How to Build an AI Agent Evaluation Harness That Survives Production

A harness coordinates five jobs: select the system under test, create its starting conditions, execute the workflow, capture the full trace, and apply a decision rule. The output should be more than a score. It should be a reviewable receipt showing what ran, under which conditions, how it was judged, and why a candidate passed or failed.

A playground is useful for exploration, but a few manually chosen prompts are not a harness. A leaderboard can summarize results, but it does not establish reproducibility. An LLM judge can grade one dimension, but it does not own the scenarios, execution environment, comparison, or release decision. The harness is the system that binds those pieces together.

Treat each accepted result as a claim about one exact test contract. The prompt matters, but so do the model configuration, tools, retrieval, routing, state, cases, evaluators, and decision rule. If any material component changed without a new identity, two runs that look comparable may describe different systems.

Write the failure as a behavior contract: when the agent faces situation X, it must do Y, because doing Z creates a defined consequence. Name the person who can decide whether that contract is correct. Without that owner, the harness can produce precise numbers for the wrong objective.

Start narrow. A pricing agent invents a discount. A support agent resets the wrong account. A router sends billing questions to sales. A research agent cites a source that does not support its claim. One concrete failure gives the first harness version a useful boundary and a falsifiable job.

Use reviewed production failures to identify the conditions that made the behavior possible, then create privacy-safe cases that reproduce those conditions. Add clean controls for behavior that already works. Add boundary cases around permissions, missing context, tool errors, long histories, and ambiguous requests when they are relevant to the failure.

Do not copy one incident repeatedly and call it coverage. Separate the underlying failure mechanism from surface wording, then vary the details that should not change the expected decision. Keep tuning cases apart from protected acceptance cases so repeated iteration does not merely teach the visible suite.

An agent can produce a plausible final sentence after taking the wrong action, calling an unauthorized tool, retrieving stale evidence, or looping through unnecessary steps. Capture the full trajectory: messages, routing decisions, tool calls and arguments, tool results, state changes, retries, latency, errors, and final output.

Control dependencies without making the environment unrealistically clean. Stable fixtures help compare candidates, but the harness should also test expected timeouts, empty results, denied permissions, partial failures, and recovery paths. Every simulated dependency needs a clear contract stating what production behavior it represents and what it omits.

Use deterministic code for schemas, permissions, tool arguments, required fields, exact state transitions, and other machine-checkable invariants. Use semantic graders when the requirement genuinely depends on meaning. Use human review to define policy, label consequential examples, calibrate automated graders, and resolve important disagreements.

Do not ask one model judge to collapse correctness, safety, usefulness, style, and business outcome into a universal score. Preserve dimension-level results and the evidence behind them. Measure judge agreement against reviewed labels on the failure slice that matters; a grader that works on ordinary responses may still miss the rare behavior controlling the release.

Run the current agent and candidate against the same scenario identity, starting state, tool fixtures, model configuration, and evaluator contract. Pair each result at the scenario or persona level. Unmatched runs can describe coverage or operations, but they should not decide which version performed better.

Require positive improvement on the targeted behavior and protect material regressions. An aggregate average can hide a challenger that fixed one slice by breaking another. Keep denominators, missing pairs, failed executions, evaluator abstentions, and blocked cases visible instead of silently dropping them from the result.

Version the harness configuration and test its own invariants. A scenario loader should fail on missing required state. A tool fixture should prove it enforces the same permission boundary the test claims to exercise. A grader should have labeled examples showing accepted, rejected, and ambiguous outcomes. A report should retain failures rather than averaging them away.

This is where prompt version control belongs. A prompt can live in Git, a prompt registry, or a deliberate hybrid, but the run receipt must identify the exact effective prompt. The same rule applies to model settings, tool schemas, retrieval inputs, scenario versions, and grader prompts. Git is one implementation; reproducible identity is the requirement.

A passing harness result means the candidate earned consideration for release under the declared test contract. It does not mean the candidate reached production, encountered comparable traffic, or improved the real outcome. Preserve the accepted candidate identity, approval, deployment time, environment, and rollback target so new traces can be joined to the exact change.

After deployment, evaluate the original failure on fresh comparable production evidence. The result can be verified, not fixed, or confounded. Feed reviewed failures back into later scenario versions, but preserve the protected evidence used to judge each release. The harness improves when production teaches it what it missed; it becomes theater when a green score ends the investigation.

Converra automates the repetitive path around a targeted production behavior: trace-backed diagnosis, prompt or supported configuration candidates, paired simulation, regression checks, governed delivery, and post-deployment measurement. The customer still owns the outcome definition, data boundary, deployment policy, and final accountability.

Converra does not claim to replace every customer-owned test, tool sandbox, retrieval evaluator, security review, or harness component. When evidence points to code, retrieval, data, permissions, or orchestration outside the supported change scope, that owner and fix type should remain explicit rather than being relabeled as a prompt problem.