How to Build an Agent Eval Harness That Survives Workflow Drift

A practical guide to scenarios, golden tasks, tool traces, and acceptance thresholds

Agent workflows do not fail like ordinary code. The output may look acceptable while the plan, tool use, or policy path regressed. That is why evaluation for agents needs a different mental model than unit testing: not perfect determinism, but repeatable signal strong enough to support shipping decisions. This is an inference from the project brief, not a measured claim.

If you are building agentic workflows, the hard part is not scoring a response after the fact. The hard part is deciding what good behavior looks like before the workflow ships. This is a framing choice drawn from the brief.

This post is about a practical agent evaluation framework: a living bundle of scenarios, golden tasks, tool-trace assertions, and acceptance thresholds. That bundle should be versioned with the workflow and updated whenever prompts, tools, policies, or routing change.

A useful eval harness is not a benchmark. It is a production artifact.

What this post is

• A production-engineering guide to agent eval harness design
• A way to turn open-ended agent behavior into repeatable pass/fail checks
• A framework for keeping evaluation current as the workflow changes

What this post is not

• A claim that agent evaluation is solved
• A universal scoring method for every workflow
• A set-and-forget system
• A product-specific tutorial

Why agent evals need a different mental model than unit tests

Traditional unit tests work well when inputs, outputs, and failure modes are narrow enough to specify exactly. Agent workflows are usually not that tidy.

An agent may return different text on different runs and still be acceptable. It may also return the “right” answer while taking a bad path: calling the wrong tool, skipping a required approval, or violating a policy boundary. Those are different classes of failure, and exact string matching will only catch a subset of them.

That is the key mental shift:

• The goal is not exact determinism.
• The goal is repeatable signal.
• The evaluation target is the behavior that matters to users, systems, or policy.

Figure description: a four-stage harness model. Scenarios define coverage, golden tasks define expected behavior, tool-trace assertions check execution path, and acceptance thresholds decide ship / no-ship.

If your current test suite is mostly string comparisons, it is probably doing useful work in narrow cases. But it is not enough for open-ended agent outputs by itself.

The core problem: open-ended outputs need concrete criteria somewhere

Open-ended outputs can be acceptable in several different forms. That makes exact-match scoring a poor primary signal for many agent workflows.

This does not mean exact match is useless. It is still appropriate when the output is fixed-format, highly constrained, or downstream systems require a strict schema. The limitation is scope: exact match is too brittle when the acceptable output space is broader than one string.

The failure mode to watch is subtle:

1. A reviewer looks at a result.
2. They decide whether it “feels right.”
3. That judgment becomes the de facto standard.
4. The standard changes from reviewer to reviewer, and from week to week.

If you do not define acceptance criteria up front, reviewers end up inventing them after the fact. The harness should encode the important outcome, not every detail of the text.

Comparison: common evaluation modes

Approach	Good for	Weakness when used alone
Exact match	Fixed-format outputs, narrow tasks	Too brittle for acceptable variation
Logs	Debugging and observability	Shows what happened, not whether it was acceptable
Human review	Ambiguous or policy-sensitive cases	Slow and inconsistent without explicit criteria
Benchmarks	Broad comparisons across systems	Often misses workflow-specific failures
Harness-based evals	Shipping decisions for a specific workflow	Requires ownership and maintenance

The point is not that one of these replaces the others. The point is that each covers a different slice of the problem.

Checklist: what to include in an agent eval harness

• Define scenarios that cover real decision points, not just generic prompts.
• Write golden tasks that describe acceptable outcome shape, required conditions, and disallowed behaviors.
• Add tool-trace assertions for the execution paths that matter.
• Set acceptance thresholds before running the eval.
• Version the harness with the workflow.
• Update scenarios, tasks, traces, and thresholds when prompts, tools, routing, or policy change.
• Keep any human-review criteria explicit and reusable in the harness.

What makes agent evaluation harder than ordinary regression testing

Agent workflows introduce several kinds of drift that ordinary software tests often do not model well:

• Prompt changes
• Tool changes
• Routing changes
• Policy changes

Those changes can invalidate assumptions in the eval suite even when the surrounding application code looks stable. A harness that was accurate last month may become stale if the workflow now plans differently, calls different tools, or follows different escalation rules.

That is why tool traces matter. Two outputs that look similar may have been produced through very different execution paths, and those paths may not be equally acceptable.

A test suite that is too rigid will age quickly. A test suite that is too loose will not catch regressions.

There is no universal scoring method that works for every workflow, so the harness has to be tailored to the decision the workflow is making.

See also: The Agent Loop Thinks. The Control Plane Decides. for the control-plane framing behind this idea.

