.tip

An agent run is a tree of model calls, tool calls, more model calls, retries and sub agents. Logs flatten it into a list. A trace keeps the tree, and can carry the messages that went into each model call as span attributes.

tracer.startActiveSpan("chat claude-sonnet-5", (span) => { ... });
tracer.startActiveSpan("execute_tool kb.read", (span) => { ... });

With the GenAI semantic conventions, the backend you already have can draw it. Open the first trace for a bad run and the bug is usually in there.