> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notte.cc/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
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
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
Understand agent execution
Optimize agent settings
Build reliable agents
Watch sessions in real-time