Debug a Browser Use Agent with Laminar

This guide sets up a browser-use agent with the Laminar debugger end to end: record a run, find the step that went wrong, and rerun from that point with the earlier LLM calls served from cache. Browser runs are slow and every rerun costs real minutes, which makes Browser Use exactly the kind of agent the debugger is built for.

1. Install prerequisites

Install uv if you do not already have it:

pip install -U uv

Create a virtual environment and install dependencies:

uv venv --python 3.11
source .venv/bin/activate
uv pip install lmnr browser-use python-dotenv

Install the Browser Use Chromium bundle:

uvx browser-use install

If your Browser Use LLM provider needs extra packages or env vars, follow the provider setup in the Browser Use docs.

2. Run Laminar setup

npx lmnr-cli@latest setup

setup logs you in, links the directory to a Laminar project, and writes LMNR_PROJECT_API_KEY to your .env file. See debugger setup for what else it does.

Add your LLM provider key to the same .env. For Claude:

ANTHROPIC_API_KEY=your_anthropic_api_key

Replay caching is served through Laminar’s provider integrations. With ChatAnthropic or ChatOpenAI, cached calls on a replay run come back instantly. With other providers (including ChatBrowserUse), recording and rerunning still work, but every LLM call on a rerun goes live.

3. Create the entrypoint

Instrumentation is one call: Laminar.initialize() before the agent is created. Browser Use is auto-instrumented, so every LLM step and browser action lands in the trace, along with a session recording of the browser synced to the trace.

agent.py

import asyncio
from dotenv import load_dotenv

from browser_use import Agent, ChatAnthropic
from lmnr import Laminar

load_dotenv()
Laminar.initialize()

async def main(prompt: str):
    llm = ChatAnthropic(model="claude-opus-4-5", temperature=0.0)
    agent = Agent(task=prompt, llm=llm)
    history = await agent.run()
    print(history.final_result())

if __name__ == "__main__":
    asyncio.run(
        main("go to ycombinator.com, summarize 3 startups from the summer 2025 batch.")
    )

4. Record a run

Run the agent with debug mode on:

LMNR_DEBUG=true python agent.py 2>&1 | tee run.log
grep 'LMNR_DEBUG_RUN' run.log

The SDK starts a debug session, opens it in your browser, and writes .lmnr/debug-session.json so later runs in this directory rejoin the same session automatically. When the run finishes, the LMNR_DEBUG_RUN line carries the run’s trace_id.

5. Find the step that went wrong

Open the trace from the session view and read the transcript: each Browser Use step is an LLM turn with the actions it chose, and the synced browser recording shows what the page actually looked like at that moment. Find the LLM call before the step you want to change and copy its span id (hover the span row and click Copy span ID), or locate it with SQL:

npx lmnr-cli sql query "
  SELECT span_id, name, start_time
  FROM spans
  WHERE trace_id = '<trace-id>' AND span_type = 'LLM'
  ORDER BY start_time ASC"

6. Change and rerun from the checkpoint

Edit the agent (the task prompt, the model, Agent settings, your own tool code), then rerun with replay armed:

LMNR_DEBUG=true \
LMNR_DEBUG_REPLAY_TRACE_ID=<trace-id> \
LMNR_DEBUG_CACHE_UNTIL=<span-id> \
python agent.py 2>&1 | tee run.log

LLM calls up to and including that span are served from the recorded trace; everything after runs live against the real browser. The rerun lands as a new trace in the same session, next to the original, so you compare attempts side by side. Repeat until the step behaves, then run the loop again from step 4 whenever a new issue shows up.

This whole loop is what a coding agent runs for you with the Laminar skill installed: it records, reads the trace, edits the code, and replays on its own. See the debugger process.

What’s next

The debugger process

Sessions, notes, SQL inspection, replay, and evals, step by step.

How caching works

What gets cached, the input hash, and which integrations support it.

Browser Use integration

Full tracing reference for Browser Use, including session recordings.

Viewing traces

Read the transcript view: inputs, LLM turns, tool calls, and recordings.