> ## Documentation Index
> Fetch the complete documentation index at: https://notte-experiment-visibility-md-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Replay & Debugging

> Debug agents with visual replays and step-by-step inspection

Debug agent executions with MP4 replays that show exactly what the agent saw and did during its run.

## Agent Replay

Get a visual replay of the agent's execution. The `session.replay()` method returns a
`ReplayResponse` with a presigned URL you can use to download the MP4 file:

{/* @sniptest testers/agents/replay/basic_replay.py */}

```python theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Navigate and extract data")

# Get MP4 replay (returns presigned URL)
replay = session.replay()

# Download to file
replay.download("agent_run.mp4")
```

## What's Included

Agent replays capture:

* **Visual recording** of every page the agent visited
* **Actions taken** by the agent (clicks, fills, navigations)
* **Page transitions** and loading states
* **Element highlights** showing what the agent interacted with
* **Timestamps** for each action

## Viewing Replays

### In Jupyter Notebook

Display the replay inline:

{/* @sniptest testers/agents/replay/view_in_notebook.py */}

```python view_in_notebook.py theme={null}
with client.Session() as session:
    agent = client.Agent(session=session)
    agent.run(task="Complete task")

replay = session.replay()
replay.download("notebook_replay.mp4")
```

### Save to File

Save for later viewing or sharing:

{/* @sniptest testers/agents/replay/save_to_file.py */}

```python save_to_file.py theme={null}
with client.Session() as session:
    agent = client.Agent(session=session)
    agent.run(task="Complete task")

replay = session.replay()
replay.download("debug_run.mp4")

# With custom path
output_dir = Path("./replays")
output_dir.mkdir(exist_ok=True)
replay.download(output_dir / f"agent_{agent.agent_id}.mp4")
```

### In Browser

Use the Notte Console to view replays:

{/* @sniptest testers/agents/replay/view_in_browser.py */}

```python view_in_browser.py theme={null}
result = agent.run(task="Complete task")

# Get replay URL
print(f"View replay: https://console.notte.cc/sessions/{session.session_id}")
```

## Debugging Workflow

### 1. Run Agent

Execute your agent task:

{/* @sniptest testers/agents/replay/run_agent.py */}

```python run_agent.py theme={null}
agent = client.Agent(session=session, max_steps=15)
result = agent.run(task="Find and click the pricing button")
```

### 2. Check If Failed

Identify failures:

{/* @sniptest testers/agents/replay/check_if_failed.py */}

```python check_if_failed.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Complete task")

if not result.success:
    print(f"Agent failed: {result.answer}")
print(f"Completed {len(result.steps)} steps")
```

### 3. Inspect Steps

Review what the agent did:

{/* @sniptest testers/agents/replay/inspect_steps.py */}

```python theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Complete task")

    for i, step in enumerate(result.steps):
        print(f"Step {i + 1}: {step['action']}")
        print(f"  Success: {step['success']}")
        if not step["success"]:
            print(f"  Error: {step['message']}")
```

### 4. Watch Replay

See the visual execution:

{/* @sniptest testers/agents/replay/watch_replay.py */}

```python watch_replay.py theme={null}
with client.Session() as session:
    agent = client.Agent(session=session)
    agent.run(task="Complete task")

replay = session.replay()
replay.download("debug_replay.mp4")

# Watch where it failed
# Identify if element selectors were wrong
# Check if page loaded correctly
```

### 5. Fix and Retry

Adjust based on findings:

{/* @sniptest testers/agents/replay/fix_and_retry.py */}

```python theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Maybe increase max_steps
    agent = client.Agent(session=session, max_steps=25)

    # Or adjust the task
    result = agent.run(task="Click the 'View Pricing' button in the main navigation")
```

## Common Issues

### Agent Can't Find Element

**Symptoms:**

* Agent fails with "Element not found"
* Replay shows element exists but wasn't clicked

**Debug:**

{/* @sniptest testers/agents/replay/debug_missing_element.py */}

```python theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Complete task")

replay = session.replay()
replay.download("missing_element.mp4")

# Watch replay and check:
# - Did page finish loading?
# - Is element visible/in viewport?
# - Is element covered by another element?
```

**Fix:**

{/* @sniptest testers/agents/replay/fix_missing_element.py */}

```python fix_missing_element.py theme={null}
agent = client.Agent(session=session)
# Be more specific in task
task = "Wait for the page to load, then click the blue 'Submit' button at the bottom"

# Or use session actions first
session.execute(type="goto", url="https://example.com")
time.sleep(2)  # Wait for load
result = agent.run(task="Click submit button")
```

### Agent Takes Wrong Action

**Symptoms:**

* Agent clicks wrong button
* Agent fills wrong form field

**Debug:**

{/* @sniptest testers/agents/replay/debug_wrong_action.py */}

```python theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Fill the email field")

    # Check what agent saw
    for step in result.steps:
        print(f"Action: {step['action']}")
        print(f"Reasoning: {step.get('reasoning', 'N/A')}")
```

**Fix:**

{/* @sniptest testers/agents/replay/fix_wrong_action.py */}

```python theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Be more specific
    task = "Fill the email input field in the signup form with user@example.com"

    # Or disable vision if causing confusion
    agent = client.Agent(session=session, use_vision=False)
```

