Agent QA Patterns

Why Testing Agents Is Different

Agents make choices. They select tools, order actions, and generate natural language — all in ways that can vary across runs. Traditional unit tests fall short because they expect deterministic outputs. To build confidence in agent systems, we need patterns that embrace non‑determinism while still catching real regressions.

Core Principle: Test Behaviour, Not Outputs

Instead of comparing exact strings or action traces, verify that the agent respects invariants. Ask: Did it stay within its safety boundaries? Did it retrieve information before answering? Did the final response contain a valid citation? These behavioural checks remain stable even when surface outputs change.

Examples of Behavioural Checks

• The agent never mutates shared state without logging.
• Every source claim is backed by a retrieval call.
• Output complies with a JSON schema or a set of forbidden terms.
• Latency and token budgets stay within configured limits.

Pattern 1: Assertion Ranges

Replace exact‑match assertions with ranges that reflect acceptable variance. For a retrieval‑augmented Q&A agent, you might assert that the answer contains at least two out of five expected keywords — not all five. This pattern lets you catch drift without failing on every legitimate re‑ranking.

Implementation Sketch

Define a scoring function over the output and assert score ≥ threshold. Combine multiple weak signals (keyword overlap, embedding cosine similarity, factual entailment) into a single acceptance condition.

Pattern 2: Statistical Re‑runs

Run the same prompt multiple times and assert that the property holds in at least p% of runs. This smooths out transient failures caused by model sampling. For safety‑critical paths, raise the required percentage; for low‑risk paths, a lower bar still catches systemic breaks.

When to Use This Pattern

• Outputs depend on LLM sampling (temperature > 0).
• You are testing an agent loop with asynchronous tool calls.
• Flaky tests are masking real issues in CI.

Pattern 3: Gold‑Set Regression

Maintain a curated set of inputs where the correct behaviour has been reviewed by a human. Instead of checking exact outputs, compare the new run against the recorded behaviour using an evaluator agent. This judge agent answers a single question: “Is this new trace functionally equivalent to the approved one?”

Keeping Gold Sets Healthy

Rotate cases regularly — add new examples that exposed past failures and retire cases that no longer stress the system. Treat the gold set as a living asset, not a frozen snapshot.

Pattern 4: Contract Testing for Tool Calls

Agents rely on external tools. Test the interface contracts independently: for each tool, verify that known inputs produce expected outputs (or expected error shapes) regardless of which agent orchestrates them. This decouples tool reliability from agent reasoning.

Putting It All Together

A robust testing suite layers these patterns. Start with fast behavioural invariants to gate pull requests. Add statistical re‑runs for nightly builds. Reserve gold‑set comparison for release candidates. The combination gives you a safety net that flexes with the system rather than breaking against it.

Read the full essay and companion code examples on the Learning Index.