Docs/Studio/Trace Debugger

Trace Debugger Interface

Master the Trace Debugger to analyze agent execution step-by-step with complete visual context.

Overview

The Trace Debugger is Studio's primary interface for inspecting agent runs. It provides a cinematic, step-by-step playback of your agent's execution with:

Complete visual context - Screenshots at every step
Detailed execution data - LLM responses, actions, and verification results
Interactive timeline - Navigate through execution history
Visualization overlays - See what the agent saw and why it acted

[Image Placeholder: Full Trace Debugger interface]

Interface Layout

The Trace Debugger uses a 65/35 split layout optimized for analyzing visual behavior:

Header Bar

[Image Placeholder: Header bar with goal, run ID, and controls]

Located at the top, the header shows:

Back Button - Return to Trace List
Goal - The agent's objective (e.g., "Buy a laptop from Amazon")
Run ID - Unique identifier for this trace
Loading Mode Badge:
- "Fast mode (index only)" - Lightweight mode for quick browsing
- "Full trace loaded" - Complete trace data loaded
Export Button - Export trace to PDF

Timeline Scrubber

[Image Placeholder: Timeline with multiple steps, some green, some red]

The timeline shows all steps in the execution:

Status Colors

Green - Step succeeded (action + verification passed)
Yellow - Partial success (action succeeded, verification failed)
Red - Step failed (action or verification failed)

Interaction

Click any step - Jump directly to that step
Hover - See step number and status
Current step - Highlighted with a border

Screenshot Viewer (65%)

[Image Placeholder: Large screenshot panel with overlays]

The left panel displays the webpage screenshot:

Overlay Controls

Three toggle buttons at the top-right corner:

[Image Placeholder: Three overlay toggle buttons]

Box - Bounding box overlay
Diff - Visual diff overlay
Heatmap - Element importance overlay

Screenshot Features

High-resolution - JPEG format at 80% quality
Exact moment - Captured before the action executed
Zoom - Click to zoom in on details
Prefetching - Screenshots load in background for smooth playback

Detail Panel (35%)

[Image Placeholder: Detail panel showing step information]

The right panel shows detailed information about the current step. See the Detail Panel documentation for complete details.

Quick summary:

Step goal and action
Pre/post-action URLs
LLM response text
Execution details
Verification results
Performance metrics

Video Controls

[Image Placeholder: Bottom control bar with play/pause and speed controls]

Located at the bottom:

Previous Step (← button) - Go back one step
Play/Pause (▶/⏸ button) - Auto-play through steps
Next Step (→ button) - Advance one step
Speed Control - Dropdown to adjust playback speed
- 0.5x - Slow motion
- 1x - Normal speed (default)
- 2x - Double speed
- 4x - Fast forward
Step Counter - "Step X of Y"

Visualization Modes

Studio provides three powerful visualization overlays to help you understand agent behavior.

Bounding Box Overlay

Shows element interactions with visual rectangles:

[Image Placeholder: Screenshot with colored bounding boxes around elements]

What It Shows

Target elements - Which elements the agent interacted with
Element boundaries - Exact size and position of elements
Click coordinates - Precise interaction points

Color Coding

Green boxes - Successful interactions
Red boxes - Failed interactions
Blue boxes - Elements considered but not selected

When to Use

Debugging element selection - Verify the agent clicked the right element
Understanding failures - See if the target element was visible
Visual validation - Confirm element detection accuracy

Example Use Case

Your agent is supposed to click "Add to Cart" but keeps clicking "Save for Later":

Enable bounding box overlay
Navigate to the step where the click happens
See which button has the green box
Check if the wrong button was selected
Review why the agent chose that element (check Detail Panel)

Diff Overlay

Highlights visual changes between consecutive steps:

[Image Placeholder: Diff overlay showing changes in different colors]

What It Shows

Added content - New elements that appeared
Removed content - Elements that disappeared
Modified content - Elements that changed

Color Coding

Green areas - Content added to the page
Red areas - Content removed from the page
Yellow areas - Content that was modified

When to Use

Verifying actions - Confirm the action changed the page as expected
Finding dynamic content - Identify elements that appear/disappear
Debugging navigation - See what changed after clicking a link
Understanding failures - Check if expected changes occurred

Example Use Case

Your agent types in a search box but doesn't see results:

