Docs · The doctrine · Section 12
Agent evaluation and testing
A deterministic system is tested; an agentic system is tested and evaluated. The code around it is verified like any software, but the model's behavior, non-deterministic, calls for a dedicated quality measure. This section is the runbook for both: the test pyramid adapted to agents, and the behavioral evaluation loop.
Founding distinction: a test answers true or false on deterministic code. An evaluation scores a quality on non-deterministic behavior. Both are necessary; neither replaces the other.
The test pyramid adapted to agents
1 Unit, the domain without the network
Because the domain is pure and the model provider is isolated behind a port, use cases are tested without network calls, by injecting a mock model adapter that returns deterministic fixtures. The tests are fast, reproducible, and depend on no provider. The purity of the domain, established in Section 02, pays off here directly.
2 Contract, the schema as guardrail
Every input and output crossing a boundary is validated by a typed schema. Contract tests verify that a schema accepts valid payloads and rejects invalid ones: a correct payload does not throw, a malformed payload throws. Their real value is detecting the silent gap between the schema and the data actually produced, the most costly drift in a typed system. Pushed one step further, the contract is consumer-driven: each consumer expresses its expectations as an executable contract, and a producer change that would break them fails at integration, before reaching production. It is the executable counterpart of the contract governance established in section 02.
valid payload → schema.parse(payload) does not throw ok, contract honored missing field → schema.parse(payload) throws ok, expected rejection wrong type → schema.parse(payload) throws ok, expected rejection
3 Integration, orchestration with injected mocks
At the integration level, use cases are assembled via the dependency injection container, with mock adapters placed inside it (persistence, model, execution). Orchestration and boundaries are verified without touching any real infrastructure. The injection container, established in Section 05, makes these tests possible by simple substitution.
4 Evaluations, behavioral quality
At the top, evaluations measure what tests cannot: the quality of the agent's behavior on realistic scenarios. A memory evaluation bench, inspired by public long-term memory protocols, covers six capabilities, over multi-turn conversations, with an expected answer and a scoring rubric.
| Capability evaluated | What it verifies |
|---|---|
| Direct recall | Retrieving a fact given several turns earlier. |
| Multi-constraint recall | Combining several scattered pieces of information to answer. |
| Knowledge update | Returning the most recent value after a correction. |
| Temporal reasoning | Returning what was true at a given date, and distinguishing when a fact was learned from when it was valid. This is the test bench for the bi-temporal model of section 06. |
| Abstention | Refusing to invent when the information was never given. |
| Long session | Remembering after many turns, which triggers summarization. |
Scoring follows an explicit rubric: a complete answer that restates all the key elements earns the maximum, a partial answer missing one earns less, a vague but not false answer earns half. Each scenario carries a list of expected terms and a list of forbidden terms, which makes the measurement of abstention as important as that of recall: not hallucinating is a scored criterion.
From the pyramid to the runtime loop
Placed at the end of the cycle, evaluation would amount to a mere preproduction gate. For a non-deterministic system subject to model drift, it must become a continuous runtime loop. The stream of traces emitted by the middleware (section 05) is sampled in the background, off the hot path: no latency added to the turn. On this sample, hybrid scoring combines deterministic checks with a rubric-driven judge model for the behavioral criteria, abstention first among them. The score feeds a per-agent quality profile, which extends the notion of trust from the credential alone to observed behavior. A trap to avoid: the judge model is itself a model, and it will be updated. The day it changes, the quality series over time becomes incomparable, silently. So the judge is anchored, just as the serving model is promoted: a pinned version, or an anchor set replayed at every judge change to recalibrate the measure.
The loop remains open at the action boundary. It produces signals and recommendations; acting on them goes either through bounded tuning within a pre-approved, audited envelope, or through human validation, never through autonomous rewriting. A naive closed loop that directly optimized the judge's score would drift toward whatever flatters it without improving real quality; what makes self-tuning hold is a tamper-proof guard, a verifiable hold-out the optimizer never sees and that triggers a rollback. This strong guard assumes verifiable ground truth; for purely subjective behaviors, where it is missing, the safety net is once again the human sample, and the self-tuning envelope stays narrow. The principle "the human decides" applies all the way here.
Why not a chorus of verifiers? The temptation is strong to replace deterministic guardrails with probabilistic agents that review one another, and to let self-correction emerge. It is seductive, but weaker wherever a guarantee is required, for three reasons. First, a hard property, an authorization, idempotence, schema conformance, cannot be manufactured from soft judgments: stacking fallible verifiers stacks uncertainties, it does not cancel them. Second, the argument assumes independent errors, yet models that share data and biases share their blind spots: their errors are correlated, to the point that a majority vote can amplify the common error instead of correcting it, and an adversarial input that fools one fools the chorus. Finally, every verification is one more inference, costly and slow, where a deterministic check is free and safe. This is the category error the model boundary avoids: deterministic for whatever admits a guarantee, judge model for the only irreducible behavioral quality, and always under the tamper-proof hold-out described above. As models grow more reliable, the share entrusted to the judge can grow; but the floor, safety, security, authorization, audit, never leaves the deterministic. And it must be said plainly: the judge this framework retains does not escape these limits, fallible and non-deterministic itself. It holds only under the tamper-proof hold-out and behind the deterministic floor, never as a standalone guarantee. The behavioral assurance layer is useful; it is not as hard as the foundation.
Validating a model change before trusting it
Substituting the model is a right the architecture guarantees; trusting it is earned. A new or updated model can alter behavior in ways no offline evaluation bench captures, and that only shows on real traffic: so the switch is never made in a single move. The candidate first runs in shadow deployment, behind the same port, on real traffic but silently: its outputs are not served, and their behavioral divergence from the serving model is measured by the same evaluation that monitors drift. If the divergence stays below a threshold defined in advance, a growing share of traffic is switched over, under the same monitoring, with immediate rollback at the slightest regression. This is the migration discipline of the model port, sister to the expand-then-contract of contracts (section 02): validate in parallel, then switch in stages. One reservation, however: this automatic gate holds only for criteria with verifiable ground truth. For purely subjective dimensions, where the automatic signal is missing, promotion does not self-trigger; it stays under human validation.
Evaluation runbook
- Add a scenario: describe the multi-turn conversation, the final question, the expected and forbidden terms, and the targeted capability category.
- Run: replay the turns in order against the current system, ask the final question, compare the answer against the expected and forbidden terms.
- Score: apply the rubric, track the score per capability over time to detect behavioral regressions.
- Trigger the evaluations: rerun the evaluation bench on any change touching memory, the prompt, or routing, wherever a behavioral regression is possible, and track the score per capability over time.