Why “we already have logs and human review” is not enough

This is the most common objection, and it is partly right.

Logs help, but they are not evaluation

Logging tells you what happened. It does not tell you whether what happened was acceptable. You still need criteria.

Human review helps, but it does not scale by itself

Human review is necessary in many workflows, especially when policy, safety, or business judgment is involved. But if review is not anchored to explicit acceptance criteria, it becomes a vibe check with a long turnaround time.

Ad hoc judgment is useful for debugging, not for regression control

Debugging is local. Regression testing is comparative. A workflow that “looks fine” in one review can still drift in ways that matter later.

So the answer is not “replace humans.” The answer is “make human judgment explicit, bounded, and reusable inside the eval harness.”

The practical framework: scenarios, golden tasks, tool traces, and thresholds

The memorable unit is simple:

Scenarios tell you what to test, golden tasks tell you what good looks like, tool traces tell you how the agent got there, and acceptance thresholds tell you when to ship.

1. Scenarios define coverage

Scenarios describe the situations the workflow must handle. They are not just test cases; they are the decision points, risk boundaries, and user intents that matter.

Good scenarios usually map to:

• common user paths
• high-risk edge cases
• policy boundaries
• fallback or escalation conditions
• known failure modes

A scenario should answer: What situation are we trying to cover?

2. Golden tasks define expected good behavior

A golden task captures what acceptable behavior looks like for a representative case. It does not have to prescribe exact prose. It should specify the outcome shape, the required conditions, and any disallowed behaviors.

A golden task should answer: What does “good” mean here?

3. Tool-trace assertions check the execution path

Tool traces are where agent evaluation becomes materially different from text-only testing. If a task should be resolved with a specific tool, a bounded sequence of tools, or a required escalation path, the trace is part of the behavior.

A trace assertion should answer: How did the agent get there, and was that path acceptable?

4. Acceptance thresholds decide ship / no-ship

Thresholds make the evaluation actionable. They should be explicit before the test runs, not adjusted after a failure.

A threshold should answer: Is this good enough to ship?

This four-part bundle is not a universal standard. It is a practical framework for production decisions.

Comparison: common evaluation modes

Approach	Good for	Weakness when used alone
Exact match	Fixed-format outputs, narrow tasks	Too brittle for acceptable variation
Logs	Debugging and observability	Shows what happened, not whether it was acceptable
Human review	Ambiguous or policy-sensitive cases	Slow and inconsistent without explicit criteria
Benchmarks	Broad comparisons across systems	Often misses workflow-specific failures
Harness-based evals	Shipping decisions for a specific workflow	Requires ownership and maintenance

What to put in each layer

The framework works only if each layer catches a different class of regression.

Scenarios should reflect real decision points

If the workflow has distinct branches, policy boundaries, or risk levels, those should appear in the scenario set. The goal is coverage that mirrors the workflow, not a generic benchmark suite.

Use scenarios to represent:

• routine cases
• ambiguous cases
• boundary cases
• unsafe or disallowed cases
• escalation cases

Golden tasks should describe outcome shape, not just prose

For open-ended agent outputs, “golden” usually means “acceptable behavior under defined conditions,” not “one exact response string.”

A golden task can specify:

• required information
• required action
• disallowed action
• required escalation
• expected final state

Tool-trace assertions should focus on important path constraints

Not every step needs to be checked. The useful assertions are the ones that prevent meaningful regressions:

• the right tool was used
• tools were used in the right order
• forbidden tools were not used
• escalation happened when required
• the agent did not bypass a control boundary

Be careful not to overfit trace checks to one implementation path. If the path is merely one acceptable way to solve the task, hard-coding it may create false failures when the workflow improves.

Acceptance thresholds should reflect the decision being made

Thresholds should be tied to the business or operational consequence of failure. In practice, that usually means distinguishing between:

• must-pass scenarios
• acceptable-with-review scenarios
• informational scenarios

If a scenario is safety-critical, the threshold should be stricter. If it is an exploratory path, the threshold may tolerate more variation. The point is to encode that decision explicitly.

Example structure

Layer	Example question	What it catches
Scenario	Did we cover this user intent or risk boundary?	Missing coverage
Golden task	Did the result satisfy the expected outcome?	Wrong or incomplete behavior
Tool trace	Did the agent take an acceptable path?	Bad execution path
Threshold	Did the workflow meet ship criteria?	Overall regression decision

Glossary

• Scenario: the user intent, risk boundary, or decision point being tested.
• Golden task: a representative case with explicit acceptance criteria.
• Tool-trace assertion: a check on the execution path, not just the text output.
• Acceptance threshold: the rule that turns a result into ship / no-ship.
• Workflow drift: changes in prompts, tools, routing, or policy that make old tests stale.

