Conversation Debugger

Conversation Debugger The Conversation Debugger reads the full transcript of a single conversation — messages, tool calls, prompts, context — and uses the model to identify the root cause of a problem turn. It returns a structured analysis with the offending sequence, the evidence and concrete recommendations.

What It Does

Manual debugging of a long agent conversation is tedious. The Debugger automates the part you’d do by hand: read every turn, find where the trouble started, and explain what went wrong in terms of the agent’s configuration.

It is an AI-assisted analysis — the model reads the conversation and produces a structured verdict. You provide the conversation Id and an optional instruction (e.g. “why didn’t the agent send the email?”); the Debugger returns its analysis as a structured object.

The Analysis Result

Field	Meaning
`rootCause`	A short statement of what actually went wrong — not the symptom, the underlying cause.
`problemAtSequence`	The message sequence number where the problem originated. Click through to that turn in the transcript to see the offending exchange.
`evidence`	The specific quote, tool call, missing context, or assembled prompt fragment that supports the diagnosis.
`recommendations`	A short list of concrete fixes — e.g. add a tool, edit a prompt, expand a context-field config.
`severity`	`low`, `medium` or `high` — how serious the problem it found is, not how sure it is. There is no confidence score.
`stopReason`	The model’s stop reason for the agent run being analysed (`end_turn`, `max_tokens`, `stop_sequence`). The UI surfaces this so you can spot truncated responses immediately.
`creditsUsed`	Credits consumed by the analysis call.
`rawAnalysis`	If the structured JSON couldn’t be parsed, the raw model output is returned here as a fallback.
`error`	Populated for non-exception failures — credit limit reached, license restrictions, configuration issues.

What the Debugger Inspects

For the conversation under analysis the Debugger sees the same data that drove the original run, plus the run’s outputs:

The agent’s assembled system prompt — persona, instructions, schema and language directives
The tools the agent had available, with categories, tiers and channels
The context-field configuration and the actual record context that was loaded
Every user and assistant message in sequence
Every tool call — tool name, input, output (or error)
The token usage and stop reason for each agent turn
Your optional natural-language instruction (e.g. “why is the answer empty?”)

That’s the full picture the Debugger needs to reach a useful conclusion — nothing is hidden behind a black box.

Agent Runtime Preview shows what an agent will load on the next conversation. Free and read-only. Use it to verify configuration before any conversation happens.
Conversation Transcript shows the raw messages and tool calls. Free, no analysis.
Conversation Debugger applies AI analysis to the transcript and returns a diagnosis. Costs credits, but produces an actual root-cause statement and recommendations.

Use the Transcript when you can read a short conversation in your head; use the Debugger when the conversation is long, the symptom is subtle, or you want a second opinion.

How a Run Works

Open the conversation
Either from the REDA AI Admin tab’s conversation list or directly from a Salesforce link to the underlying Conversation record.
Click Debug Conversation
The Debugger UI loads the transcript and tool history.
Add an instruction
If you have a specific question (“why didn’t it call send_email?”, “why was the response in the wrong language?”), enter it. Without an instruction, the Debugger looks for any obvious issue across the conversation.
Run the analysis
The platform sends the conversation context to the model and waits for the structured response.
Read the result
Root cause, problem sequence, evidence, recommendations and severity are rendered alongside the transcript so you can verify the analysis against the actual exchange.
Apply the recommendations
Fixes typically land in the agent definition, a custom prompt, a context-field config, or a tool. Rerun a similar conversation after the fix to confirm.

Severity and stopReason

The analysis carries a severity — high, medium or low — describing how serious the problem it found is, not how sure the Debugger is about it. There is no separate confidence score. high points to a clear configuration issue worth fixing now; medium to something worth looking at; low often means the conversation was an edge case rather than a bug.

Alongside it you get Problem at sequence — the message number where the analysis says things went wrong, so you can go straight to that turn in the transcript — and Evidence, the excerpt the conclusion rests on. Read the evidence before acting on the recommendation; it is what lets you disagree with the Debugger when it is wrong.

Pay separate attention to stopReason:

end_turn — the model finished cleanly. The diagnosis is about content, not infrastructure.
max_tokens — the response was truncated by the response budget. Often the actual cause when the agent “fails to answer”. Increase the agent’s output budget or simplify the prompt.
stop_sequence — the model hit a configured stop. Less common; usually expected.

The UI surfaces stopReason directly so you can recognise truncation before reading the rest of the analysis.

Don't confuse the viewer's own limits with the model's. To keep the report readable, the Debugger shortens what it displays: message content at about 500 characters and tool context at about 2,000. Text ending mid-sentence in the report is usually just that display limit — the truncation that matters is the one stopReason reports as max_tokens.

Credit Cost & Time

Each analysis is one model call. Credit cost scales with the conversation’s length and the size of the assembled context the Debugger sees. The platform reports the credits actually consumed.

Long conversations with many tool calls cost more credits and take longer to analyse because more transcript is sent to the model.

What the Debugger Does Not Do

It doesn’t fix anything automatically. The output is a diagnosis with recommendations; you apply the fixes manually in the agent definition, prompts, tools or context fields.
It doesn’t run the conversation again. The analysis is on the transcript that already exists. To validate a fix, run a similar conversation and (optionally) debug that one too.
It doesn’t guarantee a single root cause. Some conversations have several issues; the Debugger picks the most likely root cause but should be paired with your judgement.
It doesn’t replace the Incident Log. Hard failures (Apex exceptions, callout errors) land in the Incident Log. The Debugger is for behavioural problems where the conversation completed but the outcome was wrong.

Best Practices

Start with an instruction. An empty Debugger run produces a generic analysis. Telling the Debugger what bothered you about the conversation focuses the diagnosis.

Read stopReason first. If the response was truncated, fixing the budget is usually a single-character change, not a prompt rewrite.

Verify the evidence quote. The Debugger names the offending sequence and quotes evidence. Click through to that turn before accepting the recommendation; sometimes the model misreads.

Apply one recommendation at a time. Apply the most actionable recommendation, run a similar conversation, then iterate. Multiple simultaneous changes muddy the cause-and-effect.

Pair with the Runtime Preview after fixes. Once you’ve adjusted the agent, open the Runtime Preview to confirm the fix actually changed what the agent sees.

Frequently Asked Questions

No. It produces a diagnosis with concrete recommendations. You apply the fixes manually — usually small edits to a prompt, a tool, or a context-field configuration.

Yes. Async runs produce conversation and message records identical to sync runs; the Debugger inspects them the same way. See Async Agent Processing.

The model occasionally returns text that can’t be parsed into the expected JSON shape. When that happens, the raw text is returned in rawAnalysis as a fallback so the analysis isn’t lost. Re-running usually produces a clean structured response.

Yes. Every channel produces the same conversation and message records. The Debugger reads those records directly, so the channel doesn’t matter.

Re-run with a more specific instruction telling the Debugger what was wrong. low severity often means the analyser couldn’t pin the issue without more context. A targeted instruction usually upgrades the severity if the bug is real.

Hard failures land in the Incident Log. For those, use the incident-debugging tool. The Conversation Debugger handles the cases where the conversation ran but the outcome was wrong.

The Debugger’s recommendations point at things you can change — prompts, context, tools. If the analysis says “the model behaved correctly given the configuration”, that’s a direct hint that you need to change the configuration, not blame the model.

Next Steps

Read Conversation Transcripts for the underlying record structure the Debugger reads, or Debug with AI on Incidents for the same pattern applied to hard failures.

← Previous: Scheduled Actions

Next: AI Incident Logs →