Skip to content

Guided tour

FabrCore 2.0 · Release and package availability

These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes

MODULE 06 · LESSON 6.6

Tune the harness without changing its agent class

Tune harness behavior through a precise configuration contract.

Lesson 38 of 86 · FabrCore 2.0

Overview

Defaults are applied first, documented _Harness* arguments next and the configure callback afterward. Code wins over args. If no loop is explicitly selected, the wrapper chooses its todo/background fallback. Explicit none is how to request no outer loop.

Precedence explains apparently ignored settings

The wrapper starts with defaults, reads documented _Harness* arguments, then runs the code configuration callback. The callback can override the argument value. A loop fallback applies when no explicit mode was selected. Therefore, omitting _HarnessLoop is not the same as explicitly choosing none. Inspect both code and Args when a tuning change seems ineffective.

Configuration changes must reach the active instance

A blueprint is a definition; an already running instance can retain its old configuration. Ensure creates missing instances and can leave existing ones unchanged. Use an explicit update/reconfiguration when retuning. Keep argument names case-sensitive, and separate exact-version skill validation from permissive parsing of ordinary numeric/boolean options.

Apply harness arguments deliberately

  1. Use the complete argument table in the reference to set modes, todos, loop evaluators, marker/judge settings, background handles/timeouts, skills, per-request iterations, instructions and persistence.
  2. Keep keys case-sensitive and verify parser behavior. An empty _HarnessInstructions intentionally removes the preamble; malformed exact-version skill references fail initialization.
  3. Apply an update/reconfiguration to existing agents when changing behavior. An ensure-only blueprint does not necessarily retune an already-created instance.
researcher instance definition · apply using explicit reconfiguration 
{
  "Handle": "researcher",
  "AgentType": "researcher",
  "Models": "default",
  "Plugins": [
    "requests"
  ],
  "Args": {
    "_HarnessDefaultMode": "plan",
    "_HarnessTodo": "true",
    "_HarnessLoop": "todo",
    "_HarnessLoopMaxIterations": "4",
    "_HarnessMaxIterationsPerRequest": "5"
  }
}
Argument keys
Key Type Default Effect
_HarnessMode bool true Registers mode_get / mode_set and plan/execute instructions
_HarnessDefaultMode string plan Initial mode for a fresh session and non-AgentMessage run paths
_HarnessTodo bool true Registers the todos_* tools
_HarnessLoop csv todo (+ background when delegates exist) Loop evaluators — see below
_HarnessLoopMaxIterations int 10 Iteration cap. Clamped to at least 1
_HarnessLoopMarker string — Completion marker. Required by loop mode marker
_HarnessLoopJudgeModel string the agent's own model Chat client config for loop mode judge
_HarnessLoopJudgePrompt string framework default Judge instructions for loop mode judge
_HarnessBackgroundAgents csv of handles — Agents the model may delegate to
_HarnessBackgroundTimeoutSeconds int 120 Bound on one delegation. Values below 1 are ignored
_HarnessBackgroundWaitTimeoutSeconds int 300 Bound on one wait-tool call; timeout leaves tasks running. Values outside 1–4294967 are ignored
_HarnessSkills csv of name@version — Principal-scoped immutable skills loaded from Host typed Storage
_HarnessMaxIterationsPerRequest int 40 Function-invocation iterations within one model request
_HarnessInstructions string built-in preamble Replaces the preamble. **Empty string drops it entirely**
_HarnessSessionPersistence bool true Persists the session across turns and deactivations

Read back and observe a changed limit

  1. Record the existing instance configuration and its _HarnessLoopMaxIterations. Apply a changed value using update/reconfiguration, then read the instance configuration again.
  2. Run the same controlled multi-step task and inspect the stopping reason and iteration count. If the behavior disagrees with Args, inspect the configure callback for an overriding value.
  3. Test explicit _HarnessLoop=none on a separate instance. Confirm it does not acquire the implicit todo/background loop merely because the key was omitted.

The comparison connects the stored definition, effective instance configuration and observed execution. All three are needed to establish that retuning actually took effect.

If the result is different

Invalid combinations such as todo-loop with todos disabled fail intentionally. Unknown numeric/bool values can fall back, so verify effective behavior rather than relying on typo detection.

Go deeper

Explore the related documentation.