Skip to main content
Browser use gives a deep agent a browser that it controls through tools. The agent opens pages, reads what renders, clicks, types, and takes screenshots. Use it for work that happens on the web:
  • Actions with no public API: Book a restaurant reservation, complete a checkout, or research a topic by following links across sites.
  • End-to-end testing: QA a web app through its UI. Open SWE, LangChain’s open-source coding agent, gets a browser in each thread so it can open the app it changed and check the change in the UI.
To add a browser to a managed agent, see Browser use in Managed Deep Agents.

Understand the basics

An agent needs two components to use the web:

Use Stagehand with local or remote browsers

Stagehand provides browser tools that work with both local Chrome and remote Browserbase sessions. Choose where the browser runs without changing the tools your agent uses. Stagehand exposes three tools over one persistent browser: An element ID is valid only for the latest snapshot of the active page, so the agent takes a new snapshot after it navigates. Add these tools with StagehandMiddleware from langchain-stagehand. Pass a configured Stagehand client to the middleware, then include it in middleware. No MCP server, custom tool definitions, or browser system prompt is needed. For the full configuration reference, see the Stagehand integration.

Other browser tools

  • Playwright MCP: An MCP server from Microsoft that exposes Playwright browser actions. Connect it through an MCP adapter, with npx @playwright/mcp@latest as the command. See Model Context Protocol.
  • agent-browser: A browser CLI from Vercel Labs. Install it in a sandbox, and the agent runs commands such as agent-browser open and agent-browser snapshot through the execute tool.

Use Stagehand with Browserbase

This example gives a deep agent Stagehand tools that drive a Browserbase browser. The agent runs on your machine. The browser runs on Browserbase.
The middleware is proposed in langchain-browserbase#1 and is not published to PyPI yet. This example installs that revision from source. It requires Python 3.11 or later, LangChain 1.4.7 or later, and Stagehand 4.3.0 or later.
Install the middleware, Deep Agents, and the model integration:
Set your API keys:
Create the browser and pass its Stagehand client to the middleware:
Use ainvoke or astream: the browser tools are asynchronous. Your application owns the browser and closes it when finished. Keep it open across runs to reuse tabs and logins. The middleware leaves your system prompt unchanged and includes browser guidance in tool descriptions. For local Chrome, screenshots, and use with LangChain’s create_agent, see the Stagehand integration.
Snapshots can be long. To keep them out of the main agent’s context, give the browser tools to a subagent and let the main agent delegate browser tasks to it.

Choose a browser scope

Reusing a browser retains cookies and website logins, so the agent does not need to sign in on every turn. Choose which conversations share that state:
  • Thread scope: Keep one browser per conversation. Later turns reuse its tabs and logins; another conversation gets a separate browser. Participants in a shared thread can use its signed-in accounts.
  • User scope: Reuse browser login state across the same authenticated user’s conversations. For example, a person signs in to a booking site once, then requests another reservation in a new thread.
Do not reuse a personal browser session across unrelated users. Anyone whose agent can access that browser can act as its signed-in accounts. Use verified identity from your application’s authentication layer, not a user ID supplied in a prompt. StagehandMiddleware does not select a scope or manage session storage. Your application chooses which Stagehand client to supply. Reuse that client for sequential runs within the intended scope. Give concurrent agents separate clients and browsers to avoid conflicting navigation. Browser state is not part of a LangGraph checkpoint. Closing or replacing the browser can lose logins, and websites can expire them independently. Managed Deep Agents manages thread and user scope for you, including separate per-thread windows with shared login state for user scope.

Test an app with Chrome in a LangSmith sandbox

This example covers end-to-end testing: after a coding agent changes an app, an agent opens the app in a browser and checks the change. Open SWE gets its browser from Managed Deep Agents. The steps below build the same check with a LangSmith sandbox. A LangSmith sandbox runs your app and Chrome together, so the browser can open the app at localhost. The agent runs on your machine and uses the LangSmithSandbox backend for filesystem access and an execute tool. This example uses agent-browser through execute, rather than MCP. Each CLI call reuses the named qa browser session inside the sandbox. You do not need a Browserbase account or a Docker daemon on your machine.

Prepare the sandbox snapshot

A snapshot contains the filesystem and dependencies for new sandboxes. Create one containing your app, its dependencies, Node.js, and curl. During snapshot setup, install agent-browser and Chrome for Testing:
Run installation as the same user that runs the browser. The Linux dependency installer requires permission to install system packages. Capture the prepared filesystem as a snapshot and keep its ID. For snapshot creation and capture, see Create a snapshot from a running sandbox. Set these variables on the machine that runs the agent:
Replace QA_START_COMMAND with your app’s start command. The examples expect it to serve port 3000 inside the sandbox.

Create the QA agent

The code starts the app, waits for it to respond, and opens the browser. The agent then interacts with the UI through execute. Download screenshots before cleanup: deleting the sandbox deletes its files. Install the host-side packages:
The examples disable Chrome’s internal sandbox with --no-sandbox for root-run sandbox images. The disposable LangSmith sandbox supplies the outer isolation boundary. For images that support Chrome’s internal sandbox, omit that flag. The screenshot is an artifact downloaded to your machine, not an image automatically shown to the model. For model-visible images, see Multimodal inputs. Use independent assertions for deterministic test results: an agent’s report and its instructions are not a security boundary.

Secure browser sessions

Code that runs in the browser can use any account the session is signed in to and any site the browser can reach. Before you give an agent a browser:
  • For Stagehand, use Browserbase as the isolation boundary for untrusted tasks. run executes model-authored JavaScript inside the browser. See Stagehand’s security boundary.
  • For the sandbox QA path, the LangSmith sandbox is the isolation boundary. The disposable sandbox isolates Chrome and the app from your machine.
  • Use test accounts and test payment methods for checkout and form flows, and require approval before any action that commits a purchase.
  • Treat page content as untrusted input. A page can contain text written to redirect the agent.
  • Keep credentials in your application environment, not in prompts or browser tool inputs. When using MCP, pass the server only the credentials it needs.

See also