Evaluating & Testing Agents

How do you know your agent (and your prompts, tools, and context) are actually getting better? You measure.

Build an eval set

A small set of representative tasks with known-good outcomes, kept in your repo:

evals/
  case-01-refactor/   task.md   expected.patch
  case-02-bugfix/     task.md   expected_test_green
  case-03-feature/    task.md   checklist.md

Run them repeatedly. Track pass rate over time.

What to measure

• Task success — did it meet the definition of done?
• Test pass rate — the most objective signal for code tasks.
• Edit precision — how much of the diff was necessary (smaller = better).
• Steps / cost — loops and tokens consumed.
• Safety violations — any disallowed action.

Techniques

Golden tests

Keep a handful of tasks whose correct answer you know cold. Run them after every change to your prompts or tools — a regression suite for your agent.

Human scoring

For open-ended tasks, rate output 1–5 on correctness, style, and completeness. Do it consistently and keep a spreadsheet.

A/B your prompts

Change one variable at a time (the system prompt, the tool description, the context), re-run the same eval set, compare.

Interpreting failures

| Failure | Likely cause | | --- | --- | | Wrong answer, confident | Bad context / retrieval missed the key file | | Loops without finishing | Unclear goal, missing stop signal | | Correct but slow | Tool descriptions unclear → extra calls | | Inconsistent | Prompt too vague, or model too weak |

Start tiny

Even five eval cases run before every agent change will transform your results. It's the same discipline as unit testing — applied to a system that's otherwise impossible to reason about.

Eval sets turn "the agent feels better now" into "the agent passed 9/10 tasks this week." Build one before you tune anything.