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":

1. Enable bounding box overlay
2. Navigate to the step where the click happens
3. See which button has the green box
4. Check if the wrong button was selected
5. 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:

1. Enable diff overlay
2. Navigate to the step after typing
3. Look for green areas (new content)
4. If no green areas appear, the search didn't trigger results
5. 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):

1. Enable heatmap overlay
2. See which search button has the highest importance score
3. Compare with the button you want it to click
4. 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:

1. Index loads first (fast, ~100KB)
2. Screenshots begin downloading in background
3. Progress indicator shows "Loading screenshots X/Y"
4. 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:

1. Step Header - Step number, status, goal
2. Screenshot (if enabled) - Full-page screenshot
3. Action Details - What the agent did
4. LLM Response (if enabled) - Raw LLM output
5. Execution Results - Success/failure, duration
6. 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 →