ABot Runtime field guide · 1.6.0
Model calibration in ABot Runtime
This guide explains how to configure one concrete model, correct its behavior at a specific runtime step, and move reusable operating guidance into external Markdown. The JSON examples come from working Luna and Gemma profiles; they are examples to study, not defaults to copy unchanged.
instructions correct one model at one step. instructionRefs attach a reusable methodology to a step for every selected profile.
Updated for Runtime 1.6.0. The downloadable Luna and Gemma profiles and methodology examples remain unchanged; adapt them to your model and verify the results. Complete guided setup on Home before using the other workspaces. This guide covers calibration after setup; see the release notes for ABot Studio, persistent SPARK chat, and context-handling improvements.
1. What belongs in a model profile
A profile identifies the provider model that is actually called. It declares physical capacity and broad generation defaults. Its calibrationobject then overrides those defaults for named semantic steps.
Keep provider identity, model id, context capacity, and the execution policy at profile level. Do not use a calibration slot to pretend that a 32k model has a larger physical context window, and do not change the execution policy merely to hide unreliable JSON from one step.
{
"label": "My model",
"provider": "ollama",
"model": "<exact-model-id>",
"contextWindowTokens": 32768,
"execution": {
"policy": "supervisor-worker-v1"
},
"generation": {
"temperature": 0.8,
"topP": 0.9
},
"calibration": {
"supervisor.decision": {
"generation": { "temperature": 0 },
"format": "json"
}
}
}
- LINE 04Exact provider id
Calibration applies to the concrete model build you invoke, not only to a friendly label.
- LINE 05Physical capacity
This is the profile's real context ceiling. Prompt projection must fit inside it.
- LINE 07Root execution contract
The policy is selected once for the request: Supervisor/Worker or Execution Agent.
- LINE 15One semantic override
Only Supervisor decisions become deterministic here. Other steps still inherit the base generation settings.
How resolution works
- The request runner selects a model profile.
- The runtime step is resolved through
models.defaults.steps. In schema v2, an omitted mapping uses the same step id. - The selected target can use a specific profile or calibration slot. A calibration overlays that profile's base settings; a target of
defaultuses the base profile instead. - The resolved invocation is observable in
model.invocation.resolved.
Check the mapping before adding instructions. The v2 starter explicitly mapssupervisor.response, worker.result, andexecution.response to default. Merely adding a same-named calibration does not change those explicit targets. To use the matching slots from a profile, merge the relevant entries below into your existing v2 config. Keep its other model, context, and step settings.
{
"models": {
"defaults": {
"steps": {
"supervisor.response": "supervisor.response",
"worker.result": "worker.result",
"execution.response": "execution.response",
"tool_payload.raw": "toolPayload.raw"
}
}
}
}
- LINE 06Activate the handoff calibration
This selects worker.result instead of the base default target. The same principle applies to the two user-facing response slots.
- LINE 08Two different names
tool_payload.raw is the runtime step; toolPayload.raw is the profile calibration slot. Keep this non-identity mapping.
2. Writing useful instructions
The instructions array is the smallest correction surface. Use it when a measured failure belongs to one model and one step. Each item should state a concrete decision rule, invariant, or stopping condition that the runtime schema alone cannot teach reliably to that model.
Do not use vague personality requests such as “be careful” or “reason better” to repair a concrete step failure. They have no observable success condition. A useful instruction names the situation, the behavior required in that situation, and the boundary that prevents drift.
Example: keeping Gemma's Worker inside one outcome
This real calibration uses low sampling and JSON output for the structured decision, then adds three corrections discovered during use. Notice that the instructions do not explain the entire Worker role; the runtime already owns that contract.
{
"calibration": {
"worker.decision": {
"generation": {
"temperature": 0.1,
"reasoningEffort": "none"
},
"format": "json",
"instructions": [
"For connected development work, preserve the planned artifact boundaries and complete every artifact and integration edge in the assigned outcome within the same Worker call, using sequential capabilities.",
"Preserve explicit artifact, storage-format, and source-of-truth constraints literally. Create and connect the requested artifact instead of embedding an equivalent substitute in another artifact.",
"Treat successful capability results as current evidence. Do not repeat a successful mutation or add optional inspection; choose return_result as soon as the assigned outcome is complete unless a capability failed or explicit verification is required."
]
}
}
}
- LINE 05Stabilize the decision
Temperature is narrowed for this JSON decision without flattening creative generation across the profile.
- LINE 08Keep the runtime schema
The instructions supplement the structured contract; they do not replace it.
- LINE 10Completion scope
Connected artifacts and their integration edges stay in the same assigned Worker outcome.
- LINE 11Preserved invariants
An exact artifact or source-of-truth requirement cannot be substituted with something merely equivalent.
- LINE 12Stopping condition
A successful mutation becomes current evidence. The Worker returns when the assigned outcome is complete instead of repeating or inspecting by habit.
An instruction has three useful parts
- Trigger
- “For connected development work…” limits the rule to the situation where it matters.
- Required behavior
- “Complete every artifact and integration edge…” defines what the model must preserve.
- Boundary or stop rule
- “Choose return_result as soon as…” prevents unnecessary actions after evidence is sufficient.
Example: give each Worker one complete plan item
Gemma's real Planner calibration makes two decisions explicit: describe all known end-state outcomes up front, then dispatch only the earliest executable item. Runtime 1.2.0 enforces the one-production-item handoff; this calibration helps the model form useful items within that contract.
{
"calibration": {
"planner.decision": {
"generation": {
"temperature": 0,
"reasoningEffort": "none"
},
"format": "json",
"instructions": [
"On the first Planner activation, enumerate the complete known execution plan before invoking a child. Every item must be an independently completable end-state outcome; never use an initial-setup placeholder, conditional or speculative work, or one item that merely repeats the full assignment. Do not defer already-known outcomes to a later extension.",
"When selecting production work for Worker, select only the earliest currently executable plan item that one Worker can finish and report as one independently completable outcome. Related artifacts may belong to one item only when they are inseparable parts of that outcome; do not select every plan item at once merely because one Worker can handle them sequentially. Preserve dependency order and select later items only after consuming the bound Worker report."
]
}
}
}
- LINE 10Plan outcomes, not setup placeholders
Account for known final states before invoking a child. Do not defer a known outcome merely because its implementation is not yet known.
- LINE 11Dispatch one item, consume its result
Select the earliest executable outcome. Several related operations may belong to it, but the whole plan must not become one oversized Worker assignment.
“Find the existing settings page and add a working theme switch” can be one bounded implementation outcome. Locating the page is a prerequisite inside that work, not a separate completed deliverable. Several files can belong to the same outcome when their integration is inseparable. Preserve the exact target and workingDirectory; when the target is unknown, include bounded discovery instead of inventing a path.
Example: report the result without replaying the work
The Worker result is a handoff to its caller, not automatically a final answer to the user. Both profiles include this rule; the excerpt below is from Luna. Use the explicit worker.result mapping above to select it.
{
"calibration": {
"worker.result": {
"generation": {
"reasoningEffort": "none"
},
"instructions": [
"Return a concise handoff to the exact caller containing the outcome, affected artifact paths or external effects, verification evidence, and any blocker that remains.",
"When work was completed through capabilities or persisted artifacts, do not reproduce file bodies, source code, diffs, tool transcripts, or previously returned capability content unless the caller explicitly requested that content in the handoff."
]
}
}
}
- LINE 08Carry the evidence forward
Report the outcome, exact affected paths or external effects, verification evidence, and any remaining blocker to the actual caller.
- LINE 09Keep the handoff bounded
Do not replay entire files or tool transcripts unless the caller asks for them.
This instruction shapes the report; it cannot make an operation successful. The runtime's workReceipt and workLineage preserve producing-call provenance across handoffs. Provenance is not proof of quality or completion: requested effects still need settled results, and any distinct verification outcome needs its own evidence.
Example: removing ambiguous continuation scope
Luna could continue a bounded file read while describing the next objective as “the remaining lines.” That phrase depends on hidden conversational context. The correction below requires an exact range derived from the visible receipt.
{
"calibration": {
"execution.decision": {
"generation": {
"reasoningEffort": "medium"
},
"format": "json",
"instructions": [
"For a continuation of a prior bounded file observation, never use unresolved relative scope such as \"remaining\", \"rest\", or \"continue\" in operationObjective. When the visible receipt reports lines A-B of N, state the exact next inclusive range B+1-N. If exact bounds are unavailable, use an exact locator or request a fresh bounded window."
]
}
}
}
- LINE 05Keep reasoning where scope is selected
The model must relate the previous bounded receipt to the next operation objective.
- LINE 07Preserve the decision contract
The correction still produces the runtime-owned structured decision.
- LINE 09A testable rule
The output must contain B+1–N, an exact locator, or a fresh bounded observation. Words such as “remaining” are explicitly invalid.
Example: raw payload authoring is a different job
toolPayload.raw does not choose a tool or return a decision object. It authors literal input for a tool after selection. Its instructions therefore describe what must be absent as carefully as what must be present.
{
"toolPayload.raw": {
"timeoutMs": 180000,
"generation": {
"temperature": 0.08,
"topP": 0.8,
"reasoningEffort": "none"
},
"instructions": [
"Return only the literal payload text requested for the selected tool.",
"Do not include JSON wrappers, tool names, params, status text, markdown fences, or commentary.",
"Derive the target artifact format from acceptedCapability.controls.path, then follow payloadContract and payloadStage exactly: return only a required selection value during location selection, only the standalone file body during complete-file authoring, or only the content for materializedParams.selection during staged editing. Do not emit enclosing markup from another format or content outside the writable scope."
]
}
}
- LINE 03Latency only
The longer timeout permits provider work; it does not improve reasoning quality.
- LINE 05Separate payload sampling
Near-deterministic authored content is isolated from the profile's higher base temperature.
- LINE 10Positive requirement
Return the literal payload consumed by the already selected tool.
- LINE 11Explicit exclusions
Wrappers, fences, status prose, and commentary would corrupt raw tool input.
- LINE 12Stage-aware boundary
The accepted path and payload stage determine whether the model writes a selection, a whole file, or one materialized region.
Vague instruction versus bounded instruction
Be more careful.Treat successful capability results as current evidence. Do not repeat a successful mutation.Names the evidence and the prohibited action.
Continue reading the file.When lines A–B of N are visible, request the exact next inclusive range B+1–N.Produces a scope that another isolated operation can execute.
Return raw output.Return only the literal payload; omit wrappers, tool names, status text, fences, and commentary.Defines both the required value and common invalid additions.
Make a good plan.Every plan item must be an independently completable end-state outcome.Gives each item an observable completion test.
If the failure is caused by the wrong output format, insufficient physical context, an unsupported provider field, or the wrong execution policy, fix that layer. More prose will only conceal the mismatch.
3. Reusable methodologies with instructionRefs
Reusable operating judgment does not need to live in the runtime kernel or be duplicated into every model profile. A request-runner step can reference one or more Markdown files. The runtime resolves them relative to the runner config and appends their content to the existing system contract for that step.
This boundary matters: a methodology may improve route selection, evidence use, planning shape, or response presentation. It cannot add an action, role, capability, or output field that the runtime contract did not already expose.
The next example is a fragment to merge into an existing v2 runner, not a complete configuration. These production methodologies are optional local examples; installing the package does not attach them automatically. Save the referenced files first. For a config at local/request-runner.config.json, the paths below point to a sibling methodologies/ directory at the project root. Adjust them if your layout differs.
{
"schemaVersion": 2,
"steps": {
"supervisor.decision": {
"instructionRefs": [
"../methodologies/supervisor-route-selection.md"
]
},
"worker.decision": {
"instructionRefs": [
"../methodologies/worker-objective-evidence.md"
]
},
"planner.decision": {
"instructionRefs": [
"../methodologies/planner-plan-shape.md",
"../methodologies/planner-project-orientation.md",
"../methodologies/planner-reviewer-boundary.md"
]
}
}
}
- LINE 05Root routing guidance
This file teaches Supervisor how to distinguish a conversational answer, bounded work, and coordinated work.
- LINE 10Production evidence
Worker receives evidence guidance, without receiving Supervisor routing rules.
- LINE 18Keep review authority separate
Planner plans production. Supervisor decides any separate Reviewer delegation after production settles.
These references belong to planner.decision, the delegated Planner in the Supervisor/Worker route. They do not carry over to planner.graph, the Execution Agent's separate advisory Planner contract. Configure guidance for the step actually used by your chosen route.
Read the actual methodology
These are excerpts from the downloadable files, not rewritten approximations. An ellipsis marks omitted text. Each file teaches one coherent judgment and states its authority boundary where confusion would be costly.
supervisor-route-selection.mdAttached to supervisor.decision# Supervisor Route Selection
Classify by the final outcome requested now, not by future-action words or the
number of steps, tools, facts, sources, sections, or comparison dimensions.
Operational length alone never selects Planner.
- Distinguish internal recollection from a fresh observation of external state.
When an offered root context action owns the needed lookup, use it directly
rather than delegating it as a child objective. Otherwise, delegate only if
an offered observation can access the required source. A recollection can
establish what was remembered, never a current external observation or effect.
[…]
- Choose Worker only when one independently completable external outcome can
be delegated without coordinating multiple final-state artifacts or effects.
Prerequisite observation or reasoning alone does not require Planner.
- Choose Planner when the request requires two or more persistent effects,
deliverables, or components that must each exist in the final state and must
be coordinated for integration, consistency, or joint acceptance, even when
they form one product.
- Choose Reviewer only for an independent assessment of supplied or delegated
work.This methodology teaches the root how to distinguish a response, a focused memory recall, one bounded production outcome, and coordinated work. Recall is a root context action when memory is enabled—not a child objective or a substitute for current external observation.
worker-objective-evidence.mdAttached to worker.decision# Worker Objective Evidence
Before every decision, separate the exact bounded objective into requirements
already established by canonical supplied results and requirements that remain.
A successful observation establishes only its returned facts. It does not
establish a requested mutation, artifact, or other external effect. A successful
settled mutation establishes the bounded production effect represented by its
result and referenced target. Intent, controls, guidance, authored content,
promises, and completion prose do not establish that effect without the settled
mutation result.
The successful mutation does not independently certify quality, style, or a
separate verification outcome. Treat the requested production effect as complete
without inspecting the same target merely to audit the payload you just authored.
Inspect it only when this Worker was explicitly assigned a distinct verification
outcome, when current content absent from supplied context is needed for a later
different mutation, or when the mutation failed or was incomplete.
For a connected observation-to-reasoning-to-effect objective, a settled
observation becomes input to the remaining reasoning or effect; it never
closes the chain. Continue the same Worker call until every downstream required
effect has its own successful settled result.
[…]This separates observation from effect. Reading a file proves what it contains; it does not prove that a requested edit happened. That distinction prevents premature completion and repeated operations.
planner-reviewer-boundary.mdAttached to planner.decision# Planner Reviewer Boundary
Reviewer authority belongs to Supervisor, not Planner. Planner never creates a
review plan item, invokes Reviewer, or waits for a review verdict. Missing
observation, synthesis, artifact, or external effect remains production work.
Words such as review, compare, inspect, or verify in the requested deliverable
do not select the Reviewer role. If producing that deliverable still requires
work, delegate the complete remaining outcome to Worker. Once production is
settled, return the process to Supervisor for any separate audit decision.In the Supervisor/Worker route, Planner coordinates production; Supervisor owns any separate Reviewer delegation. A user asking to compare or verify something may still be asking for production work, not an independent audit. This file is shown in full.
response-ux.mdAttached to supervisor.response · execution.response# Root Response Experience
Fulfill the current user request first. Shape the response, level of detail,
ordering, and tone around what is useful at this point in the conversation,
rather than following a fixed response template.
Write clearly, directly, and naturally. Do not treat the response as terminal
by default. Look for a natural way to create conversational momentum: deepen
the topic, surface a meaningful implication or connection, or ask one specific
follow-up question grounded in what the user actually said. Avoid obligatory
summaries, repeated conclusions, fixed closings, generic offers, canned
questions, manufactured warmth, and artificial conversation extension.
Use editorial judgment without changing the accepted request or inventing
facts. Current user instructions and supplied evidence remain authoritative.
This guidance affects presentation only; it grants no routing, action, or
completion authority.This is presentation-only guidance. It can improve tone and usefulness, but the final sentence makes the authority boundary explicit: response style cannot authorize another action or claim completion.
For existing-project work, target identity and target content are different. Discover a missing target within the assigned directory. Once it is known, do not add another read solely to recover content that the chosen mutation capability already supplies. Reuse settled observations unless the target changed, the earlier result was incomplete, or new required scope is missing.
Attach response guidance to the response steps
Fresh initialization supplies response-ux.md andmemory-informed-response.md for both root response steps. The current response guidance allows a grounded follow-up or useful connection, without canned questions or artificial conversation extension. Existing local copies are not replaced by a package upgrade.
{
"steps": {
"supervisor.response": {
"instructionRefs": [
"../methodologies/response-ux.md",
"../methodologies/memory-informed-response.md"
]
},
"execution.response": {
"instructionRefs": [
"../methodologies/response-ux.md",
"../methodologies/memory-informed-response.md"
]
}
}
}
- LINE 03Supervisor route
The methodology attaches to the response step independently of the profile calibration target.
- LINE 09Execution Agent route
Attach the same presentation guidance to execution.response so both root policies receive it.
Focused memory recall is a root decision
Memory is optional reference context, not a new instruction or evidence of completion. In 1.3.0, an enabled Supervisor or Execution Agent can request a focused recall through its root decision contract and then continue the same decision. It does not invoke a plugin or delegate a child. Current user instructions and current evidence remain authoritative; attaching the memory-informed presentation file does not enable memory storage.
Before merging the fragment below, use the documented memory onboarding flow to select and probe an embedding model. It creates the referenced embedding profile; the fragment shows the recall budget alongside that existing binding. In Web onboarding, a successful embedding setup also enables native memory and disables the separate Memory plugin without deleting its stored data. Skipped or failed setup leaves the plugin selection unchanged. See the long-term memory guide.
{
"longTermMemory": {
"enabled": true,
"maxRecallCallsPerRequest": 5,
"embeddingProfileId": "memory-embedding"
}
}
- LINE 03Still opt-in
Long-term memory remains disabled until the consumer explicitly enables and configures it. Merge this fragment only after declaring the referenced embedding profile.
- LINE 04Bounded per request
The default permits at most five focused root recalls in one user request. Earlier results remain available after the limit.
- LINE 05Existing retrieval service
Explicit recall uses the configured embedding profile and the same Runtime-owned memory pool.
A recall query is limited to 1,024 characters. Its result contains at most six complete records within a 6,000-character serialized budget, and may report omitted records. empty means that lookup found no match;unavailable does not prove the memory pool contains nothing useful. Recollection can establish what was remembered, never the current state of an external system or a completed external effect.
Download only the files you choose to reference, review them, and adapt the paths:
supervisor-route-selection.mdworker-objective-evidence.mdplanner-plan-shape.mdplanner-project-orientation.mdplanner-reviewer-boundary.mdresponse-ux.mdmemory-informed-response.md
What the loader enforces
- References must point to Markdown files and are resolved relative to
request-runner.config.json. - A step may load at most eight unique references.
- Each file is limited to 32,000 characters; all files for one step are limited to 48,000 characters in total.
- The methodology is appended once to the existing system message under an explicit supplementary contract.
- Its estimated tokens are reserved before history selection, so the guidance cannot silently overflow the prompt.
- Reference paths and content hashes are exposed as invocation metadata for traceability.
instructions or instructionRefs?
instructionsUse runner instructionRefsA specific model repeatedly fails one known semantic step.
The operating rule should apply across compatible model profiles.
The correction is short and tightly coupled to sampling, format, or provider behavior.
The guidance explains a reusable method such as routing, evidence, plan shape, or response UX.
Example: Luna must turn a prior line receipt into the exact next range.
Example: every Worker must distinguish an observation from a completed mutation.
4. Reading the Luna and Gemma profiles
These profiles solve different problems. Luna uses execution-agent-v1and keeps reasoning effort on decision boundaries. Gemma usessupervisor-worker-v1, lowers sampling for structured role decisions, and relies more heavily on explicit instructions. Neither profile is a universal recommendation for every model from the same family.
Built-in runtime changes do not need to be copied into every model profile. Version 1.3.0 adds focused recall to the existing Supervisor and Execution Agent decision contracts; it does not add a model calibration slot. It also preserves accepted Supervisor recommendations through response authoring. Add local instructions only for a specific remaining failure you can observe.
Luna: allocate reasoning by authority
{
"execution": {
"policy": "execution-agent-v1"
},
"generation": {
"reasoningEffort": "medium"
},
"calibration": {
"execution.decision": {
"generation": {
"reasoningEffort": "medium"
},
"format": "json"
},
"auditor.decision": {
"generation": {
"reasoningEffort": "none"
},
"format": "json"
},
"toolPayload.raw": {
"generation": {
"reasoningEffort": "none"
},
"instructions": [
"Return only the literal payload text requested for the selected tool."
]
}
}
}
- LINE 03Direct root
Execution Agent owns the tool loop and final response; Planner and Auditor remain advisory.
- LINE 11Decision effort
Medium reasoning is retained where the next action is selected.
- LINE 17Bounded audit
Auditor evaluates supplied criteria and evidence without reopening the whole request.
- LINE 26Literal payload
No reasoning budget is spent on explaining text that must be consumed directly by a tool.
Open the complete Luna profile
Gemma: narrow structured responsibilities
{
"generation": {
"temperature": 1,
"topP": 0.95
},
"calibration": {
"supervisor.decision": {
"generation": {
"temperature": 0.2,
"reasoningEffort": "none"
},
"format": "json"
},
"worker.decision": {
"generation": {
"temperature": 0.1,
"reasoningEffort": "none"
},
"format": "json"
},
"planner.decision": {
"generation": {
"temperature": 0,
"reasoningEffort": "none"
},
"format": "json"
},
"toolPayload.raw": {
"generation": {
"temperature": 0.08,
"topP": 0.8,
"reasoningEffort": "none"
}
}
}
}
- LINE 03Expressive base
General generation keeps temperature 1; individual decision steps override it.
- LINE 09Supervisor
Lower sampling and JSON make root routing more stable.
- LINE 16Worker
Capability selection and one bounded production result use a separate decision calibration.
- LINE 23Planner
Dependency coordination is the most deterministic step in this excerpt.
- LINE 30Payload
Artifact text is treated separately from structured capability controls.
5. A calibration loop you can measure
Begin with an observed failure in a named modelStep, not with a general impression that the model needs a longer prompt. Change one class of setting at a time so the result tells you which lever mattered.
- Observe
Run one representative request and locate the failing modelStep in resolved events.
- Isolate
Pair provider request and response by invocation id when the failure is unclear.
- Change one lever
Adjust generation, context, format, instructions, or timeout—not several at once.
- Repeat
Use the same request and compare structured events plus the actual artifact or effect.
- Generalize
Test nearby inputs. A fix that encodes one prompt is not reusable calibration.
Provider latency, malformed structured output, missing context, and poor role judgment are different failure classes. A longer timeout only addresses the first. A larger declared context value is invalid unless it matches the physical model. An instruction is worth keeping only when the same request improves and nearby requests do not regress.
6. Step reference
Choose the observable success condition for the step before choosing a setting.
supervisor.decision · worker.decision · planner.decision · planner.graph · execution.decision · reviewer.decision · auditor.decisionSuccess: Complete structured output, stable routing, and bounded authority.
Try first: Required format, then deterministic sampling or reasoning effort.
supervisor.response · worker.result · execution.responseSuccess: Useful prose with truthful claims and no replay of internal work.
Try first: Response-specific instructions and intentional sampling.
capability.controls · toolPayload.rawSuccess: Valid controls and literal payloads that tools can consume directly.
Try first: Separate structured controls from raw payload authoring.
context.compact · degraded.finalizationSuccess: Preserved facts and safe, neutral recovery when a normal answer is unavailable.
Try first: Format fidelity, bounded context, and conservative wording.
Before keeping a change
- The failing
modelStepis known. - Only one setting class changed: generation, context, format, instructions, or timeout.
- The same request improved in observable output, events, or external effects.
- Nearby requests did not regress.
- The instruction does not encode one prompt's wording as a special case.
For the complete contracts, continue with the configuration reference and architecture documentation.