Debug Stagehand act/extract runs with a local timeline

Try the trace viewer 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 before wiring a real Stagehand page.

Wrap a Stagehand page

from stagehand import Stagehand
from browsertrace import Tracer
from browsertrace.integrations.stagehand import wrap_stagehand

tracer = Tracer()
stagehand = await Stagehand(...).init()
page = wrap_stagehand(stagehand.page, tracer, name="stagehand checkout run")

await page.goto("https://example.com")
await page.act("click the checkout button")
await page.extract("get the order total")
page.bt_run.close()

The wrapper records goto, act, extract, observe, and click calls while preserving the original page methods.

Arguments and keyword arguments are saved as model_input. Successful Stagehand return values are written back to the same trace step as model_output.

What the trace captures

1. The Stagehand method and instruction.
2. The current page URL.
3. A screenshot before the action when available.
4. The successful Stagehand result, including observe or extract output when returned by the wrapped method.
5. Step status and exception text if the action fails.
6. Exportable HTML with optional model I/O redaction.

Share only what is safe

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 before attaching a real trace to a public issue or community thread. Use individual redaction flags when you want to keep some fields visible.