Execution traces

Every run produces a full execution trace: a step-by-step record of exactly what the agent did, in order. Traces are streamed live while a run is in progress and remain browsable afterward.

What a trace records

Each step in the agentic loop is recorded as it happens:

• The tool the model chose to call
• The arguments it passed to that tool
• The tool's output

This applies to every tool type — code_execution, api_call, knowledge_search, connector_action, MCP tools, and subagent delegation — so the trace is a complete, ordered account of the run, not a summary.

Live streaming

While a run is active, its trace streams over SSE (server-sent events). You see each step appear as it completes, rather than waiting for the run to finish. If you close the tab or lose connection mid-run, the run keeps executing — the trace is still there, fully recorded, when you come back to view it.

Browsing a finished run

After a run completes (successfully, with a failure, or paused on a pending approval), its trace stays available for you to open and read step by step. This is the primary way to answer "what did the agent actually do" for any given run.

Explain this run

On top of the raw trace, you can ask for an "Explain this run" narration: an LLM-generated summary of what happened, in plain language, built over a secret-scrubbed version of the trace. Because the input to the narration has secrets stripped out, this feature is safe to use even on runs that touched credentials or connector calls.

If the run failed, the same narration surfaces a diagnosis of what went wrong along with a suggested fix, rather than leaving you to read raw tool errors yourself.

Using traces to debug

When a run doesn't do what you expected, the trace is the first place to look:

1. Open the run and read the trace step by step to find where behavior diverges from what you intended.
2. Check the arguments passed to the tool at that step — a wrong argument is often the model working correctly on bad input, not a bug in the tool.
3. Check the tool's output for that step — a malformed or unexpected response there explains why later steps went wrong.
4. If the run failed outright, start with "Explain this run" for a diagnosis and suggested fix before digging into individual steps.
5. If a step required approval and the run halted there, that's expected behavior for a destructive tool call — approve or reject it explicitly rather than treating it as a failure.

Traces are also the input for guardrails redaction checks — if you're not seeing a secret you expect to be scrubbed, that's a guardrails configuration issue rather than a tracing one.