Tracing
View per-message agent traces — LLM calls, token usage, and tool executions — to debug and analyze your assistant.
Tracing gives you an inside look at how your assistant produced each reply. For every assistant message, the platform records each LLM call and each tool execution, along with token usage, duration, and status.
Tracing is the fastest way to answer "why did the assistant respond like that?" and "what made this reply slow or expensive?".
What Is Tracing?
A single assistant reply is not always one LLM call. When the assistant uses tools (knowledge base, MCP, custom APIs, etc.), it runs a tool loop: call the model → run the requested tools → feed results back → call the model again, until it has a final answer.
Tracing records each step of that loop:
- One LLM call entry per loop iteration (model, provider, tokens, duration, status).
- One tool execution entry per tool the model invoked (arguments, result, duration, outcome).
This is built-in observability — no external setup required.
How to Open Traces
- Go to the Admin Panel and open Assistants.
- Open an assistant, then go to Conversations.
- Select a conversation to view its messages.
- On any assistant message, click the Trace pill (activity icon) to open the Agent Trace Details dialog.
Only assistant messages have traces. User messages don't trigger LLM or tool calls, so there is nothing to trace.
Summary Bar
The top of the dialog summarizes the whole reply at a glance:
| Metric | Meaning |
|---|---|
| Call(s) | Number of LLM calls (loop iterations) for this message |
| Tokens | Total tokens consumed across all calls |
| Duration | Total time spent generating the reply |
| Tool(s) | Total number of tool executions across all calls |
Reading an LLM Call
Each LLM call is shown as a card. The header shows the model, a status badge, and the Loop # (tool-loop iteration, starting at 0). Expand a card to see full details.
| Field | Meaning |
|---|---|
| Model | The chat model that handled this call (e.g. gpt-5.6-luna) |
| Provider | The provider behind the model (e.g. openai, anthropic) |
| Status | completed, aborted, or error — see below |
| Loop # | Tool-loop iteration index (0 = the first call) |
| Time | When the call was made |
| Duration | How long the call took |
Token Breakdown
| Token | Meaning |
|---|---|
| Input | Tokens sent to the model (prompt, history, context, tool results) |
| Output | Tokens generated by the model |
| Total | Input + output |
| Cached | Input tokens served from the provider's prompt cache (cheaper) |
| Reasoning | Internal reasoning tokens, for models that think before answering |
Cached and Reasoning only appear when they are greater than zero. Cached tokens lower cost; reasoning tokens are extra work the model does internally before producing the visible answer.
Tool Executions
When the assistant uses tools, the call card lists each tool execution. Each row shows the tool name, a type badge, and its duration. Expand a row for details:
| Detail | Meaning |
|---|---|
| Action | The outcome of the tool call (see table below) |
| Time | When the tool ran |
| Args | The arguments the model passed to the tool (JSON) |
| Result | A summary of what the tool returned |
| Error | The error message, if the tool failed |
Tool Types
| Badge | What it is |
|---|---|
| builtin | Server-side built-in tools (knowledge base, memory, web, etc.) |
| mcp | Tools provided through MCP (endpoints and MCP servers) |
| custom | Your own custom HTTP API tools |
Tool Actions
| Action | Meaning |
|---|---|
| REQLLM | Result was sent back to the model to continue the loop |
| RESPONSE | Tool produced the final response directly |
| NONE | Tool ran but returned nothing to act on |
| ERROR | Tool failed — check the error message |
Args and Result are sanitized and truncated for safety and readability — they are summaries, not the full raw payloads.
Trace Status
| Status | Meaning |
|---|---|
| completed | The call finished normally |
| aborted | The call was stopped early (e.g. the user interrupted / barged in) |
| error | The call failed — inspect the trace and tool errors for the cause |
Common Use Cases
Debug a wrong answer — check which tools were called, what arguments were passed, and what each tool returned. A bad result or wrong arguments usually explains an off-topic reply.
Analyze cost — total tokens map directly to credit usage. Use traces to spot which messages are expensive and why. See Credits.
Diagnose slow replies — compare the duration of each loop iteration and each tool. A slow external tool or many loop iterations is often the bottleneck.
Related
- Tools & MCP — the tools that appear in your traces
- AI Models — the models shown in each LLM call
- Credits — how token usage maps to cost