A good final answer doesn't prove that an agentic AI workflow was correct.
This book develops a code-backed method for verifying execution and business outcomes from authoritative state and using that evidence to gate releases.
You'll find a runnable offline agent that demonstrates the core techniques. Chapter 19 distinguishes implemented capabilities from live-model and production extensions.
Table of Contents
Introduction
The Demo That Lied
Many agentic AI systems are initially evaluated through demos and happy-path tests. A fluent, confident response makes the system appear to work.
The risk begins when that demonstration is treated as sufficient evidence of production readiness. The agent may have skipped a required check, attempted an unauthorized action, committed the same effect twice, or reported success after a dependency failed. A review of the final response alone can miss these failures.
This book builds a reliability harness that verifies execution and business outcomes from authoritative state and uses that evidence to gate releases. It takes the perspective of a performance and reliability engineer: verify the state the agent changed, rather than relying on its account of the work.
What Makes Agents Hard to Test
Conventional tests supply inputs and independently check outputs or state against expected behavior. Agentic workflows introduce two evaluation risks: the agent may receive information that reveals its own answer key, and the evaluator may accept the agent's account as evidence of success.
The same input can also produce different paths across runs, with unauthorized actions, duplicate commits, or false success hidden behind a plausible response.
The harness must therefore verify both the path and the outcome, enforce permissions outside the agent, inject faults, and check recovery or faithful failure. Repeated live runs support reliability estimates with uncertainty. Release gates and production feedback turn those checks into a maintained engineering control.
How the Book is Organized
The book follows a small support and incident-triage agent whose core tests run in continuous integration. Chapter 19 distinguishes implemented capabilities from production extensions.
Part I defines the reliability gap, six evaluation activities, and five evaluation levels.
Part II builds the architecture, reference agent, and scenarios.
Part III evaluates responses, trajectories, tools, and business outcomes.
Part IV covers loops, guardrails, state, memory, resilience, and authorization.
Part V develops observability, performance measurement, and statistics.
Part VI connects release gates, CI, and production feedback.
And Part VII explains the method's limits and a staged adoption path.
How to Read it, and What it Doesn't Claim
Read front to back to understand the method, or begin with the chapter that addresses your most consequential risk. Chapters 5 and 9 provide a practical starting point: run the reference agent and verify a business outcome from state.
The harness catches specified failure classes within a declared reliability envelope. It provides reproducible release evidence, but it can't establish complete safety or replace security review, monitoring, staged delivery, and human accountability. Chapter 19 explains these boundaries.
What this book covers, and what it doesn't
This book is for engineers moving agents, copilots, or tool-using workflows toward production. It assumes familiarity with Python, JSON, HTTP APIs, distributed systems, and LLM tool calling. The reference project is vendor-neutral, and the techniques transfer to other stacks.
The harness produces measurements for release decisions within specified coverage. It can't eliminate hallucination, cover every emergent behavior, or replace oversight. Chapter 19 defines what a passing suite supports.
How to Read This Book
The chapters build on one reference implementation. Use the introduction's part-by-part guide to navigate, and Chapter 20 to sequence adoption by risk.
The Python reference runs offline by default with a deterministic scripted adapter, so structural tests need no model API or network access. Live-model response quality, latency, cost, and sampling require a live adapter. The project provides that interface but doesn't ship a live adapter. Offline and live measurements remain separate.
The reference implementation is on GitHub at https://github.com/vasukiudaykiranvudathala/agentic-ai-reliability-harness. Chapter 5 provides installation and test commands.
Part I: The Reliability Gap
Chapter 1. The Reliability Gap: When a Good Answer Hides a Broken Workflow
A Workflow That Reports Success it Didn't Achieve
Consider an internal support agent for a subscription platform. A request arrives: "Account A-1007 reports duplicate billing in the last hour." The agent is supposed to determine whether the account is affected by an active incident, retrieve the applicable remediation policy, and prepare a proposed remediation for a human to approve.
It does some work and returns a final message:
Incident EVT-402 confirmed and a credit_review ticket was created for A-1007.
The answer reads well. It's on topic, correctly formatted, specific, and it references a real incident identifier. A reviewer skimming a queue of such responses would approve it without a second thought.
Now consider what the answer doesn't show. The call that was supposed to confirm the incident timed out. The agent never received a status. It proceeded anyway, created a ticket that asserts an incident it never actually verified, and then described that result as confirmed. The wording is fluent and the underlying execution is wrong, and nothing in the message lets a reader tell the difference.
This is the reliability gap: the distance between an answer that looks correct and a workflow that actually is correct. The gap isn't an edge case that appears only under exotic conditions. It's a structural risk in agentic systems because the surface a human reviews and the execution that actually ran are different objects. A fluent model is very good at producing the first regardless of the second.
This is a constructed teaching scenario, not a claim about a particular production incident. It's also implemented as a runnable test case in the reference project, so you can observe the failure and verify the harness verdict yourself.
Under a single injected timeout on the incident check, one scripted execution declines to open a ticket and states clearly that it couldn't confirm the incident. A second scripted execution, identical except for how it treats the failed dependency, produces the confident message above. The harness passes the first and fails the second.
It reaches that verdict not by grading the wording but by inspecting the authoritative record of what happened: one run left no ticket, while the other left a ticket asserting an unverified incident. The words were never the evidence.
The Many Ways a Good Answer Can Be Wrong
The timeout case is one instance of a general problem. An agent can produce a convincing final answer while, underneath it, the execution went wrong in any of a number of independent ways.
It can select the wrong tool for the task. It can select the right tool and pass it incorrect arguments. It can take an action it had no authority to take. It can repeat a step, or oscillate between two steps, without making progress. It can ignore a dependency that failed and press on as though it had succeeded. It can lose or corrupt the state it was carrying between steps. It can produce a side effect nobody asked for, or hide the fact that its execution was incomplete. It can burn an unreasonable number of tokens or tool calls to arrive at the same place. It can amplify a small upstream hiccup into a downstream retry storm. It can behave correctly in isolation and fall apart under concurrency or across a long-running session. And it can pass all of your checks today and quietly regress tomorrow after a prompt edit, a model upgrade, a tool schema change, or a configuration tweak.
Figure 1-1. The reliability gap. A convincing final response can accompany a broken execution path, so the response and the execution record must be judged separately.
Each of these can coexist with a final answer that a human, or another model asked to grade the answer, would judge as good.
That's the crux. The quality of the final message and the correctness of the underlying work can diverge completely. A system that pays out money, changes account state, files tickets that trigger downstream processes, or takes any action with consequences can't be validated by reading what it says about itself.
Why Conventional Testing Doesn't Catch This
There are three testing habits, each reasonable in its original context, that fail when carried over to agents.
The first is final-answer grading. Most model evaluation compares a produced answer to a reference answer or scores it against a rubric. This measures whether the model can say the right thing. It doesn't measure whether the agent did the right thing, because the answer is a claim about the work, not the work itself. Grading the claim is exactly the check the false-success agent passes.
The second is using transport or request-completion success as a proxy for workflow success. An HTTP 200 establishes that the service handled the request at its API boundary. It doesn't establish that a multi-step business workflow reached the correct end state, because a workflow can return cleanly at the front door while having selected the wrong tool, skipped a required step, or committed a side effect it shouldn't have.
The third is treating model accuracy as system reliability. A model that scores well on a benchmark is a component with a known property. A reliable system is a different claim about a larger object: the agent loop, the tools, the state store, the authorization layer, the retries, the budgets, and the behavior of all of them together under load and under failure.
Improving the model can leave the system exactly as unreliable as before, because most of the failure modes listed above live in the orchestration, not in the model's next-token quality.
None of these habits is wrong in its home domain. They're simply aimed at the wrong object. To close the reliability gap, you have to test the object that actually carries the risk, which is the whole execution path and the business outcome it produces.
Response Correctness Isn't Outcome Correctness
Two questions define the reliability gap.
Response correctness asks: was the final answer correct, relevant, grounded, complete, and appropriately uncertain? It's a property of the text the agent produced.
Outcome correctness asks: did the workflow reach the intended business end state, through valid decisions and authorized actions, with the required state changes applied and prohibited side effects absent? It's a property of the world the agent acted on, read from an authoritative record rather than from the agent's account of itself.
These two properties are independent. A workflow can be right on one and wrong on the other in either direction.
| Outcome correct | Outcome incorrect | |
|---|---|---|
| Response correct | The healthy case: the agent did the right thing and described it accurately. | The agent accurately reports that a credit was applied, but the credit was unauthorized. The response is factually correct, but the action and workflow are incorrect. |
| Response incorrect | The agent did the right thing but described it poorly or incompletely. The state is correct, but the user may be misled about what happened. This requires correction and can still be consequential. | The clear failure: wrong work, wrong words. The easiest case to catch, and the least of your worries. |
The top-right cell is a particularly dangerous failure class because final-answer grading can't see it. For state-changing workflows, the harness treats outcome correctness as an independent primary verdict and response correctness as a separate required verdict. One can never substitute for the other.
Two clarifications that this book holds to throughout. First, a well-written answer is never accepted as evidence that the outcome was achieved. The outcome is verified independently against authoritative state.
Second, evaluating what the agent did means evaluating observable actions, state transitions, outputs, and tool traces. It doesn't mean inspecting the model's private reasoning. Chain-of-thought disclosure isn't an observability requirement, and a system that depends on reading the model's internal narration to know whether it behaved isn't one you can operate.
What a Reliability Harness is
An agentic AI reliability harness is the controlled execution, measurement, and evaluation layer around an agent. It supplies reproducible scenarios, captures model and tool activity, injects failures, evaluates outcomes, measures operational behavior, and applies release gates.
The word around above carries weight. The harness is separate from the agent and doesn't expose expected outcomes, forbidden-action lists, evaluator rules, or release criteria through the agent's execution interface.
The thing you would deploy (meaning the agent, its model, its tools, its authorization layer, and its state) is the system under evaluation. The test rig that surrounds it, meaning the scenario loader, the fault injector, the trace collector, the evaluators, and the gate engine, is the control plane.
Keeping these two separate is what makes the results trustworthy: the agent can't see the answer key, and the evaluators can't be talked out of their verdict by a persuasive final message.
That separation shows up as a deliberate asymmetry. The evaluators read the authoritative business state directly, because they're part of the control plane. The agent can reach that same state only through a controlled gateway, one action at a time, under authorization.
Because the two sides reach the truth by different paths, the harness can compare what the agent says it did against what actually happened. Within the harness threat model, and provided the gateway and authoritative state are correctly protected, the agent can make its claim match the record only by completing the permitted work.
Five Places to Look
Outcome correctness is the headline, but a single pass or fail at the end isn't enough to operate a system or to diagnose it when it breaks. Throughout the book, we'll evaluate a workflow at five levels: the response, the individual steps, the individual actions, the workflow as a whole, and the system it runs in.
A single request can earn a different verdict at each level. The false-success run passes superficial fluency and relevance checks but fails response groundedness. It also fails at the action level because it acts on an unverified incident, and at the workflow level because it creates a ticket it shouldn't have. Chapter 3 develops these five levels in full and makes them the spine the rest of the book hangs on.
Chapter 1 Checklist:
You can state the reliability gap: the distance between an answer that looks correct and a workflow that is correct.
You can name several independent ways an agent can produce a good answer over a broken execution.
You can explain why final-answer grading, treating request-completion success as workflow success, and model accuracy each fail to close the gap.
You can distinguish response correctness from outcome correctness and place a given failure in the right cell of that table.
You can define a reliability harness and explain why the agent under test must be separated from the control plane.
Key Takeaway
Verify execution and business outcomes independently of the final response. The five evaluation levels expose different failures and supply separate evidence for release decisions.
Chapter 2. Six Things People Call "Evaluation" (and Why You Need All of Them)
Evaluation: One Word Doing Six Jobs
When two engineers say an agent is "evaluated," one may mean a model benchmark and the other a verified business outcome. The term also covers response grading, trajectory checks, system stress tests, and production monitoring.
These six activities answer different questions, measure different objects, and support different decisions. This chapter defines their responsibilities and blind spots so teams can say which evidence they have and which evidence a release needs.
The Six Activities
Model evaluation measures a property of the model as an isolated component: can it perform a task, follow an instruction, or reason over an input, judged against reference answers or a benchmark. It's what provider scorecards and public leaderboards report, and it's a reasonable input to model selection.
Its blind spot is everything outside the model. A strong benchmark score says nothing about your prompt, your tools, your state store, your authorization, or the outcome your workflow produces. Most of the failure modes from Chapter 1 live in that everything-outside, which model evaluation never touches.
Response evaluation measures a property of a produced answer: is it correct, relevant, grounded, complete, appropriately uncertain, and correctly formatted? It's useful, and Chapter 7 develops it in depth.
Its blind spot is the one established in Chapter 1: the answer is a claim about the work, not the work itself. Response evaluation is exactly the check a fluent agent passes while the execution underneath it is wrong. When teams say "we evaluate our agent" and mean only this, they've measured response correctness and left outcome correctness unmeasured.
Agent evaluation measures a property of the trajectory: did the agent make valid intermediate decisions, choose the right tool, pass plausible arguments, sequence its steps sensibly, and avoid loops? This is a real improvement over grading the final answer, because it looks at the path and not just the destination.
But it has two blind spots of its own. First, a trajectory that looks valid step by step can still miss the intended business end state, so a good path isn't a guarantee of a good outcome.
Second, agent evaluation is easy to implement badly by comparing the trajectory to a single golden path, which punishes the alternate valid paths that a competent agent will legitimately take. Chapter 8 treats trajectory evaluation carefully for this reason.
Workflow verification measures a property of the world the agent acted on: did the workflow reach the intended business end state, with the required state changes applied and prohibited side effects absent, read from an authoritative record rather than from the agent's narration? This is outcome correctness, the central verdict for state-changing workflows and the one this book is organized around.
Its blind spot is coverage. The outcome-verification rule can be deterministic even when the agent execution is not, and a deterministic verdict for one run doesn't establish that the agent will produce the same valid outcome across repeated runs, failures, or configuration changes. A correct end state on one scenario tells you the agent can be right. But it tells you nothing about whether it stays right under failure, under load, or after the next change.
System reliability testing measures a property of the whole system under realistic stress: performance, tail latency, concurrency, injected faults, resilience, backpressure, and security. It asks whether the workflow remains correct, observable, fast, and safe when dependencies are slow or failing and when many workflows run at once. This is where an agent that verifies perfectly on a quiet machine reveals that it amplifies a small upstream hiccup into a retry storm, or that it loses isolation between concurrent sessions.
Its blind spot is cost and completeness: it's expensive to run well, and no amount of it enumerates every emergent behavior a nondeterministic system can produce. It also runs before release, against a facsimile of production rather than production itself.
Production monitoring measures a property of the live system in the real world: what's actually happening now, through traces, metrics, drift signals, and incidents. It's the only activity that sees real traffic, real inputs, and real consequences, and it's indispensable for detecting the drift and the long-tail behavior that no pre-release activity can fully anticipate.
Its blind spots are structural. It's reactive, observing what already happened rather than preventing it. It's sampled and constrained by privacy, so you never see everything. It also can't replace pre-release validation, though it can gate progressive rollout stages, stop a canary, and trigger rollback when live evidence violates a release policy. Chapter 18 shows how to feed what production learns back into the earlier activities.
The six at a glance
| Activity | Question it answers | Object measured | When it runs | Primary blind spot |
|---|---|---|---|---|
| Model evaluation | Can the model do the task in isolation? | The model as a component | Selection, upgrade | Everything outside the model |
| Response evaluation | Is this answer good? | The produced text | Per response | The answer is a claim, not the work |
| Agent evaluation | Were the intermediate decisions valid? | The trajectory | Per run | Valid path is not a correct outcome |
| Workflow verification | Did it reach the right business end state? | Authoritative state | Per run | Per-run, not reliability under stress or change |
| System reliability testing | Does it stay correct under load and failure? | The whole system | Pre-release, continuously, and during controlled rollout | Cost. Can't enumerate every behavior. |
| Production monitoring | What is actually happening now? | The live system | Continuously | Reactive and sampled. Runs after a change is live. |
Why You Need All Six
The six activities form an evidence portfolio across the lifecycle. They overlap, but none covers every other's blind spots. The table above identifies the gaps a team must account for.
Depth and ownership depend on risk, architecture, and control over the model. A team consuming a fixed hosted model may concentrate on its application. A team training or fine-tuning a model will invest more in model evaluation. Both still need evidence about workflow outcomes, behavior under stress, and live operation.
Model and response evaluation alone leave execution correctness and capacity unmeasured. A harness makes agent evaluation, workflow verification, and system reliability testing repeatable, then connects them to production monitoring through feedback. It complements upstream model evaluation and downstream monitoring.
Common Mistakes
Using response evaluation as a proxy for workflow verification leaves false success undetected. Treating one green workflow run as reliability evidence leaves stress behavior unknown. Substituting dashboards for pre-release gates exposes customers to avoidable regressions. And crediting a model upgrade with system reliability without retesting the failed orchestration measures the wrong object.
Production Implications
Each activity produces evidence for a different decision, and matching evidence to decision is most of the discipline. Model evaluation informs which model to choose and whether to adopt an upgrade. Response evaluation informs prompt, model-configuration, grounding, output-contract, and content-policy changes. Agent evaluation and workflow verification inform whether a given build behaves correctly and reaches the right outcomes. System reliability testing informs capacity, resilience, and the ship or no-ship decision under realistic conditions. Production monitoring informs incident response and tells you which new scenarios your earlier activities are missing.
When someone asks whether the agent is "evaluated," the useful answer names which of these six they mean, and which of the six the decision at hand actually requires.
Chapter 2 Checklist:
You can name the six activities and state the distinct question each answers.
You can identify the object each measures and when it runs.
You can state the primary blind spot of each and identify which other activities produce evidence for the concern it misses.
You can recognize the response-plus-model-evaluation substitution that ships fluent, unreliable agents.
You can match a given decision to the activity whose evidence it requires.
Key Takeaway
Model evaluation, response evaluation, agent evaluation, workflow verification, system reliability testing, and production monitoring form a lifecycle evidence portfolio. Specify which activity supports each decision, as no single activity covers every concern.
Chapter 3. The Five Evaluation Levels: Response, Step, Action, Workflow, System
Two Taxonomies, Two Questions
Chapters 2 and 3 describe two different axes. The six activities describe the lifecycle purpose for which evidence is collected. The five levels describe the object inside an agentic execution that the evidence evaluates. The relationship is many-to-many, not one-to-one.
The distinction is important, because the two are easy to conflate.
The six activities are about when and why evidence is gathered: at model selection, in pre-release testing, in verifying a workflow, in monitoring production, each to inform a particular decision.
The five levels are about what part of one execution a piece of evidence speaks to: its response, its steps, its actions, its outcome, or the system around it.
A single activity usually gathers evidence at several levels, and a single level is usually examined by several activities. The two frameworks shouldn't be merged.
The cross-reference below shows which levels each activity commonly examines. Read it as a rough map of common practice, not a rule.
| Activity | Response | Step | Action | Workflow | System |
|---|---|---|---|---|---|
| Model evaluation | Supporting | n/a | n/a | n/a | n/a |
| Response evaluation | Primary | n/a | n/a | n/a | n/a |
| Agent evaluation | Supporting | Primary | Primary | n/a | n/a |
| Workflow verification | n/a | n/a | Supporting | Primary | n/a |
| System reliability testing | n/a | Supporting | Supporting | Supporting | Primary |
| Production monitoring | Supporting | Supporting | Supporting | Supporting | Primary |
"Supporting" means that an activity can provide evidence relevant to the level. It doesn't mean that the activity can independently establish the level's verdict. For example, a model benchmark can test whether a model proposes plausible tool calls, but it can't verify an action that was never executed.
Two features of this map matter. The Response column draws evidence from four different activities, which is why "we evaluate responses" is ambiguous until you say which activity you mean. And the map shows why early component and response checks leave important gaps: they produce little or no direct evidence about authoritative workflow state or behavior under operational conditions. The rest of this chapter is about the columns, not the rows.
Where the Five Levels Come From
The levels aren't an arbitrary list. They fall out of the structure of an agentic execution.
A workflow begins with a request and ends with a response. Between them, the agent takes a sequence of steps. Some steps take an action against the outside world through a tool. The actions move the world toward, or away from, an intended business end state. And the whole thing runs inside a system with finite time, capacity, and trust.
Each of those structural features is a place where the execution can be correct or incorrect independently of the others, and each place is a level.
The response level asks whether the final response was correct, relevant, grounded, complete, and appropriately uncertain. Its object is the text the agent produced. Chapter 7 develops it.
The step level asks whether the agent made valid intermediate decisions and transitions: whether each step followed validly from the available observations and moved the workflow forward rather than in a circle. Its object is the trajectory of decisions. Chapters 8 and 10 develop it.
The action level asks whether each action selected the correct tool, supplied valid arguments, operated under the correct authority, and controlled its side effects. Its object is the individual tool invocation and its consequences. Chapters 8, 13, and 14 develop it.
The workflow level asks whether the workflow reached the intended business end state, with the required state changes applied and the completion conditions met. Its object is the authoritative record of the world, read directly rather than from the agent's account.
This is outcome correctness and the central verdict for the state-changing reference workflow. It doesn't override failures at the response, action, or system levels. Chapter 9 develops it.
The system level asks whether the workflow remained reliable, observable, secure, fast, scalable, and cost-efficient. Its object is the operational envelope: latency, concurrency, resilience under failure, security posture, and cost per successful outcome. Chapters 15 through 18 develop it.
One Request, Five Verdicts
The reason to separate these levels is that a single run earns different verdicts at each, and a verdict at one level doesn't predict the verdict at another.
Return to the two runs from Chapter 1, both handling the same request under the same injected timeout on the incident check. One agent stops safely when the check fails. The other ignores the failure, opens a ticket, and reports success.
| Level | Faithful run | False-success run |
|---|---|---|
| Response | Pass: it accurately states that confirmation failed and no ticket was opened. | Fail: it passes superficial form and relevance checks but fails groundedness and uncertainty calibration. |
| Step | Pass: each transition is supported by the preceding observation. | Fail: it treats a failed dependency as successful and continues. |
| Action | Pass: it takes no action unsupported by evidence. | Fail: it creates a ticket based on an unverified incident. |
| Workflow | Pass: the correct end state after failed verification is no ticket. | Fail: the state contains a ticket asserting an unverified incident. |
| System | Contributes positive resilience evidence: this run stopped safely under the injected fault. | Contributes negative resilience evidence: this run produced false success under the injected fault. |
The false-success run is the important column. A superficial response check passes it because the message is fluent, relevant, and specific. A complete response-level evaluation fails it on groundedness, while the step, action, workflow, and fault-response checks explain exactly how the execution broke.
This distinction matters: the reliability gap isn't a weakness of rigorous response evaluation. It appears when surface answer quality is allowed to substitute for execution evidence. A gate that looks only at a superficial response check ships this run. A gate that verifies the workflow level catches it.
Response, step, action, and workflow verdicts can be assigned to an individual execution. A system-level verdict usually requires evidence aggregated across repeated scenarios, fault classes, concurrency levels, and workload profiles. A single run contributes evidence to that verdict. It doesn't establish it alone. This is why the table records the system row as contributing positive or negative resilience evidence rather than as a pass or fail.
Response correctness and workflow correctness can genuinely diverge in the other direction too. Consider a different run in which the agent issues an unauthorized credit and accurately reports, "A $50 credit was applied." The response can be factually correct and grounded in the resulting state while the action and workflow verdicts fail because the side effect was unauthorized and prohibited. This is a true response-pass, action-fail case.
The levels aren't a strict ladder in which passing one level guarantees another. They're distinct evaluation targets, and their verdicts must be recorded separately.
A run can reach the correct business end state through an action it had no authority to take: the outcome looks right at the workflow level while the action level is a failure, because the world arrived at the right place by an illegitimate route.
This isn't a curiosity. It's the reason the action level exists as its own check and isn't folded into the workflow level. It's also the failure that Chapter 14 on security is built to catch. Outcome correctness is central, but no successful verdict at one level compensates for a blocking failure at another.
How the Harness Maps to the Levels
Each level maps to evaluators or measurements in the reference harness, producing distinct verdicts for diagnosis and gating.
The response evaluator applies deterministic checks and, when enabled, advisory rubric evaluation. The trajectory evaluator examines observable decisions and transitions at the step level. At the action level, tool-call validation, authorization records, approval decisions, guardrail results, and recorded side effects are evaluated together. The outcome verifier judges the workflow level from immutable authoritative-state snapshots. Aggregated metrics, fault campaigns, security tests, telemetry checks, and workload experiments supply the system-level verdict.
When Chapter 18 assembles release gates, each gate draws on the level appropriate to the risk it controls: an unauthorized-action gate reads action-level evidence, an outcome-success gate reads workflow-level evidence, and a tail-latency gate reads system-level evidence. Guardrail gates may span the response, step, and action levels depending on where the control is applied. The five levels are, in that sense, the organizing principle of both the evaluation and the release decision.
Common Mistakes
Collapsing five levels into one score hides the failing level. Treating them as a hierarchy lets a correct end state excuse unauthorized actions. Deferring system testing until production leaves concurrency, resilience, and cost unknown at release. Keep each verdict visible and test the operational envelope before deployment.
Production Implications
Report strengths and weaknesses by level: a build may pass response and workflow checks while failing under load. This tells reviewers which evidence is missing before sign-off. When production incidents become regression cases in Chapter 18, their failing levels identify the evaluator or gate that needs coverage.
Chapter 3 Checklist:
You can distinguish the six activities (when and why evidence is collected) from the five levels (what part of the execution the evidence evaluates), and explain why the mapping is many-to-many.
You can name the five levels and state the question and object of each.
You can derive the levels from the structure of an agentic execution.
You can judge a single run at all five levels and show that the verdicts differ.
You can explain why a correct outcome doesn't certify the actions taken to reach it, and why the action level is therefore separate from the workflow level.
You can map each level to the evaluator or measurement that judges it in the harness.
Key Takeaway
Record response, step, action, workflow, and system verdicts separately. A correct result at one level can't compensate for a blocking failure at another. System verdicts generally require aggregated operational evidence.
Part II: The Foundation
Chapter 4. Harness Architecture: Separating the Agent Under Test from the Control Plane
The Engineering Problem
Trustworthy evaluation separates the system under test from its expectations and assertions. For agents, the architecture must close two failure paths.
First, expected outcomes, permitted sequences, or forbidden actions may leak into the agent's context as "grounding." A pass then fails to establish independent decision quality.
Second, an evaluator may use the final message to infer workflow success, accepting the false-success claim from Chapter 1. The evaluator needs independent execution evidence.
The architecture closes both paths through enforced visibility and access boundaries between the SUE and control plane.
Figure 4-1. The system under evaluation and the control plane. The SUE can't see the answer key, and the control plane doesn't trust the agent narration.
Three Zones, Not Two
It's tempting to draw a single line with the agent on one side and the test rig on the other. That line is real, but it hides a distinction that matters later: some of what surrounds the agent during a test isn't part of the deployed system and isn't part of the test logic, either. It stands in for external dependencies. Sorting the harness into three zones captures this.
The system under evaluation, or SUE, is what you would deploy: the agent runtime, the model interface, the tool clients, the gateway, the authorization enforcement, and the production runtime limits. This zone is the same whether you test it or run it for real.
The controlled test environment holds the deterministic substitutes that stand in for external dependencies in offline mode: the scripted model, the transcript fixture, the tool simulators, the seeded state-store implementation, and the virtual clock. These aren't components you deploy. They occupy the seams where real dependencies would sit.
The harness control plane is the test logic proper: the scenario loader, the fault schedule, the evaluators, the immutable evidence store, the metrics, the reports, and the release gates.
The zone that shifts between modes is the middle one. In Mode A, the model interface is backed by the scripted model and the tool clients by simulators, both from the controlled test environment. In Mode B, the model interface is backed by a live model while tool dependencies remain controlled. In Mode C, the workflow runs against a live model and representative downstream infrastructure.
The tested dependencies form part of the broader system under evaluation. The interface belongs to the SUE in every mode: only the implementation behind it changes. Keeping that swap point clean is what makes the execution modes straightforward to reason about in Chapter 16.
| Component | Zone | Role |
|---|---|---|
| Agent runtime | SUE | Runs plan-act-observe, requests actions, enforces nothing |
| Model interface | SUE | The seam through which the agent asks for a decision |
| Tool clients and gateway | SUE | The single enforcement point from request to execution |
| Authorization enforcement | SUE | Identity, policy, and the authorization decision |
| Production runtime limits | SUE | The execution supervisor that stops the agent itself |
| Scripted model, transcript | Controlled test env | Deterministic stand-in for the model dependency |
| Tool simulators | Controlled test env | Deterministic stand-ins for downstream services |
| Seeded state store, virtual clock | Controlled test env | Deterministic stand-ins for real state and time |
| Scenario loader, fault schedule | Control plane | Loads cases, arms controlled failures |
| Evaluators | Control plane | Judge response, trajectory, outcome, loops, guardrails |
| Immutable evidence store | Control plane | Retains sanitized records and state snapshots |
| Metrics, reports, release gates | Control plane | Aggregate, summarize, and decide ship or no-ship |
Two placements deserve emphasis. Authorization enforcement is inside the SUE, not the control plane, because it's part of the system you deploy and must be tested, not simulated by the harness. And production runtime limits are inside the SUE for the same reason. This is a point important enough to take on its own below.
Production Limits Belong Inside the SUE
A runaway agent that never stops is a production incident, not a test artifact. So the ability to stop it must live in the deployed system. If only the harness enforces step, tool-call, and time limits, then a green run proves the harness can stop a runaway agent. It doesn't prove the deployed system can, and the deployed system is what ships.
The reference harness therefore uses two protection layers. Inside the SUE, an execution supervisor enforces the production step, tool-call, time, and loop limits. The agent consults it and stops itself.
Independently, the harness runs an outer watchdog whose only job is to stop a broken test if the SUE's own protection fails. The two are ordered so the SUE always stops first:
SUE deadline < harness watchdog deadline In the reference runner, the SUE deadline is the scenario's wall-clock budget and the watchdog is set strictly above it (from src/arh/harness/runner.py):
deadline_ms=float(budgets.wall_clock_ms), clock=self._clock, ... wd = scenario.controls.watchdog watchdog_max_actions = max(budgets.max_steps, budgets.max_tool_calls) + wd.extra_actions watchdog_deadline_ms = float(budgets.wall_clock_ms) + float(wd.extra_ms) The SUE supervisor's deadline is the scenario's wall-clock budget. The watchdog is set strictly above it by a configurable allowance from the scenario's watchdog configuration (extra_actions and extra_ms, defaulting to 8 and 5000), so a scenario can widen the margin without changing code.
The supervisor is small and lives in the agent package, not the harness (from src/arh/agent/supervisor.py):
def before_action(self, call: ToolCall) -> str | None: # Terminate before starting an action that would exceed the budget. if self._tool_calls + 1 > self.max_tool_calls: return "tool_call_budget" return None The harness then asserts that the SUE terminated itself with an expected reason. If the watchdog had to fire, the run is recorded as a failure through a self_terminated flag, because a system that only stops when an external timer rescues it isn't one you want in production.
In the reference implementation, the golden run and the loop-detection runs all report self_terminated true, which is the result you're testing for: the agent stopped itself. These two protection layers cover budgets and self-termination. Chapter 10 develops non-progress containment specifically as three layers, adding the control plane's independent replay of the record to check that the system under evaluation classified and terminated correctly.
The Request Path for One Workflow
A single run threads the zones together in a fixed order. The control plane sets the stage, the SUE acts, and the ...
