agent-debugger

Breakpoints for AI-agent browser runs. Drops into pdb (or a custom callback) the moment a semantic event fires — antibot_detected, login_failed, MFA prompt, or any predicate you define on event data.

Two layers:

• Programming-language-level — Debugger is a drop-in replacement for agent_trace.Tracer. When a watched event fires, your Python process pauses. You can poke around with pdb, inspect agent state, then continue.
• Browser-level — supply a browser_pause callback to suspend the actual browser at the same instant (e.g., calling await page.pause() in Playwright opens the inspector right at the failure).

Built on top of agent-trace.

Install

pip install agent-debugger

Quickstart

from agent_debugger import Debugger

with Debugger(
    task="Log in to example.com",
    model="claude-opus-4-7",
    browser="playwright",
    break_on=["antibot_detected", "login_failed"],
) as d:
    d.step("Navigate to login")
    d.nav("about:blank", "https://example.com/login")
    d.antibot_detected("cloudflare_turnstile", 0.96, "iframe present")
    # process drops to pdb HERE
    # ...

Pause the actual browser too:

async with browser.new_context() as ctx:
    page = await ctx.new_page()

    with Debugger(
        task="...", model="...",
        break_on=["login_failed"],
        browser_pause=lambda et, d: page.pause(),  # opens Playwright inspector
    ) as d:
        ...

Custom predicate (not just event type):

Debugger(
    ...,
    predicate=lambda et, d: et == "antibot_detected" and d.get("confidence", 0) > 0.95,
)

Replay an existing trace

After a failed run, walk through the trace and pause at matches:

agent-debugger traces/<session>.jsonl --break-on antibot_detected --break-on login_failed

# Or with a predicate:
agent-debugger traces/<session>.jsonl -p "data.get('reason') == 'captcha'"

Output:

============================================================
[agent-debugger] event 7/14: antibot_detected at step 2
  data: {'vendor': 'cloudflare_turnstile', 'confidence': 0.96, ...}

  context:
    [1] step_start
    [1] nav
    [1] step_end
  → [2] antibot_detected
    [2] error
    [2] step_end
    [-1] session_end
============================================================
[enter] next match  ·  [q]+enter to quit:

Why this exists

Free-text logs make you read every line every time. agent-trace gives the events structure; agent-debugger uses that structure as the breakpoint table.

Built around three observations from running agents in production:

1. Most failures cluster on a handful of event types (antibot detection, login outcome, agent decision loops). Watching those four covers ~90% of incidents.
2. Live pdb at the moment of failure beats post-mortem log reading every time.
3. Pausing the browser at the same moment as the process is what unlocks real forensics — you can see the actual page state, not just the agent's interpretation of it.

CLI flags

agent-debugger <trace.jsonl> [--break-on EVENT]... [--predicate EXPR]

--break-on, -b   Event type to break on. Repeat for multiple. Common values:
                   antibot_detected, login_failed, mfa_prompt, error
--predicate, -p  Python expression returning bool. Locals: event_type, data
                 Example: -p "data.get('confidence', 0) > 0.95"

API surface

Debugger(*tracer_args, break_on=[], predicate=None, on_break=None, browser_pause=None, **tracer_kwargs)

All Tracer methods (step, nav, click, type, antibot_detected, login_failed, ...) pass through unchanged. The breakpoint check happens after the event is written — your trace stays complete even if you abort during pdb.

Roadmap

• Conditional resume. dbg.resume_after("login_success") — keep running until a specific event happens, then break again.
• Browser-level deep hooks. Optional CDP integration: hold the browser at the exact frame the event fired, freeze JS execution, dump live DOM.
• Time-travel. Use the trace to deterministically replay up to event N, then continue live. (Hard — depends on browser-level instrumentation in agent-browser.)

License

MIT.