### Agent Exceeds Max Steps

**Symptoms:**

* Agent stops before completing task
* `len(result.steps) == max_steps`

**Debug:**

{/* @sniptest testers/agents/replay/debug_max_steps.py */}

```python theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Complete task")

    print(f"Steps taken: {len(result.steps)}")
    print(f"Max steps: {agent.request.max_steps}")

replay = session.replay()
replay.download("debug_replay.mp4")  # See where it got stuck
```

**Fix:**

{/* @sniptest testers/agents/replay/fix_max_steps.py */}

```python theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Increase max_steps
    agent = client.Agent(session=session, max_steps=30)

    # Or break task into smaller steps
    result1 = agent.run(task="Navigate to products page")
    result2 = agent.run(task="Search for laptops")
```

## Advanced Debugging

### Step-by-Step Analysis

Inspect each step in detail:

{/* @sniptest testers/agents/replay/step_by_step_analysis.py */}

```python step_by_step_analysis.py theme={null}
result = agent.run(task="Complex task")

for i, step in enumerate(result.steps):
    print(f"\n=== Step {i + 1} ===")
    print(f"Action: {step.get('action')}")
    print(f"Success: {step.get('success')}")
    print(f"Page URL: {step.get('url')}")
    print(f"Message: {step.get('message')}")
```

### Comparing Runs

Compare successful vs failed runs:

{/* @sniptest testers/agents/replay/comparing_runs.py */}

```python theme={null}
from notte_sdk import NotteClient

client = NotteClient()

# Successful run
with client.Session() as session_1:
    agent_1 = client.Agent(session=session_1)
    result_success = agent_1.run(task="Working task")
replay_success = session_1.replay()
replay_success.download("success.mp4")

# Failed run
with client.Session() as session_2:
    agent_2 = client.Agent(session=session_2)
    result_fail = agent_2.run(task="Failing task")
replay_fail = session_2.replay()
replay_fail.download("failure.mp4")

# Compare side-by-side
# Identify where behavior diverges
```

### Agent Status During Execution

Monitor agent in real-time:

{/* @sniptest testers/agents/replay/monitor_status.py */}

```python monitor_status.py theme={null}
with client.Session() as session:
    agent = client.Agent(session=session)
    agent.start(task="Long running task")

    while True:
        status = agent.status()

        if status.status == "closed":
            break

        print(f"Steps: {len(status.steps)}")

        time.sleep(5)

# Get replay after completion
# replay = session.replay()
# replay.download("replay.mp4")
```

## Best Practices

### 1. Always Review Failed Agents

Don't ignore failures - watch the replay:

{/* @sniptest testers/agents/replay/review_failed_agents.py */}

```python review_failed_agents.py theme={null}
with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Critical task")

if not result.success:
    replay = session.replay()
    replay.download(f"failure_{agent.agent_id}.mp4")
    print(f"Saved replay for debugging: failure_{agent.agent_id}.mp4")
```

### 2. Save Replays for Production Issues

Keep replays of production failures:

{/* @sniptest testers/agents/replay/save_production_replays.py */}

```python save_production_replays.py theme={null}
    result = agent.run(task="Production task")
    if not result.success:
        replay = session.replay()
        replay.download(f"prod_failure_{agent.agent_id}.mp4")
        logger.error(f"Agent failed, replay saved: prod_failure_{agent.agent_id}.mp4")
except Exception as e:
    logger.error(f"Agent exception: {e}")
```

### 3. Use Replays for QA

Verify agent behavior before deploying:

{/* @sniptest testers/agents/replay/replays_for_qa.py */}

```python replays_for_qa.py theme={null}
with client.Session() as session:
    agent = client.Agent(session=session)
    # Test run
    result = agent.run(task="Test checkout flow")

# Review replay before production
replay = session.replay()
replay.download("qa_replay.mp4")

# Verify:
# - All steps completed correctly
# - No unexpected behavior
# - Performance is acceptable
```

### 4. Share Replays with Team

Save and share for collaboration:

{/* @sniptest testers/agents/replay/share_with_team.py */}

```python share_with_team.py theme={null}
with client.Session() as session:
    agent = client.Agent(session=session)
    agent.run(task="Feature test")

replay = session.replay()
replay.download(f"feature_test_{agent.agent_id}.mp4")

# Share file with team
# Or share console link
print(f"Console replay: https://console.notte.cc/sessions/{session.session_id}")
```

## Limitations

Replays are currently:

* ✅ Available for all completed agents
* ✅ Full video recording of execution
* ✅ Include element highlights
* ⚠️  Generated after completion (not real-time)
* ⚠️  May be large files for long runs

## Next Steps

<CardGroup cols={2}>
  <Card title="Lifecycle" icon="rotate" href="/features/agents/lifecycle.md">
    Understand agent execution
  </Card>

  <Card title="Configuration" icon="sliders" href="/features/agents/configuration.md">
    Optimize agent settings
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/guides/reliability.md">
    Build reliable agents
  </Card>

  <Card title="Live View" icon="eye" href="/features/sessions/live-view.md">
    Watch sessions in real-time
  </Card>
</CardGroup>