How do you test an agent harness?

Test the boundary, not the prompt

An agent harness is mostly application code. It builds context, interprets model output, validates proposed actions, checks identity and policy, invokes tools, records observations, updates state, applies budgets, and decides whether the run may continue. Those responsibilities can be tested without asking a live model to behave consistently.

Replace the model with a scripted double that returns an exact sequence of proposals. Replace external tools with adapters that record calls and can return success, rejection, timeout, malformed output, or an unknown outcome after dispatch. The test then controls every input and observes every state transition.

flowchart LR
  C[Scripted context and state] --> M[Model double]
  M --> P[Exact proposal]
  P --> V[Schema and semantic checks]
  V --> A[Identity, policy, approval]
  A --> T[Tool adapter]
  T --> O[Observation or uncertainty]
  O --> S[State and trace assertions]

This seam lets a test prove that unsafe proposals produce zero external effect. It also makes failures reproducible: the same proposal, identity, policy, and state should produce the same harness decision.

Build a contract matrix

For every tool, record the tool name and version, argument schema, semantic constraints, principal, permitted resource scope, risk tier, required approval, rate and cost limits, idempotency strategy, expected observations, and log-redaction rules. Derive positive and negative tests from that matrix.

A schema-valid call can still be wrong. A path may escape the allowed directory. An account ID may belong to another tenant. A refund amount may exceed the current order balance. An approval may refer to a different operation or have expired. The harness must check current meaning and authority immediately before the effect.

Use at least these proposal classes:

• known tool with valid, authorized arguments;
• unknown tool or unsupported version;
• malformed output and extra fields;
• valid shape with invalid business meaning;
• cross-tenant, traversal, or stale-resource identifier;
• correct operation without required approval;
• replay of a previously accepted operation;
• proposal that exceeds a turn, token, time, or money budget.

Test the state machine

Model a run with explicit states such as ready, proposing, awaiting_approval, executing, observing, recovering, completed, failed, and cancelled. Then test which transitions are allowed and what evidence each transition requires.

Completion deserves its own validator. A polished final message is not evidence that the requested file exists, the database commit succeeded, or the operation stayed inside policy. The harness should enter a terminal success state only after checking the declared completion evidence. Cancellation and failure must prevent further effects.

Useful state-machine properties include:

• one accepted proposal creates at most one logical effect;
• a denied proposal creates no effect;
• a terminal run cannot execute another tool;
• an approval is bound to one exact pending operation;
• current identity and policy are checked again before execution and retry;
• every transition records enough evidence to reconstruct what happened.

Inject failures around the effect

The most important retry bug occurs when a request may have reached the external system but the response did not reach the harness. A timeout is not proof of failure. Treat the result as unknown until the harness can reconcile by operation ID or inspect the target state.

Inject failures before dispatch, during dispatch, after the external effect, while receiving the result, while persisting the observation, and while writing the next run state. Verify which failures are safe to retry, which require reconciliation, and which must stop for human review.

Also test duplicate delivery, reordered events, expired credentials, rate limits, partial tool output, oversized output, hostile content inside tool results, and loss of the process between effect and checkpoint. The trace must distinguish a tool failure from a harness failure and an unknown outcome from a confirmed no-op.

Do not ask the model to certify its harness

Harness testing is not asking a model to follow a safety prompt ten times. It is not satisfied by validating JSON against a schema, because schemas do not establish ownership, permission, freshness, or business meaning. It is not an end-to-end agent score: model capability and stochastic trajectory quality are separate concerns.

A framework's own unit tests do not prove the product policy. The application team still owns tool scope, tenant boundaries, approvals, budgets, state transitions, recovery, and terminal evidence.

Verify deterministic contracts first

Use a layered suite:

1. Unit-test pure context selection, validation, policy, budgets, and transition functions.
2. Contract-test each tool adapter against a fake or disposable service.
3. Run deterministic harness scenarios with scripted model proposals and injected tool outcomes.
4. Property-test invariants such as zero effect after denial and no action after a terminal state.
5. Run a small number of real-model integration trials to verify the boundary is connected correctly.
6. Re-run dangerous and previously failing traces as permanent regression fixtures.

Assert observable contracts rather than private implementation details. The strongest evidence is a trace that shows the proposal, the exact validation and policy decision, whether dispatch occurred, the observed outcome, the resulting state, and why the run stopped.