9.9 Evaluating and observing agents

What this is and why it exists

An agent that succeeds twice as often is better. An agent that succeeds equally often at twice the cost in three times the steps is worse, and a success-rate number will not tell you that. Agent evaluation has to look at the path as well as the outcome, which means recording what actually happened — every model call, every tool call, every decision — because a run you cannot examine is a failure you can only guess at.

The vocabulary

• Trajectory — the full sequence of steps a run took.
• Outcome evaluation — judging only the final result.
• Trajectory evaluation — judging the path as well.
• Trace — the recorded structure of a run, with each step nested inside its caller.
• Span — one recorded operation within a trace.
• Steps to completion — how many actions a task took.
• Cost per task — the total spend for one completed task.
• Replay — re-running a recorded case after a change.

The mental model

Outcome evaluation asks whether the answer was right. Trajectory evaluation asks how it got there, and the two come apart in both directions.

A run can reach the right answer badly: fifteen steps where four would do, three tools called and abandoned, the same search repeated, the answer found by accident on the last attempt before the limit. That is a success by outcome and a system about to fail, because it succeeded with no margin and the next slightly harder task will exhaust the budget. An agent that stumbles to a correct answer is not reliable, it is lucky, and outcome-only measurement cannot distinguish the two.

A run can also take a good path to a wrong answer — correct tools, sensible order, and a source that was out of date. That is a data problem wearing a failure, and only the path shows it.

So judge both, and the trajectory questions are specific enough to be checkable: did it choose the right tools, in a sensible order, without repeating itself, without calling anything unnecessary, and did it stop when it had enough?

Tracing is the observability layer, and without it agent debugging is guesswork. Record for every run: each model request with its full prompt, each response, each tool call with its arguments, each result, each decision, with timing and cost attached, and — the part that matters — nested so a step sits inside the step that caused it. A flat log of events is much harder to read than a tree that shows what led to what.

You have a choice of purpose-built services for this or the open standard for distributed tracing, and the argument for the open standard is worth stating: it is the same tracing your other services already use, so an agent's run appears in the same picture as the database query and the third-party request it triggered — which is where the latency frequently turns out to be. Whatever you choose, instrument from the first day. Adding tracing after an incident means the incident cannot be investigated, and these systems produce incidents that are impossible to reconstruct from their outputs alone.

Three practical notes. Redact before storing, because traces contain everything users typed, which is the privacy point from the safety topic. Sample deliberately if volume is high — keep all failures, keep all expensive runs, sample the successful cheap ones. And attach identifiers linking a trace to the user, the task and the version of the prompt and model, since without those you cannot answer whether last week's change helped.

Three numbers describe agent quality, and reporting one of them hides the others.

Task success rate: how often it completes correctly, judged against a defined standard rather than "it produced something".

Steps to completion: how much work a task took. This is the leading indicator — it moves before the success rate does. A change that leaves success unchanged and raises the average steps has made the agent worse and bought you nothing, and it will show up as a cost increase and then, on harder tasks, as failures against the step limit.

Cost per task: the total spend for one completed task, which is not the average per call times the steps, because the transcript grows and later calls cost more.

Report all three, and report the distribution rather than the mean. The mean hides the tail, and in agent systems the tail is where the money goes — a small share of tasks taking many times the median steps is the normal shape, and those are the ones that hit limits and generate complaints. Watch the ninety-fifth percentile, not the average, and be able to see whether it is one kind of task or one kind of user.

Two more worth having: human intervention rate, how often somebody had to step in, which is the honest measure of whether an agent is actually saving work; and failure taxonomy, the mistakes grouped by cause, which is the error analysis habit from the language module and is where the plan for next week comes from.

Replay is the agent equivalent of a regression suite, and recorded runs are what make it possible.

Save real runs — especially the failures, the expensive ones and the ones a person had to rescue — with their inputs and the tool results they received. After a change, replay them and compare: same outcome, fewer steps, lower cost? Replaying with recorded tool results rather than live calls makes this fast, cheap and deterministic on the tool side, which isolates the change you are testing from whatever the outside world is doing today. Keep a live-call version too, run less often, because recorded results eventually stop resembling reality.

And measure against the alternatives, which is where this topic meets the first one. Report the agent's three numbers beside a fixed chain doing the same task, and beside a single model call where that is possible. If the agent is not better on the numbers that matter, the chain is the answer — and having built the measurement is what lets you say so with evidence rather than with a preference.

What you should now be able to explain or do

Distinguish outcome from trajectory evaluation and give a case where each alone misleads. Ask the five trajectory questions of a run. Instrument tracing with nesting, timing and cost, from the first day, with redaction, deliberate sampling and linking identifiers. Report success rate, steps and cost per task as distributions, watching the tail. Add intervention rate and a failure taxonomy. Build a replay suite from recorded runs, with and without live tool calls. Compare the agent against a chain on the same numbers.

Check yourself