Reading a trace

The trace is the record of one run: what the agent read, which tools it called and what each returned, what it decided, what it handed off and to whom, what it cost, and how it ended. It is continuous across handoffs, so an item that passed through three agents reads as one sequence rather than three.

Read it in this order

1. 1

   The outcome, at the bottom

   Settled, handed off, waiting, stopped or failed. This tells you which kind of question you are asking. A stop is correct behaviour and a failure is not, and reading a week of stops as failures is the most common misdiagnosis there is.

2. 2

   The tool calls, in the middle

   Not the agent's reasoning — what came back. Most surprising behaviour is a tool that returned less than expected, an empty list where there should have been three rows, a field the provider stopped sending. The agent then reasoned correctly from bad input.

3. 3

   The inputs, at the top

   What the agent was given to start with. If the tool calls look right and the outcome still looks wrong, the question moves here: did it receive the item you think it received.

What a handoff looks like inside a trace

A handoff carries the item, the evidence gathered so far, the run history, and a reason written by the agent handing off. The reason reads slightly oddly — an agent explaining itself to a colleague — and it is the field support asks for first, which is why it has survived two attempts to remove it.

Cost

Each run records what it consumed. A run that retried twice was metered three times, and the trace shows all three attempts rather than only the one that worked. If an agent's spend looks higher than its output suggests, the retries are usually where it went.