Debug custom computer-use agents with browser state and model I/O

When a custom computer-use agent fails, a normal log rarely shows what the model saw, which page state changed, or where the first wrong browser action entered the run. BrowserTrace gives those steps a local timeline.

View repo Open exported trace Integration snippet Feedback issue

Try the local demo first

uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace doctor
uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace demo
uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace

Open http://127.0.0.1:3000 and inspect the failed checkout-agent run. The demo does not require an API key. From a source checkout, python examples/computer_use_loop_example.py creates a generic observe-decide-act trace for a custom agent loop.

Wrap your agent loop

from browsertrace import Tracer

tracer = Tracer()

async with tracer.run("custom computer-use agent") as run:
    await page.goto("https://example.com")
    await run.snapshot(page, action="opened task page")

    observation = await describe_page(page)
    decision = await model.choose_next_action(observation)

    await page.click(decision["selector"])
    await run.snapshot(
        page,
        action=f"clicked {decision['selector']}",
        model_input=observation,
        model_output=decision,
    )

Use snapshot at the points where the model observes, chooses, or acts. BrowserTrace stores the current URL and screenshot from Playwright-compatible pages, plus the model input and output you provide.

What to capture at failure time

The page screenshot immediately before the model chose an action.
The URL and task state so redirects, modals, and stale pages are visible.
The model input, model output, chosen selector, and action label.
The first exception or failed assertion that stopped the run.
A public-safe HTML export when you need help debugging without leaking prompt or page data.

Export a trace for review

browsertrace list
browsertrace export <run_id> -o full.html
browsertrace export <run_id> --redact -o public.html
browsertrace export <run_id> --public -o public.html

Use --public for community posts and public issues. Keep the full trace local or share it only with people who should see screenshots, URLs, prompts, and model output.

BrowserTrace is intentionally runtime-agnostic. It works best when your computer-use agent exposes a Playwright-compatible page or a place in the loop where you can attach screenshots, URLs, actions, model inputs, and model outputs.