A model can request a shell command, but it cannot run the command by itself. It can propose a file change, but it cannot decide which files the application permits it to read. It can write a plan, but it cannot preserve progress after a worker stops.
An agent harness supplies instructions and controls for model-directed work. In some products, the term also refers to the runtime that manages context, state, tool calls, and recovery. Teams should state which meaning they use because the boundary varies across frameworks.
This article uses “harness” for the instructions, guardrails, and runtime controls that manage the agent loop. It treats the model, tools, and external environment as separate components.
The harness manages each model turn
Before a model call, the harness prepares the goal, instructions, current run state, relevant context, and available tool definitions. After the call, it parses the response, checks any tool request, records the result, and decides whether the run may continue.
A basic turn includes these operations:
- Load the run identity, goal, state, and remaining budget.
- Select the instructions and context needed for the next decision.
- Provide the tools available at that point in the run.
- Call the model and parse its response.
- Check the proposed action against policy and approval state.
- Send an approved request to the relevant tool or environment.
- Record the observation and update the run state.
- Continue, stop, retry, or request human input.
The implementation may use one process or several services. The important point is that the model does not control these operations. The harness and application code decide what context enters the call and what effect a tool request may have.
Anthropic describes a related four-part system: model, harness, tools, and environment. The harness provides instructions and guardrails. Tools provide defined actions. The environment provides the state and feedback the agent acts on. Keeping these components separate makes failures easier to identify.
Context selection affects every decision
The model can use only the information in its current context. The harness must decide which instructions, messages, documents, memory records, observations, and tool definitions to include.
Loading all available information is not a reliable strategy. Irrelevant records use context space and can distract from current evidence. Similar documents may conflict. A large tool catalog can make selection harder. Long conversations may place important facts in positions that models use less well.
Context should preserve authority and source. System rules should remain separate from user requests. Organization policy should retain its version and source. Web pages, emails, and retrieved documents should remain labeled as untrusted content rather than instructions.
Just-in-time retrieval can reduce context use. The harness first provides compact identifiers or search results. It loads the full document or record when the next decision needs it. This approach works well for large tool outputs and file systems, though not every task requires it.
Compaction can help long runs continue across context limits. A useful compacted state records completed work, open questions, current files or artifacts, and the next verified step. Exact facts such as identifiers, approvals, budgets, and tool outcomes should remain structured. A summary should not replace authoritative run state.
Long-running agents need durable progress
A conversation transcript does not provide enough state for a resumable task. The system needs a durable record of completed actions, active work, artifacts, pending approvals, budgets, errors, and component versions.
Long-running coding agents provide a clear example. A run may cross several model contexts or worker processes. An initialization step records the environment. A progress record tells a later turn what changed, which tests ran, and what remains. The next turn should verify this state rather than assume the summary is correct.
Initialization should inspect the current environment before changing it. For a coding task, this can include the repository status, active branch, existing tests, and relevant instructions. For an external workflow, it can include the current record version and pending operations. This prevents a resumed run from treating an old summary as current state.
Progress records should be concise and specific. Record completed changes, files or records affected, verification results, unresolved problems, and the next intended step. Avoid general notes such as “work is mostly complete.” A later process needs facts it can check.
Recovery must distinguish three outcomes. A confirmed action succeeded. A failed action did not complete. An unknown outcome may have completed even though the worker lost the response. This distinction matters for any tool with external side effects.
Suppose an agent sends a message and the process stops before it records the provider response. A retry may send the message twice. An idempotency key lets the provider recognize the repeated request. A provider operation ID can help the harness check what occurred before trying again.
Long-running or resumable work should use durable checkpoints. A checkpoint records the latest confirmed state. The system should save it at defined points and reconcile external effects before resuming. A checkpoint alone cannot undo a side effect that occurred after the last save.
Concurrent runs also need conflict handling. If two agents update the same record or file, the second operation should detect that its starting version is stale. Version checks, leases, or serialized access can prevent silent overwrites. Use the simplest method that fits the shared resource.
Policy must remain outside model instructions
The harness can explain operating rules to the model, but deterministic software must enforce them. A prompt that requires approval for production changes does not prevent an unsafe call. The execution path must check the approval.
Each request should carry the acting user, organization, delegated role, task, and target resource. The policy layer can then decide whether that principal may perform the operation now. Schema validation checks whether arguments have the correct form. Authorization checks whether the action is permitted.
Credentials should remain outside the prompt and model response. A tool broker can select a short-lived credential scoped to the current user and operation. The model requests an action without receiving the secret that performs it.
For consequential actions, use a proposal and execution step. The proposal includes the exact target, change, and relevant evidence. A person or deterministic rule approves that proposal. The executor rejects changed arguments or an expired approval.
Sandboxing provides another enforced boundary. Instructions can ask an agent to stay inside a workspace. Filesystem mounts, network policy, resource limits, and process isolation determine what the generated code can reach.
Errors and stopping conditions need explicit rules
Tool errors should tell the harness what happened without exposing secrets. Stable categories such as not_found, permission_denied, stale_version, and outcome_unknown support different recovery steps.
The harness should not retry every error. A transient read may be safe to repeat. A write with an unknown outcome requires a status check. Repeating the same model call with unchanged context may reproduce the same mistake. The harness can add the error details, narrow the tool choice, or request review.
Stopping is part of normal operation. The harness should stop when the task completes, the user cancels, the budget ends, progress stops, or required information is missing. Limits can cover turns, time, cost, repeated failures, and allowed action classes.
When a run stops, preserve partial work and report confirmed results separately from intended results. Do not describe an unconfirmed external change as complete. If a run needs human input, identify the decision or permission required.
Budgets should also appear in run state. The model may need to narrow the task before time or cost ends. A controlled stop with useful partial work is better than ending during an action without a final status.
Evaluate the harness as part of the agent system
Final answers do not show whether context retrieval, policy, tools, or recovery worked. The evaluation needs the full trial: starting state, context sources, model requests, policy results, tool observations, and final environment state.
Hold the model constant when testing a context or tool change. Hold the task and harness constant when comparing models. Measure task success, constraint violations, tool errors, retries, turns, latency, and total cost.
Test context compaction and resume behavior directly. Stop a run at known points, start it in a new process or context window, and compare the final state with an uninterrupted trial. Include a tool timeout with an unknown outcome and a changed external record. These cases show whether the harness verifies state before continuing.
Frameworks can provide model adapters, state storage, and tool schemas. They can also hide prompt construction, retries, or state transitions. A team should be able to explain the path from user request to external effect even when a framework implements part of it.
Start with one explicit loop, a small tool set, and a durable run record. Add routing, queues, parallel work, and long-term memory when evaluation shows a need. Each new component adds another state and failure path that the team must operate.
An agent harness provides the instructions, guardrails, and runtime controls for model-directed work. It selects context, applies policy, records progress, handles errors, and decides when the run continues. Clear boundaries between the harness, model, tools, and environment make the system easier to test and control.