Skip to main content
A long agent trace can span dozens of LLM and tool calls, which makes reading it end to end impractical. Braintrust offers two Loop-powered analyses for this: the Debugger, which diagnoses why a trace went wrong, and the Guide, which explains what a trace did. Running either Run debugger or Generate guide produces both a Debugger report and guide sections in the Timeline layout. Choose the Debugger to review failure hypotheses, or Timeline to follow the work performed. Both are available on traces in your project logs. They don’t appear on experiment or dataset traces, or in embedded and human review contexts.
The Debugger is in public preview and can change before reaching general availability.

​
Diagnose a failure

Use the Debugger when you know a trace went wrong but not why, and the trace is too long to read span by span. Loop identifies the failure modes it considers likely and cites the evidence behind each one, so you start from something concrete instead of scrolling.
1

Open the trace

Open a trace from the Logs page and select the Debugger tab.
2

Run the debugger

Click Run debugger. If a report already exists for the trace, the button reads Run again. While Loop works, a Debugger progress panel shows the steps completed so far and the elapsed time, and its menu offers View in Loop and Run again.The Debugger uses your Loop provider and model. Select to change the model for this run. If no compatible provider is configured, the button is disabled. Hover over it to see a link to your AI providers settings.
3

Read the report

See What’s in a report for how it’s organized.
4

Follow the evidence

Select any evidence item to jump to that span in the trace, scrolled to the field it came from with the supporting phrase highlighted.If you use the new thread view, the evidence is also highlighted in the thread, so you can read each finding in the context of the conversation.
5

Continue in Loop

To take a diagnosis further, click Continue in Loop on the report and ask follow-up questions against the full project. See Analyze traces.
A run takes a few minutes, and longer on a trace with many spans or very large inputs. You don’t have to wait on the page. A run is recorded on the trace rather than in the browser tab that started it, so it survives a reload or a switch to another tab, and a teammate who opens the same trace sees it in progress. If the last run didn’t produce a report, whether it failed or it ended without writing one, the Debugger says so in a banner above Run debugger, with the error when there is one. Re-run the Debugger after you’ve changed the underlying behavior and logged a new trace, or when you want a second pass on the same one.

​
What’s in a report

A report from the Debugger opens with a Summary of what Loop found, followed by one entry per failure mode. The tab shows a count once findings exist. Each finding carries a title, a severity of critical, high, medium, or low, and a short label for the area it relates to, such as infrastructure, evaluation, or tool_call. Severity is medium when Loop doesn’t specify one, so treat that level as unranked rather than as a deliberate judgment. Within a finding:
  • Hypothesis is what Loop believes went wrong.
  • Potential root cause is why it believes that happened.
  • Evidence lists the spans, tool calls, and model outputs behind the finding.
  • Next steps, when Loop has something specific to suggest, are the smallest useful actions to take.
When Loop has actions that cut across findings rather than belonging to any one of them, the report ends with its own Next steps list. A finding that relates to a recorded pattern also shows a badge with the pattern’s name. Select it to open the pattern and see the other traces behind it. That finding’s Next steps carries the pattern’s Suggested fix.
Treat the Debugger’s findings as a starting hypothesis with evidence attached, not a verdict. Each finding points at the spans it came from so you can check the reasoning yourself.

​
Summarize what a trace did

Generate a guide when you want to understand an unfamiliar trace rather than diagnose it, and answer “what happened here” before deciding whether anything went wrong.
  1. Open a trace from the Logs page and select the Timeline () layout.
  2. Click Generate guide in the timeline header. Click it again to regenerate the guide on a trace that already has one. If no compatible provider is configured, the button is disabled. Hover over it to see a link to your AI providers settings.
  3. Review the Guide: Collapsible timeline groups that explain the work performed by LLM and tool spans. Unassigned spans appear under Uncategorized. Selecting a span in a collapsed section automatically expands it. To see the timeline without sections, select Spans in the timeline header. Select Guide to return.
Duration scales with the trace size. Expect a couple of minutes on a long agent trace, and longer on one carrying very large inputs. As with the Debugger, the result is recorded on the trace rather than in your browser tab, so you can navigate away and come back to it, and a teammate who opens the same trace sees the same guide sections.

​
Where the Debugger fits

Scheduled Patterns investigations use the Debugger to inspect individual traces and support their findings. You can navigate between a pattern and its evidence:
  • From a pattern: On the Patterns page, select span evidence to open the trace beside the pattern. The source field and quoted terms are highlighted when available.
  • From a Debugger report: Findings from patterns that cite the trace link back to those patterns. These findings can come from earlier investigations, even without a full analysis of the trace.
If the trace has no guide sections, click Run debugger or Generate guide to generate both views. Results you or a teammate already generated are available in both layouts.

​
Next steps