Enable diff overlay
Navigate to the step after typing
Look for green areas (new content)
If no green areas appear, the search didn't trigger results
Investigate why (check if Enter was pressed, if there's a delay, etc.)

Heatmap Overlay

Visualizes element importance scores:

[Image Placeholder: Heatmap overlay with color gradient showing element priorities]

What It Shows

Element importance - How much the agent "cared" about each element
Attention distribution - Where the agent focused its analysis
Priority ranking - Which elements were considered most relevant

Color Gradient

Bright red/orange - Highest importance (agent's top focus)
Yellow - Medium importance
Blue/dim - Low importance
No color - Not considered relevant

When to Use

Understanding decisions - See why the agent chose a specific element
Debugging misclicks - Check if the wrong element had higher importance
Improving prompts - Understand what the agent prioritizes
Visual debugging - See the agent's "attention map"

Example Use Case

Your agent keeps clicking the wrong "Search" button (there are multiple on the page):

Enable heatmap overlay
See which search button has the highest importance score
Compare with the button you want it to click
Adjust your semantic query to better target the correct element

Combining Overlays

You can enable multiple overlays simultaneously:

Box + Heatmap - See which high-importance elements were clicked
Diff + Box - Verify that clicking an element caused expected changes
All three - Complete visual analysis (can be overwhelming)

Screenshot Prefetching

Studio optimizes performance by prefetching screenshots in the background.

[Image Placeholder: Screenshot prefetch progress indicator]

How It Works

When you open a trace:

Index loads first (fast, ~100KB)
Screenshots begin downloading in background
Progress indicator shows "Loading screenshots X/Y"
Playback is smooth once screenshots are cached

Benefits

No loading delays - Screenshots ready before you need them
Smooth playback - No stuttering when advancing steps
Instant navigation - Jump to any step without waiting

Progress Indicator

Located in the top-right of the header:

Animated download icon - Screenshots loading
Progress bar - Visual progress (green bar)
Counter - "5/20" (5 loaded out of 20 total)
Disappears - Once all screenshots are loaded

Fast Mode vs Full Trace

Studio uses intelligent loading to optimize performance:

Fast Mode (Index Only)

[Image Placeholder: "Fast mode (index only)" badge]

What loads:

✅ Timeline and step status
✅ Screenshots (prefetched)
✅ Basic step metadata
❌ Full LLM responses
❌ Detailed execution data
❌ Verification signals

When it's used:

Initial page load
Traces with many steps (>10)
Quick browsing without deep inspection

Full Trace Loaded

[Image Placeholder: "Full trace loaded" badge]

What loads:

✅ Everything from Fast Mode
✅ Complete LLM responses
✅ Detailed execution data
✅ Verification signals
✅ Performance metrics

When it's used:

Automatically loads when viewing step details
When enabling Diff Overlay (requires snapshot data)
After 5-second timeout if Fast Mode fails
Small traces (few steps)

Automatic Loading

Studio automatically switches from Fast Mode to Full Trace when:

You click a step in the Detail Panel
You enable Diff Overlay
Byte-range loading fails or times out

PDF Export

Export traces as PDF reports for documentation, sharing, or compliance.

[Image Placeholder: PDF export dialog with options]

Opening Export Dialog

Click the Export PDF button in the header (top-right corner).

Export Options

[Image Placeholder: Export options checkboxes]

Include Screenshots

Enabled - Each step includes the screenshot (large file size)
Disabled - Text-only report (smaller file size)

Recommendation: Enable for visual debugging, disable for quick reports.

Include LLM Responses

Enabled - Full LLM response text for each step
Disabled - Only action summaries

Recommendation: Enable for deep analysis, disable for executive summaries.

Include Verification Details

Enabled - Detailed verification signals and outcomes
Disabled - Only pass/fail status

Recommendation: Enable for debugging, disable for high-level overviews.

PDF Structure

The exported PDF contains:

Cover Page

Trace goal
Run ID
Total steps
Final status
Duration
Export date

Executive Summary

Success rate
Total steps (successful/partial/failed)
Performance metrics
Key findings

Step-by-Step Report

For each step:

Step Header - Step number, status, goal
Screenshot (if enabled) - Full-page screenshot
Action Details - What the agent did
LLM Response (if enabled) - Raw LLM output
Execution Results - Success/failure, duration
Verification (if enabled) - Detailed signals

Use Cases

Bug Reports - Share trace with development team
Client Demos - Show agent capabilities to stakeholders
Compliance - Document agent actions for audit trails
Training - Create training materials from real executions
Documentation - Archive agent behavior for reference

File Size Guidance

Typical export sizes (20-step trace):

Minimal (no screenshots, no LLM, no verification): ~500KB
Standard (screenshots, no LLM, no verification): ~5MB
Detailed (screenshots, LLM, no verification): ~8MB
Complete (all options): ~10MB

Keyboard Shortcuts

Speed up navigation with keyboard shortcuts:

| Shortcut | Action | |----------|--------| | Space | Play/Pause auto-playback | | ← (Left Arrow) | Previous step | | → (Right Arrow) | Next step | | Home | Jump to first step | | End | Jump to last step | | B | Toggle Bounding Box overlay | | D | Toggle Diff overlay | | H | Toggle Heatmap overlay | | E | Open Export dialog | | Esc | Close Export dialog |

Pro Tip: Use Space + arrow keys for rapid step-by-step analysis.

Performance Tips

For Large Traces (100+ steps)

Use Fast Mode initially
Enable Full Trace only when needed
Disable unused overlays
Export without screenshots for faster processing

For Slow Connections

Wait for screenshot prefetch to complete
Reduce playback speed (0.5x or 1x)
Avoid toggling overlays rapidly
Use Fast Mode when possible

Browser Compatibility

Recommended browsers:

✅ Chrome 90+ - Best performance
✅ Edge 90+ - Best performance
✅ Firefox 88+ - Good performance
✅ Safari 14+ - Good performance

Next Steps

Deep Dive: Master the Detail Panel →
Organize: Learn about Trace List management →
Enable Tracing: Set up SDK tracing →

Trace List

Detail Panel