Agent Architecture and Orchestration
Agent Harness Engineering
What it is
Designing the executable environment around a model so that an agent can make useful progress: assemble task context, expose permitted tools, execute calls, retain work records, verify outcomes, and recover when a turn or process fails. The harness is a versioned system of code, configuration, and policies. Instructions describe desired behavior; the runtime determines which operations can actually occur.
Harness Engineering is used at different scopes, from one agent's runtime to the repository and feedback environment surrounding a coding agent. State the boundary you are designing. An evaluation harness runs measurements; an agent harness runs the work being measured.
The component map
| Boundary | Responsibility | Evidence to retain |
|---|---|---|
| Task intake | Bind the objective, acceptance criteria, caller identity, and allowances | Task revision and authority granted |
| Context assembly | Select instructions, history, knowledge, and observations for this turn | Source/version references and projection policy |
| Model interface | Submit requests and interpret answers or proposed calls | Model configuration and response |
| Tool dispatch | Validate arguments and permissions, execute inside the appropriate boundary | Call identifier, inputs, outcome, and effect receipt |
| Work state | Store progress and pending operations outside model context | Durable record and continuation position |
| Verification | Check the resulting artifact or external state against the objective | Verdict, criterion version, and supporting observations |
For example, a ticket assistant receives an authorized request, obtains project facts through a connector, drafts a ticket, validates its fields, and submits the exact approved payload. Its harness binds the connector credentials, scopes the workspace, and records the returned ticket identifier. A server exposing the connector alone does not supply this whole runtime.
Harness, graph, and loop boundaries
These are overlapping design views. The harness supplies the execution environment. An execution graph makes steps and permitted transitions explicit. An inner loop advances model and tool turns; an outer loop selects work and evaluates runs. A graph or loop can use the same harness services. None of these labels requires adding multiple agents or changing model weights.
Designing the assembly
Start with one successful task and one realistic failure. Draw where identity, context, state, and effects cross component boundaries. Specify what each component consumes and produces, and which record is authoritative after a crash. Keep acceptance checks outside the agent's ability to rewrite them during the run.
Record the harness configuration with each run: context policy, tool schemas, permission rules, runtime image, state format, and checker revision. A comparison that changes these along with the model cannot attribute improvement to the model alone. Diagnose failure at the first broken boundary: absent evidence, unsuitable context, invalid tool selection, denied or failed execution, lost state, or an inadequate acceptance check.
Key decisions
- Which machinery is owned by the application and which is delegated to a runtime library.
- How workspace lifetime, credential custody, and state scope align with a run or tenant.
- Whether recovery reconstructs a context from durable observations or repeats an uncertain action.
- How changes to tool contracts and context policies affect runs already in progress.
- What the agent can inspect about tests, logs, and environment health to diagnose its own work.
- Whether a harness adjustment improves task success without unacceptable cost or new failure modes.
Failure modes
- Tool access is advertised in a prompt but no dispatch boundary enforces the permitted operations.
- A new context policy drops a prerequisite and the regression is attributed to model quality.
- The work record and workspace refer to different revisions after resumption.
- A checker accepts a fluent completion message without inspecting the requested artifact.
- A runtime upgrade changes several defaults, but only the model identifier is stored with results.
- A recovery path repeats a committed external write because no effect receipt was retained.
Related capabilities
- Dynamic Prompt Assembly — request-time context composition
- Tool Execution Sandbox — confinement of executed work
- Shared State Management — authority for the active work record
- Agent Graph Engineering — explicit execution structure
- Loop Engineering — work and verification cycles across runs
- Agent Trajectory Evaluation — evidence for diagnosing agent decisions
Applies: Production readiness · Design questions