What is an agent harness?

The harness in the complete stack

The model sees the context supplied for one call and returns generated output. The harness is the runtime that turns repeated model calls into a controlled run. The host application still owns the user experience, principal, business rules, and system of record; the environment owns the files, services, accounts, and effects the run can reach.

Read the blue loop as controlled execution: the model participates in the run, while the surrounding harness owns how proposals become observed effects.

flowchart TB
  U[Host goal + principal + policy] --> C[Harness context]
  S[Canonical state] --> C
  E[Retrieved evidence] --> C
  C --> M[Model]
  M --> P[Proposed action or answer]
  P --> V[Schema and semantic validation]
  V --> A[Authorization and approval]
  A --> X[Bounded executor]
  X --> R[Observed result or effect]
  R --> S

This separation matters because a probable next token cannot authenticate a user, lock a file, enforce a spending limit, or prove that an external effect occurred. It also keeps “agent” from becoming a label for the entire product: the model proposes, the harness operates the loop, and the host decides what the run means for the product.

Core responsibilities

A production harness usually owns:

• Context: which instructions, history, evidence, and tool definitions enter the next call.
• State: task status, durable identifiers, attempts, approvals, budgets, and artifacts.
• Tools: schemas, semantic validation, credentials, resource scopes, and output sanitation.
• Policy: whether the current principal may perform the proposed operation now.
• Lifecycle: turn limits, timeouts, cancellation, retry, reconciliation, and terminal states.
• Trace: observable events needed for debugging, evaluation, audit, and recovery.

Frameworks can supply useful defaults, but the product team still owns the semantic contract. A generic framework cannot know whether a refund, deployment, message, or file write is appropriate for a particular user and state.

One turn is a state transition

A reliable loop makes intermediate states explicit instead of hiding the task inside a recursive function. One turn commonly moves through:

1. load the current run revision, principal, task state, and remaining budget;
2. construct a versioned context and call the declared model;
3. parse the result as an answer, tool proposal, clarification, refusal, or malformed output;
4. resolve resource identifiers and evaluate schema, semantic constraints, authorization, and approval;
5. execute one allowed operation in the appropriate sandbox or service;
6. record the policy decision, operation identity, result, effect evidence, cost, and timing;
7. commit the observation and next run state with concurrency control;
8. decide whether another turn is permitted or a terminal condition has evidence.

The run revision prevents two workers from both advancing the same state. Operation IDs connect a proposal to one dispatch and its eventual result. Idempotency keys belong to the effect boundary, not to free-form model text. A cancellation flag and deadline are checked before expensive calls and again before effects.

The model can suggest “done,” but the harness owns the transition. Completion may require a schema-valid artifact, a passing test, persisted state, no unresolved effect, or human acceptance. Likewise, denial is an observation the model can respond to; it is not permission to disguise the same action through another tool.

Classify failure before recovery

Model APIs, policy services, tools, state stores, and networks fail differently. Preserve at least:

• rejected proposal: invalid, unauthorized, or not approved;
• known operation failure: execution returned a trustworthy failure with no claimed effect;
• known success: the required effect and result were observed;
• unknown outcome: dispatch may have crossed the effect boundary but confirmation was lost;
• run interruption: cancellation, deadline, resource exhaustion, or infrastructure loss;
• harness defect: malformed state, impossible transition, or violated invariant.

A transient model-call failure can often be retried within a bounded budget because it has not changed the user's business state. A timed-out payment, message, deployment, or file write cannot be treated the same way. Reconcile by stable operation identity or inspect the target state before considering another dispatch. “No response” is evidence about communication, not evidence that nothing happened.

Choose one retry owner. Provider SDK, harness, job queue, and workflow engine retries can multiply each other. Backoff, jitter, attempt limits, total deadlines, and cancellation must appear in the trace so evaluation can distinguish a resilient recovery from a hidden retry storm.

Context is constructed

A large context window does not remove the need for a harness. Capacity does not decide relevance, authority, freshness, ordering, or whether retrieved text is trusted. The harness must label and select evidence, refresh volatile facts, and keep credentials outside model input.

Summaries are derived state. Canonical business records, policy, and permissions should remain in authoritative stores and be checked again before consequential effects.

Treat all retrieved or tool-returned content as data with provenance, even when it contains instruction-like language. Context precedence can guide the model, but the permission boundary must still reject unauthorized effects if the model follows an injected instruction.

Where the model stops

The harness is not merely a prompt template or a loop around an API call. It is not proof that the agent is safe simply because tool calls are valid JSON. Schema validity does not establish ownership, permission, freshness, business meaning, or user approval.

The harness should also avoid pretending to expose private model reasoning. Useful traces record proposals, evidence, decisions, operations, observations, and concise rationales tied to policy—not hidden chain-of-thought.

Verify the runtime as a state machine

Test the harness separately from model quality:

1. Replace the model with deterministic proposals, including invalid and hostile calls.
2. Verify context ordering, provenance, token budgets, deletion, and stale-data refresh.
3. Exercise cross-tenant identifiers, path traversal, excessive amounts, and expired approvals.
4. Inject failure before dispatch, after dispatch, during observation, and during state persistence.
5. Prove retries are idempotent or reconcile unknown outcomes before retrying.
6. Assert every terminal state has sufficient evidence and an explicit reason.
7. Confirm logs support debugging without exposing secrets or unnecessary personal data.

A harness test should show that unsafe proposals produce zero effect and that uncertain effects remain uncertain until observed.