Logging and tracing agent runs

When an agent gives a wrong answer, you need to see what it did. Ordinary application logs are not enough, because the interesting part is the sequence of decisions.

One id for the whole run

Give every run a run id and attach it to every log line and every external call. Without it you cannot tell which lines belong together once several runs overlap.

Log the steps

For each step, record:

• the step name and its start and end time
• which model was called, and with how many input and output tokens
• which tool was called, with its arguments
• the outcome, including errors and retries

Use structured logs, such as JSON, so you can filter by run id and step.

Be careful with content

Prompts and tool results can contain personal or confidential data. Decide what is safe to store, redact secrets and personal fields, and set a retention period. Sometimes it is enough to log sizes and hashes instead of full text.

Use traces

A trace shows one run as a tree of timed spans: the run, each step inside it, and each model or tool call inside those. Tools built on OpenTelemetry can draw this, and it makes slow steps and repeated retries easy to spot.

Questions the data should answer

• Why did this run take four minutes?
• Which tool fails most often?
• How many tokens does a typical run use?
• What did the model see just before it made the wrong call?

If your logs can answer these, debugging becomes much faster.