State and the trace: State and traces

State is a fold over events

What one run leaves behind

An agent run has two things that are easy to mix up:

State: what the loop needs now to decide the next step: the messages so far, the step counter, the budget used.
Events: what happened, in order: the model decided X, the tool returned Y.

Keep the events as the source of truth, append-only, and derive the state by folding them: start empty, apply each event in order. Then the state can be rebuilt at any step, a crash loses nothing that was recorded, and a bug can be explained by reading the events up to that point. In the example, fold(events) rebuilds exactly the conversation the live loop had, and the totals of tokens and seconds.

Each step leaves two events and a run leaves a header and an ending:

Event	Records
header (once)	the task, the model id, the prompt version, the seed, the tool versions, the limits
model call, per step	the tool and arguments chosen, the model's text, everything it was shown, tokens and seconds
tool call, per step	the tool and arguments, the result, seconds, whether it was an error
end	the status (done, step limit, ...), the final answer, totals

What does the trace need to hold?

Work backwards from the questions you will ask when a run goes wrong. The example defines nine, and each question is a small function that tries to answer from a trace and returns nothing if the trace lacks what it needs. Recording the same run at five levels of detail:

Level	Records	Answers	Size per run
0 answer only	status and final answer	what was the answer?	0.1 KB
1 calls	+ which tools, with which arguments	which tools were called?	1.0 KB
2 calls and results	+ the model's text, + tool results	what did each tool return? which step sent the wrong date? can I replay it?	1.4 KB
3 model inputs too	+ everything the model saw	what did the model see at step 2?	3.3 KB
4 versions, seed, costs	+ versions, tokens, seconds, why it stopped	cost? why did it stop? which model and prompt ran?	3.8 KB

Questions you can answer, by how much the trace records

Reading the matrix:

Level 0 tells you only that it failed. That is what most logs are, and it answers none of the useful questions.
Level 2 is the big step: with the model's outputs and the tool results you can find the step that went wrong, and you can replay the run exactly. This costs little, 1.4 KB for a three-step run.
Level 3 (the model's full input) is the most expensive field and the most useful when you ask "what did it see?". In this toy the input can be rebuilt from the earlier events (a test checks it), but in a real agent the input also includes the system prompt, tool descriptions and retrieved text, so either store it or store a hash and a prompt version that identify it.
Level 4 adds the facts you need to compare runs: a change in answers is often a change in model, prompt or tool version, and the trace is the only place that is written down.

Tip: the prompt version is not optional

Put a version (or a content hash) on the prompt, the tool descriptions and each tool's code, and record them in the header. Without them, "it worked last week" cannot be investigated.