A minimal eval case should be readable as a spec

If an eval case is hard to read, it will be hard to maintain.

A maintainable harness usually keeps scenario definitions, golden tasks, trace assertions, and thresholds in source control. That makes the harness a first-class engineering artifact rather than an ad hoc collection of review notes.

See also: Agentic AI Operating Model: Assign Decision Rights Before You Add Autonomy for the operating-model angle behind this pattern.

Example eval case schema

Below is a framework-agnostic shape, not a product-specific format.

scenario: "User asks for a refund after a failed service action"
goal:
  outcome: "Refund is approved or escalated according to policy"
  disallowed:
    - "Invent a refund without policy basis"
    - "Bypass mandatory review"
trace_assertions:
  - "Use policy lookup before decision"
  - "Escalate if refund amount exceeds approval boundary"
threshold:
  pass_if:
    - "Required policy step completed"
    - "No forbidden path taken"
    - "Final outcome matches policy"
review_notes:
  - "Human review required if policy is ambiguous"

The important part is not the syntax. The important part is that the evaluation criteria are explicit, reviewable, and versioned with the workflow.

Eval template: minimal case structure

scenario: "Describe the real user intent or risk boundary"
goal:
  outcome: "State the acceptable result shape"
  required:
    - "Required condition or action"
  disallowed:
    - "Forbidden action or path"
trace_assertions:
  - "Important tool or escalation constraint"
threshold:
  pass_if:
    - "Outcome is acceptable"
    - "Required path constraint is met"
review_notes:
  - "Human judgment needed when criteria are ambiguous"

Copy this / don’t copy this

Copy this	Don’t copy this
Encode required conditions, forbidden behaviors, and escalation rules in the eval case.	Rely on reviewer intuition after the fact.
Version the harness with the workflow.	Freeze the harness while the workflow changes.
Check both outcome and path when the path matters.	Use exact string matching as the only signal for open-ended behavior.
Treat production failures as harness updates, not just workflow bugs.	Patch only the code and leave the eval suite stale.

How to keep the harness current as the workflow changes

The harness should change when the workflow changes. Freezing the harness is how you end up with stale confidence.

Figure description: prompts, tools, routing, and policy changes feed into a refresh loop that updates scenarios, golden tasks, trace assertions, and thresholds.

Version the harness with the workflow

If prompts, tools, routing logic, or policy rules live in source control, the eval suite should too. That keeps evaluation from drifting away from the thing it is supposed to measure.

Treat refresh work as normal engineering work

When the workflow changes, ask:

• Which scenarios are no longer representative?
• Which new scenarios need to be added?
• Which golden tasks are now stale?
• Which trace assertions are too specific?
• Which thresholds need to be tightened or relaxed?

Separate stable criteria from implementation details

Some checks should remain stable even if the implementation changes. For example, a workflow may switch tools without changing the required outcome or policy boundary. If your trace assertions are too implementation-specific, they will churn unnecessarily.

Keep explicit notes where human judgment is still required

Not every case should be reduced to a deterministic check. For those cases, put the human review criteria in the harness itself so the review is repeatable.

Refresh after real failures, not just after planned refactors

Production or staging regressions are useful data. They tell you where the harness missed a meaningful failure, which is often the fastest way to find missing scenarios or weak thresholds.

Rollout template: how to keep the harness current

1. Start with scenarios that match the workflow’s real decision points.
2. Add golden tasks before defining thresholds.
3. Add trace assertions only for path constraints that matter.
4. Make thresholds explicit and reviewable.
5. Version the harness with the workflow.
6. Refresh the harness after prompt, tool, routing, or policy changes.
7. Use production or staging regressions to find missing scenarios or weak thresholds.

How to validate whether the harness itself is working

A harness deserves its own validation loop.

Figure description: when a production or staging issue appears, compare targeted human review with the harness result. If the harness missed a meaningful failure, add or update a scenario, adjust a threshold, or revise a trace assertion.

A useful harness should do at least four things:

1. Catch regressions when prompts, tools, or routing change.
2. Agree with targeted human review on representative cases.
3. Expose gaps where the suite is too permissive.
4. Track whether scenario coverage still matches the current workflow surface.

This is less about generating a score and more about checking whether the harness still reflects reality.

What to look for

• The harness passes a workflow that reviewers consider unsafe.
• The harness fails a workflow that reviewers consider acceptable.
• The same scenario produces different decisions without an intended workflow change.
• New product behavior is not represented in the suite.
• A trace assertion keeps failing because the workflow changed legitimately.

