# Evaluation and testing

> You cannot improve an agent you cannot measure. This topic covers naming the qualities that matter, turning them into rubrics and metrics that resist gaming, grading the path the agent took as well as its answer, using a model as a judge, maintaining golden sets, analyzing errors and observing the agent in use.

Page: https://schubergphilis.github.io/ai-training/topics/building-agents/evaluation/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

*Building agents* · topic `building-agents/evaluation`

You cannot improve an agent you cannot measure. This topic covers naming the qualities that matter, turning them into rubrics and metrics that resist gaming, grading the path the agent took as well as its answer, using a model as a judge, maintaining golden sets, analyzing errors and observing the agent in use.

## Concepts

- **Quality pillars**: The distinct dimensions along which an agent can be good or bad: correctness of the result, faithfulness to sources, safety of actions, efficiency in steps and tokens, and adherence to instructions and format. Naming them separately matters because they trade off; an agent can score well on one while failing another, and one number hides that. [glossary](https://schubergphilis.github.io/ai-training/glossary/#quality-pillars)
- **Rubrics**: Written criteria that turn "good" into scorable statements: what a passing answer must contain, what disqualifies it, how partial credit is given. A rubric lets different graders, human or model, agree, and it makes the definition of quality reviewable and improvable. Writing one usually exposes disagreement about what the agent is for. [glossary](https://schubergphilis.github.io/ai-training/glossary/#rubrics)
- **Metrics that cannot be gamed**: A metric that can improve without the real quality improving will be optimized until it does exactly that. Length, keyword presence and self-reported success are easy to game; tests the agent cannot see, human spot checks and outcomes measured downstream are harder. Choose metrics that require the quality itself to move, and watch for divergence between the number and what users see. [glossary](https://schubergphilis.github.io/ai-training/glossary/#metrics-that-cannot-be-gamed)
- **Trajectory evaluation**: Grading the sequence of steps an agent took, not only its final output: did it call the right tools, in a sensible order, without dangerous or wasteful actions, and did it recover from errors. Two runs with the same answer can have very different trajectories, and the unsafe or lucky one will fail in production. Trajectories are also where error analysis starts. [glossary](https://schubergphilis.github.io/ai-training/glossary/#trajectory-evaluation)
- **LLM as judge**: Using a model to grade outputs against a rubric, so evaluation scales beyond what humans can read. It works well for criteria a careful reader could apply and poorly for facts the judge cannot check. Judges have biases, toward length, toward their own style, toward the first option, so calibrate them against human grades on a sample and re-check when the model changes. [glossary](https://schubergphilis.github.io/ai-training/glossary/#llm-as-judge)
- **Golden sets**: A curated set of inputs with expected outputs or qualities, covering typical cases, edge cases and past failures, run every time the agent, prompt or model changes. The golden set is the agent's regression suite. It should be representative of real use, grow with every production incident and stay small enough to run often. [glossary](https://schubergphilis.github.io/ai-training/glossary/#golden-sets)
- **Error analysis**: Reading failed runs one by one, classifying what went wrong and where, and counting the categories. It replaces guessing about what to fix with evidence: the most common failure is usually one thing, such as a tool schema or a retrieval miss, and fixing it moves the metric more than any general tuning. It is the highest-value activity in improving an agent. [glossary](https://schubergphilis.github.io/ai-training/glossary/#error-analysis)
- **Observability**: Recording what an agent does in real use so it can be inspected later: each model call, tool call, result, latency and cost, tied together as a trace per run. Observability turns a user complaint into a traceable run, feeds error analysis and the golden set, and shows drift when a model or dependency changes. Without it, production is a black box. [glossary](https://schubergphilis.github.io/ai-training/glossary/#observability)

## Links

- **Builds on:** [The agent loop and harness](https://schubergphilis.github.io/ai-training/topics/building-agents/agent-loop/), [Verifying agent work](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/verification/)
- **Leads to:** [Guardrails and production](https://schubergphilis.github.io/ai-training/topics/building-agents/production/)
- **Competencies drawing on it:** [Evaluates an agent's quality systematically](https://schubergphilis.github.io/ai-training/competencies/building-agents/evaluates-agents/)

## Lessons

- [Reading failures one by one](https://schubergphilis.github.io/ai-training/building-agents/error-analysis/) (explanation)
- [A golden set is the agent's regression suite](https://schubergphilis.github.io/ai-training/building-agents/golden-sets/) (tutorial)
- [A model as the grader](https://schubergphilis.github.io/ai-training/building-agents/llm-as-judge/) (tutorial)
- [Turning good into a rubric](https://schubergphilis.github.io/ai-training/building-agents/rubrics/) (explanation)
- [Recording and grading the path the agent took](https://schubergphilis.github.io/ai-training/building-agents/traces-and-trajectories/) (tutorial)

## Sources

- `AEC-09` [Evaluating and testing agents: quality pillars, metrics, trajectories, LLM as judge](https://lsimons.github.io/agent-engineer-course/09-evaluating-and-testing-agents/), Agent Engineer Course (course)
- `AEC-08` [Agentic RAG: the retrieve, evaluate, refine loop; when basic RAG is enough](https://lsimons.github.io/agent-engineer-course/08-agentic-rag/), Agent Engineer Course (course)
- `DLAI-11` [Agentic AI: M1 workflows and autonomy, M2 reflection, M4 evals and error analysis, M5 autonomous agents](https://www.deeplearning.ai/courses/agentic-ai), DeepLearning.AI (course)
- `Brilliant VER` Verification, Brilliant, Coding with AI skills map (reference)
- `Academy building-with-the-claude-api` [Building with the Claude API](https://academy.claude.com/courses/building-with-the-claude-api), Claude Academy (course)
- `Academy ai-native-sdlc-playbook` [The AI-native SDLC playbook](https://academy.claude.com/courses/ai-native-sdlc-playbook), Claude Academy (course)
- `OpenTelemetry GenAI spans` [Semantic conventions for generative client AI spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-spans.md), OpenTelemetry GenAI semantic conventions (reference)
- `OpenAI Academy evaluate-ai-applications-pxds7` [Evaluate AI Applications](https://academy.openai.com/public/courses/evaluate-ai-applications-pxds7), OpenAI Academy (course)