Agent evaluation harness development
Build a harness that preserves comparable evidence across agent revisions
Manual reruns cannot establish whether a prompt or tool change altered behaviour. The decision is how to build a harness that preserves comparable evidence across agent revisions. The work begins with your actual workflow and looks for the evidence that separates intended behaviour from a consequential exception. It is particularly relevant to evaluation engineers and platform owners. A useful outcome is an explicit account of what was examined, what remains uncertain, and which decision the evidence can support.
The release evidence relationship
- Runner code
Establish the basis for fixture contract.
- Run identity
Retain versions and setup with each execution.
- Runner architecture
Retain the scoped finding and its unresolved dependencies.
Decision
Frame the decision around fixture contract
Questions and the evidence they need
- Fixture contract
- Inspect runner code for the relevant constraint or observation.
- Run identity
- Inspect configuration manifests for the relevant constraint or observation.
- Teardown check
- Inspect fixtures for the relevant constraint or observation.
The decision is how to build a harness that preserves comparable evidence across agent revisions. This is relevant to evaluation engineers and platform owners when manual reruns cannot establish whether a prompt or tool change altered behaviour. Name the affected workflow, the consequence of a wrong decision, and the owner who can act on the result. The initial discussion should establish which evidence is already available and which uncertainty is material enough to investigate.
The specific failure hypothesis is that test setup changes between runs and is mistaken for an agent regression. It remains a hypothesis until examined in the deployment. Existing internal tests or operating records may already resolve it; identify the uncovered question before commissioning additional work.
Mechanism
The harness must distinguish agent failure from runner failure
Relationships within release evidence
- Fixture contract
- Fix the retrieval and tool conditions being compared.
- Run identity
- Retain versions and setup with each execution.
- Teardown check
- Expose incomplete runs and residual test state.
What this specialty examines
A harness needs explicit contracts for setup, execution, observation and teardown. Preserve the case identifier, configuration, tool fixtures, timestamps and final state independently of presentation. A run that never reached the agent should remain a runner failure, distinguishable from an agent’s failed task.
The review should run a known fixture through the harness twice, vary one dependency and inspect recorded configuration and outcomes. Identify the normal route, relevant exceptions and the authoritative record of the outcome. Inspect the relevant business-system record, enforcement event or process evidence alongside any reported status. Keep incomplete cases visible, with an explanation of what their absence prevents the owner from concluding.
The tradeoff to make explicit
For this decision, realistic integrations improve relevance while deterministic fixtures improve diagnosis. Compare the available design or operating choices against the same intended outcome. If one option removes a required control or changes the task boundary, describe that difference before treating its apparent simplicity, speed or lower effort as an improvement. The decision should expose the tradeoff instead of burying it in an aggregate score.
Preparation
Connect the working inputs to the boundary being examined
Evidence packet for fixture contract
Illustrative working format
- Runner code
- Identify provenance and the specific decision this material can inform.
- Configuration manifests
- Match this description to the deployed or proposed boundary being examined.
- Fixtures
- Keep expected behaviour and the limits of the constructed example explicit.
- Tool mocks
- Identify provenance and the specific decision this material can inform.
Start with runner code, configuration manifests, fixtures, tool mocks and retained execution traces. Identify the owner, revision and operating context of each source. Sanitised examples may support initial design, but differences from actual conditions should remain explicit. Where direct access is unsuitable, a customer-controlled evidence or execution route may be considered, with agreed handling and retention.
The scope also needs the release owner, agreed expectations for a representative task case, and the authority to inspect the relevant boundary. Specify what evidence would distinguish the failure in which test setup changes between runs and is mistaken for an agent regression from acceptable behaviour. If stakeholders disagree about intended behaviour, resolve the interpretation before classifying the observed difference as a defect.
How the work proceeds
Carry fixture contract through to an accountable finding
From the scoped material to a decision record
- Runner code
Separate hard constraints from graded preferences.
- Run identity
Apply the scoped check to teardown check.
- Runner architecture
Record the evidence, open dependencies, and the owner’s next decision.
Prepare the evaluation cases
Work with evaluation engineers and platform owners to assemble runner code, configuration manifests, fixtures, tool mocks and retained execution traces. Select a normal task, a consequential exception and a case with insufficient information. Identify the relevant requirement and expected result for each, then mark which outcomes need human adjudication. The preparation output is a case packet that separates blocking behaviour from graded quality preferences before any comparison is run.
Run and review the comparisons
Test the measuring system with known outcomes before trusting its reports. Include a deliberately failing fixture and a missing dependency so the team can see whether errors are retained correctly. Reproducibility means knowing which conditions were reproduced, including any live components that remain variable.
Choose the release or evaluation change
Use the reviewed cases to produce a proposed runner architecture with fixture contracts, result schemas and reproducibility checks. Distinguish a product defect from a missing test, an ambiguous requirement or an unreliable measuring method. For each, name the proposed correction and the case that would check it. The release owner can then decide whether to change the implementation, improve coverage or restrict the intended use while a specific gap remains.
Indicative artefact
Make the runner architecture usable by its owner
Runner architecture
Illustrative working format
- Runner architecture
- Identify the assessed workflow, revision, and decision boundary.
- Fixture contracts
- Retain selection rationale, accepted alternatives, and unexamined task conditions.
- Result schemas
- Link observations and counterevidence to the case, configuration, and conclusion limit.
A useful decision artefact is a proposed runner architecture with fixture contracts, result schemas and reproducibility checks. Supporting material may include selected cases, configuration or process records, evidence references, a disagreement log and prioritised actions. Retain the case selection rationale and material disagreements alongside the result; otherwise the result may be mistaken for complete coverage.
Illustrative scenario
Examine teardown check through a constructed exception
A constructed case and its decision paths
Illustrative scenario
- Fixture contract
Two revisions receive different retrieval fixtures during an apparent regression.
- Run identity
Freeze retrieval and tool fixtures before comparing revisions.
- Teardown check
Investigate the agent difference only if it survives the controlled setup.
Consider a fictional situation: a developer compares two agents while one silently uses a newer retrieval collection and different tool responses. The scenario is illustrative, with no client engagement, executed test or measured improvement implied.
In the two-agent comparison, first freeze the retrieval collection and tool responses. If the apparent difference disappears, the harness has prevented an unsupported model conclusion. If it remains, inspect the recorded actions before attributing the difference to a particular component.
Scope and next action
Keep the conclusion within selected task cases
Confirm fit before the next commitment
- Fixture contract
- This review is limited to selected task cases.
- Runner code
- The relevant owner must confirm access and the intended operating conditions.
- Runner architecture
- The customer retains the release decision.
A result applies to the recorded configuration and selected cases. It does not establish universal agent competence or authorise release. Any engagement depends on an agreed scope, qualified team, authorised access and confirmed availability. Bring the affected workflow, its current configuration or process, the triggering change and the evidence already available. The immediate scope question is prompted by the situation in which manual reruns cannot establish whether a prompt or tool change altered behaviour; confirm which missing observation would change the owner’s next action.
Ways to engage
Related engagement scopes
AI Agent Evaluation Evidence Diagnostic
Find the gaps between your release decision and the evidence behind it. Start with one agent workflow and a bounded set of questions.
AI Agent Evaluation Foundation
Turn scattered tests into a repeatable release discipline. Connect the behaviours that matter to datasets, evaluation criteria and evidence your team can maintain.
AI Long-Horizon Agent Evaluation
Examine what changes when an agent keeps working. Evaluate accumulated state, recovery and goal adherence across extended tasks.
Continue exploring
Related insights and resources
Engineer the harness, not just the prompt
Define the contracts around an agent's decisions: what state it trusts, which actions can execute, how interrupted work resumes, and what evidence an operator needs to recover safely.
What would justify releasing this agent?
Replace a single pass rate with a reviewable chain of requirements, cases, observations and judgements. Distinguish task quality, control failures and uncertainty before increasing an agent's exposure.
The evidence behind the go-live decision
A working paper for leaders who need to explain why an agent workflow is ready for its next release. Includes a proposed evidence-pack structure, decision table and review agenda.