Stagehand + Browserbase integration

Stagehand is an open-source SDK for browser agents from Browserbase. StagehandMiddleware adds its run, snapshot, and screenshot tools to a LangChain or Deep Agents agent. Pass a configured Stagehand client to the middleware: no MCP server, custom tool definitions, or browser system prompt is needed. For use cases, browser scope, and a sandbox testing setup, see Browser use.

langchain-stagehand requires Python 3.11 or later, LangChain 1.4.7 or later, and Stagehand 4.3.0 or later.

Tools

Tool	Description
`run`	Acts on the active page. Pass either `code` (JavaScript that uses Playwright-style `page`, `context`, and `browser` objects) or `actions` (a batch of `click`, `hover`, `fill`, `type`, `press`, and `select` operations on snapshot IDs).
`snapshot`	Captures the active page’s accessibility tree and assigns the bracketed IDs that `run` actions use. Each call replaces the previous IDs.
`screenshot`	Returns a model-visible PNG or JPEG image. Accepts optional `fullPage`, `type`, and `quality` arguments. Use `quality` only with JPEG.

These are the two input shapes for run:

{ "code": "await page.goto('https://example.com'); return await page.title();" }

{ "actions": [{ "op": "click", "id": "1-42" }] }

Use an ID from the latest snapshot response instead of the illustrative 1-42 value. Take a new snapshot after navigation or when IDs become stale.

Setup

Install the middleware, Deep Agents, and a model integration:

pip install langchain-stagehand deepagents langchain-openai

Set the model-provider credential and your Browserbase API key:

export OPENAI_API_KEY="your-openai-api-key"
export BROWSERBASE_API_KEY="your-browserbase-api-key"

Use with a deep agent

Create a Browserbase browser, attach a Stagehand client, and pass the middleware to create_deep_agent:

import asyncio
import os

from deepagents import create_deep_agent
from langchain_stagehand import StagehandMiddleware
from stagehand import Stagehand, browserbase


async def main():
    browser = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])
    try:
        stagehand = await Stagehand.create(browser=browser)
        agent = create_deep_agent(
            model="openai:gpt-6.1-sol",
            middleware=[StagehandMiddleware(stagehand=stagehand)],
        )
        result = await agent.ainvoke({
            "messages": [{
                "role": "user",
                "content": "Open news.ycombinator.com, read the top three stories, and summarize each one.",
            }]
        })
        print(result["messages"][-1].content_blocks)
    finally:
        await browser.close()


asyncio.run(main())

Use ainvoke or astream: the browser tools are asynchronous. The middleware includes browser guidance in tool descriptions and leaves your system prompt unchanged. These tools use Stagehand’s Playwright-shaped facade and do not require a separate Stagehand model.

Use with LangChain

Keep the same browser setup and replace create_deep_agent with create_agent:

from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-6.1-sol",
    middleware=[StagehandMiddleware(stagehand=stagehand)],
)

Choose the browser

Your application configures the browser and Stagehand client directly, rather than through MCP server environment variables.

Browserbase: Use browserbase.launch(api_key=...) as in the example above. The browser runs remotely, so it cannot reach localhost on your machine or in a sandbox.
Local Chrome: Use local_browser.launch(headless=True) to run without a visible window. Chrome shares the application’s localhost and requires an installed Google Chrome or Chromium browser.

To use local Chrome, replace the browser launch and client setup with:

from stagehand import Stagehand, local_browser

browser = await local_browser.launch(headless=True)
stagehand = await Stagehand.create(browser=browser)
middleware = StagehandMiddleware(stagehand=stagehand)

Keep the same application-level try/finally cleanup. All Stagehand client settings remain available through Stagehand.create(...). To run Chrome next to your app with a LangSmith sandbox backend, see Test an app with Chrome in a LangSmith sandbox.

Manage browser lifetime

Your application owns the client and browser. The middleware reuses the supplied client across runs and does not close or recreate it. Keep the browser open to retain tabs and logins, then call await browser.close() when finished. If the browser disconnects, supply a new configured client. Choose whether to reuse login state within a thread or across one authenticated user’s conversations. The middleware does not implement scope selection, session storage, or browser checkpointing. Give concurrent agents separate clients and browsers. For the tradeoffs and user-isolation requirements, see Choose a browser scope. The screenshot tool returns images directly to the model. Screenshots saved by run code with a path go to the current working directory, not a Deep Agents backend. Backend artifact saving is not supported yet.

Require approval before actions

snapshot and screenshot only read the page. run navigates, clicks, types, and submits forms. To review each run call before it executes, keep the browser setup above and add interrupt_on and a checkpointer to the agent:

from langgraph.checkpoint.memory import InMemorySaver

agent = create_deep_agent(
    model="openai:gpt-6.1-sol",
    middleware=[StagehandMiddleware(stagehand=stagehand)],
    interrupt_on={"run": True},
    checkpointer=InMemorySaver(),
)
config = {"configurable": {"thread_id": "browser-1"}}

Pass config to ainvoke and keep the browser open while reviewing and resuming interrupts. Each interrupt lists the pending run arguments. For the approval and resume loop, see Human-in-the-loop.

Security

run executes model-authored JavaScript inside the Stagehand browser extension. That code can use any account the session is signed in to and any site the browser can reach. Use Browserbase as the isolation boundary for untrusted tasks. The Playwright-shaped API is not a general-purpose security sandbox. See Stagehand’s security boundary. Treat page content as untrusted input. Keep credentials in your application environment, not in prompts or browser tool inputs. Do not share personal browser sessions across unrelated users.

Browser use guide

Use cases, browser scope, and a sandbox testing setup.

Middleware source and examples

Native LangChain middleware, client lifecycle, and browser tools.

Stagehand Deep Agents docs

Upstream MCP alternative, including use with JavaScript agents.

Browserbase provider page

Browserbase setup, plus Search and Fetch tools.

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Popular Providers

Integrations by component

Stagehand + Browserbase integration

Tools

Setup

Use with a deep agent

Use with LangChain

Choose the browser

Manage browser lifetime

Require approval before actions

Security

Browser use guide

Middleware source and examples

Stagehand Deep Agents docs

Browserbase provider page

Tools

Setup

Use with a deep agent

Use with LangChain

Choose the browser

Manage browser lifetime

Require approval before actions

Security

Related resources

Browser use guide

Middleware source and examples

Stagehand Deep Agents docs

Browserbase provider page