Debug a single agent conversation

When an agent gives a wrong answer, the question is rarely “what did it say” — you already know that. The question is why: which knowledge-base chunk it grounded on, which tool it called, where the time went, and what that turn cost. The conversation debug view answers all of that in one place, one turn at a time, so you don’t have to reconstruct the run from model-provider logs and vector-store queries by hand. This guide walks the debug view end to end: where it lives, what each turn card shows, and two worked troubleshooting loops — a latency isolation and a cost-spike trace.

1. When you need it

Aggregate logs tell you a conversation happened; the debug log tells you how each turn was built. Reach for it in these failure modes:

The agent picked the wrong knowledge-base chunk. The retrieval section of the turn card shows every chunk the run considered — document name, chunk index, similarity score, and a content preview — so you can see exactly which document mis-grounded the answer.
A latency spike. Each turn splits total latency into prep (context assembly, retrieval, prompt construction) and graph (model + tool execution), so you can tell whether the slowdown is on the retrieval leg or inside the graph, rather than staring at one aggregate number.
A tool misfire. The tool-calls section records the tool name, the input arguments, and the output for every call in the turn — including calls the agent made internally that never surfaced in the transcript.
Cost drift. Every turn carries its cost in cents. When a conversation’s spend jumps at turn 12, you find which turn and which tool did it.

If none of those apply, the standard transcript view is the right surface. The debug view is for operator drill-down.

2. Where it lives

Open the agent from Agents, go to its Conversations list, and drill into one conversation. The debug page sits at /agents/<agent-id>/conversations/<conversation-id>/debug — one card per turn, oldest first. Access is restricted to the owner, admin, and developer roles, and the restriction is enforced on both sides: the route gate in the dashboard and a requireRole pre-handler on every debug endpoint. A customer-facing member or a supervisor sees the transcript, not the raw tool arguments and retrieval previews. Two API endpoints back the view:

GET /agents/conversations/{conversationId}/debug-log — paged list of turns (defaults to 100 per page, capped at 500).
GET /agents/conversations/{conversationId}/debug-log/{turnId} — one turn with its full tool-call and retrieval payloads. The list endpoint intentionally returns only counts; the wide blobs load lazily when you expand a turn.

Both return 404 for a conversation that doesn’t exist in your tenant, before any turn data is read.

3. What each turn carries

Each turn card shows, top to bottom:

Field	What it tells you
`turn_index`	Position of the turn in the conversation (0-based).
`user_message`	The inbound message that opened the turn.
`latency split`	`prep_latency_ms` (context + retrieval) and `graph_latency_ms` (model + tools), plus the turn total `latency_ms`.
`tokens_used`	Tokens the run consumed this turn.
`cost_cents`	What this turn cost, in cents.
`model`	The model that produced the response.
`tool_call_count` / `retrieval_count`	How many tool calls and retrieval hits the turn contains.

Expand the card to load the full payloads:

Tool calls — for each call: tool (name), input (the arguments the model sent), and output (what came back). Long outputs collapse behind a details toggle.
Retrieval hits — for each hit: documentName, chunkIndex, score (similarity, 0–1), and contentPreview (the chunk text the model saw). Where a document id is present the hit links into the knowledge base so you can open the raw chunk.
Assistant response — the full text the agent replied with, unabridged.

A worked list row (what the paged endpoint returns per turn; blobs projected out):

{
  "id": "turn_9f2e1c",
  "conversation_id": "conv_4b8110",
  "agent_id": "agent_support_1",
  "turn_index": 11,
  "user_message": "What is your returns window?",
  "assistant_response": null,
  "tokens_used": 2431,
  "cost_cents": 0.84,
  "latency_ms": 1840,
  "prep_latency_ms": 612,
  "graph_latency_ms": 1228,
  "tool_call_count": 1,
  "retrieval_count": 3,
  "model": "claude-sonnet-4",
  "created_at": "2026-09-08T14:22:41Z"
}

And the same turn expanded, from the single-turn endpoint:

{
  "turn": {
    "id": "turn_9f2e1c",
    "tool_calls": [
      {
        "tool": "lookup_order",
        "input": { "order_id": "A-10482" },
        "output": { "status": "delivered", "eligible": true }
      }
    ],
    "retrievals": [
      {
        "source": "knowledge_base",
        "score": 0.91,
        "documentName": "returns-policy.pdf",
        "chunkIndex": 4,
        "contentPreview": "Returns are accepted within 30 days of delivery…"
      }
    ]
  }
}