When you find those cases, do not just fix the failing test. Decide whether the problem is the scenario, the golden task, the trace assertion, or the threshold. That distinction matters because each points to a different kind of maintenance work.

Decision tree: how to classify a failing eval

• Did the workflow change in a way that makes the old test invalid?
  • Yes → update the scenario, golden task, trace assertion, or threshold as appropriate.
  • No → treat it as a likely regression and investigate.
• Is the failure about the final outcome?
  • Yes → check the golden task and acceptance threshold.
  • No → check the tool trace and path constraints.
• Is the evaluation too strict for a legitimate variation?
  • Yes → relax the trace assertion or broaden the allowed outcome shape.
  • No → keep the failure and fix the workflow.

Expected benefits, without pretending the problem is solved

I would avoid claiming that a better harness magically improves every agent workflow. We do not have evidence for that here, and evaluation quality depends on the workflow, the constraints, and the team maintaining it.

What you should expect, in practical terms, is:

• less ambiguity about what “good” means
• faster review because criteria are written down
• easier regression triage because failures map to a known layer
• clearer ship / no-ship decisions

The main win is not a higher score. It is a more reliable decision process for shipping changes.

See also: Control Plane vs Agent Loop: A Production Architecture for Safe, Auditable Agentic Systems for the broader architecture context.

Where this approach can still fail

This is the part people skip, and it is where the maintenance cost lives.

Scenario coverage can drift behind reality

If the suite is not maintained, it will eventually stop reflecting real usage. That creates false confidence.

Golden tasks can go stale

User expectations and policy can change. A golden task that encoded last quarter’s behavior may no longer be valid today.

Trace assertions can overfit one implementation

If your checks are too specific, a legitimate routing or tool change can trigger failures even though the workflow is still correct.

Thresholds can be too loose

If acceptance criteria are vague or overly permissive, you may ship behavior that is technically passing but operationally wrong.

The harness requires ownership

A living harness is not free. Someone has to curate scenarios, review thresholds, and decide when a change in the workflow should trigger a change in the tests.

Failure mode table: where harnesses break down

Failure mode	What it looks like	Why it matters
Scenario coverage drift	The suite no longer reflects current product behavior	Creates false confidence
Golden tasks go stale	Tasks encode outdated policy or user expectations	Passing tests can still reflect the wrong behavior
Trace assertions overfit	Tests fail after legitimate routing or tool changes	Causes churn without improving signal
Thresholds are too loose	Passing behavior is operationally wrong	Lets regressions ship
Harness has no owner	No one refreshes tests after workflow changes	The suite degrades over time

See also: The Agent Loop Ceiling: When LLM Agents Need More Than a Prompt, Tools, and a While Loop for the point where a prompt-and-loop approach starts to run out of room.

A practical checklist for building or revising an agent eval harness

If you are starting from scratch, or cleaning up a brittle suite, use this sequence:

1. Start with scenarios that reflect the workflow’s real decision points.
2. Write golden tasks for representative cases before you define thresholds.
3. Add tool-trace assertions for the execution paths that matter.
4. Make acceptance thresholds explicit and reviewable.
5. Version the harness with the workflow.
6. Update the harness whenever prompts, tools, policies, or routing change.

If you are reviewing an existing suite, ask:

• What important scenario is missing?
• Which golden task is too vague?
• Which trace assertion is too rigid?
• Which threshold is doing hidden work?
• What recent workflow change invalidated this test?

See also: Boundaries are your friends for a boundary-first way to think about this kind of design.

Architecture review questions

• What scenario is this eval actually covering?
• What behavior counts as good enough?
• Which execution paths are required, forbidden, or acceptable?
• What failure would still look acceptable to a casual reviewer?
• What recent workflow change could have invalidated this test?
• Which checks are stable criteria, and which are implementation details?

Conclusion: agent evaluation is part of workflow design

The safest way to think about agent evaluation is not as a post-launch checklist. It is part of workflow design.

The useful unit is the bundle:

• scenarios
• golden tasks
• tool-trace assertions
• acceptance thresholds

Because agent behavior can drift in planning, tool use, and policy decisions even when surrounding software looks stable, the harness has to evolve with the workflow.

That is the real production lesson:

Open-ended outputs still need concrete pass/fail criteria somewhere in the workflow.
The job of the eval harness is to make those criteria explicit, maintainable, and current.

Three things to remember

1. Agent evals need explicit criteria, not just logs or vibes.
2. The useful unit is a bundle: scenarios, golden tasks, tool traces, and thresholds.
3. A harness that is not refreshed with the workflow will become stale.