Treat cost_cents as the operator read of spend, not the billing record. The per-turn figure is the runtime’s accounting of what the turn consumed; the billing-truth aggregation comes from the agent-usage callback that settles usage against the wallet. When the two disagree, the callback wins.

4. Walkthrough: a slow turn and a wrong chunk

An ops operator is investigating a support agent whose answers got slow mid-conversation and whose returns answer cites the wrong policy.

Open the debug view for the conversation. The badge next to the title shows how many turns loaded; long threads page in 100-turn slices with a load-more control at the bottom.
Find the slow turn. Scan the latency split column. Turn 11 shows 1,840 ms total where surrounding turns run 700 to 900 ms. The split reads 612 ms prep / 1,228 ms graph; both legs run hot, but graph dominates, so this isn’t a pure retrieval stall.
Isolate the retrieval leg. Expand turn 11. Three retrieval hits came back; the top hit is returns-policy.pdf chunk 4 at 0.91 — high similarity but the preview text is the obsolete 30-day policy, not the current 14-day one. The graph leg didn’t slow down on its own; it chewed on a long, wrong chunk.
Confirm the source. Follow the retrieval hit’s link into the knowledge base. The document is tagged policy-2024 when it should be policy-2024-deprecated; the current policy document carries the active tag.
Re-tag and re-run. Re-tag the document in the knowledge base, then fork the conversation from the debug header (Fork conversation) to branch the transcript into a what-if variant. The fork lands you on the new variant’s debug view, where you re-ask the returns question. The new turn’s retrieval shows the active policy chunk at a comparable score and the graph leg drops back into its normal band.

The fork doesn’t mutate the original conversation — it copies the transcript as a starting context, so you can compare before and after without touching the production thread.

5. Cost troubleshooting

The same drill works backwards from spend. Suppose the conversation’s total cost jumped at turn 12:

Sort or scan the turn list on cost_cents; turn 12 reads 3.9 cents where the rest of the conversation averages 0.6.
Expand that turn. Its tool_call_count is 1, and the tool call is search_web — a tool with a real per-call price — invoked with a broad query the model generated after a vague user prompt.
The response itself was a two-sentence answer; the spend came from the tool, not the tokens. Either gate that tool behind an approval (see Supervise pending tool approvals) or narrow the prompt so the model reaches for it less.

Because each turn carries its own cost, this takes one screen instead of a billing-export diff.

6. Set expectations with customers

The debug view is an operator-only drill-down, and it reads like one: raw tool arguments, chunk previews, internal model names, per-turn cost. It is not a customer-facing playback of the conversation and it never becomes one — the role gate (owner/admin/developer) applies at the route and the API, and the endpoints return nothing to a session without one of those roles. When a customer asks “why did the agent say that,” the deliverable you hand them is the plain-language finding you draw from the debug view (“the agent grounded on a deprecated returns policy; we’ve re-tagged the document”), not a screenshot of this page. If they need a shareable artifact, the conversation export suits that; the debug log suits your own diagnosis.

7. Export and downstream use

When a turn-level record needs to leave the dashboard — an incident review, a prompt-tuning session in another tool, a regression case for the evals pipeline — use the execution-trace export endpoints on the same role gate:

GET /agents/{agentId}/conversations/{conversationId}/execution-trace/export renders the conversation’s trace as a portable payload.
POST /agents/{agentId}/conversations/{conversationId}/execution-trace/push pushes the same trace to a configured destination.

The 30-day debug log is the operational surface; the export is how you keep a trace past that window or hand it to tooling outside the dashboard.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Debug a single agent conversation turn by turn

Debug a single agent conversation

1. When you need it

2. Where it lives

3. What each turn carries

4. Walkthrough: a slow turn and a wrong chunk

5. Cost troubleshooting

6. Set expectations with customers

7. Export and downstream use

​Debug a single agent conversation

​1. When you need it

​2. Where it lives

​3. What each turn carries

​4. Walkthrough: a slow turn and a wrong chunk

​5. Cost troubleshooting

​6. Set expectations with customers

​7. Export and downstream use

Debug a single agent conversation

1. When you need it

2. Where it lives

3. What each turn carries

4. Walkthrough: a slow turn and a wrong chunk

5. Cost troubleshooting

6. Set expectations with customers

7. Export and downstream use