Stagehand + Browserbase integration

Stagehand is an open-source SDK for browser agents, backed by Browserbase—the complete platform to run agents that use the web like humans. The integration ships a ready-made MCP server that exposes three tools—run, snapshot, and screenshot—directly to your Deep Agent, with no custom tool definitions required.

Note

Stagehand ships this integration from its own repository. Clone the repo and run the examples from packages/integrations/deepagents.

Tools

Tool	Description
`run`	Execute JavaScript or snapshot actions against the active browser page
`snapshot`	Inspect the active page and hydrate bracketed element IDs for use in `run`
`screenshot`	Capture a screenshot of the rendered page

Setup

Prerequisites

Python 3.11–3.13
uv
A model-provider API key (e.g. OPENAI_API_KEY)
Local Chrome, or a Browserbase API key for a managed remote browser

Clone and install

git clone https://github.com/browserbase/stagehand.git
cd stagehand/packages/integrations/deepagents
uv sync --locked
uv sync --project examples/local --locked

Environment variables

# Model provider
export OPENAI_API_KEY="..."

# Browser: local Chrome (default) or Browserbase
export STAGEHAND_BROWSER="browserbase"    # omit to use local Chrome
export BROWSERBASE_API_KEY="bb_live_..."  # required for Browserbase

Use with a Deep Agent

The integration's MCP server (stagehand-deepagents-mcp) is launched over stdio by MCPAdapter. Use list_tools() to discover the tools and pass them to create_deep_agent — no manual tool definitions needed:

import asyncio
import os

import dotenv
from deepagents import create_deep_agent
from langchain.mcp import MCPAdapter

dotenv.load_dotenv()

BROWSER_INSTRUCTIONS = """You control one persistent browser through exactly three tools:
- snapshot: inspect the active page and hydrate bracketed element IDs.
- run: provide either snapshot actions or JavaScript using the Playwright-shaped page API.
- screenshot: inspect the rendered page visually.

Use snapshot actions for simple interactions and run code for multi-step workflows.
Snapshot IDs are valid only for the latest snapshot of the active page.
Snapshot again after navigation or stale IDs. Do not launch another browser.
"""

CONFIG = {
    "mcpServers": {
        "stagehand_browser": {
            "command": "uv",
            "args": ["run", "--project", ".", "--locked", "stagehand-deepagents-mcp"],
            "env": {
                k: v for k, v in os.environ.items()
                if k.startswith(("STAGEHAND_", "BROWSERBASE_")) and v
            },
        }
    }
}


async def main():
    async with MCPAdapter(CONFIG) as adapter:
        tools = await adapter.list_tools()
        agent = create_deep_agent(
            model="openai:gpt-4o",
            tools=tools,
            system_prompt=BROWSER_INSTRUCTIONS,
        )
        result = await agent.ainvoke({
            "messages": [{"role": "user", "content": "Go find me a summary of all main sports events today"}]
        })
    print(result["messages"][-1].content)


asyncio.run(main())

Warning

Keep the MCPAdapter context manager open for the duration of the agent run. The browser session and snapshot IDs are tied to the underlying stdio process — closing the adapter ends the session.

Server configuration

Variable	Default	Purpose
`STAGEHAND_BROWSER`	`local`	Select `local` or `browserbase`
`STAGEHAND_HEADLESS`	`false`	Run local Chrome headlessly
`STAGEHAND_START_URL`	Unset	URL to open when the server starts
`STAGEHAND_MODEL`	Unset	Optional — model for Stagehand AI methods called inside `run`; inference is provided by default if unset
`STAGEHAND_MODEL_API_KEY`	Unset	Optional — API key for `STAGEHAND_MODEL`; not required when using default inference
`STAGEHAND_RUN_TIMEOUT_MS`	`60000`	Timeout for JavaScript and snapshot-action batches
`BROWSERBASE_API_KEY`	Unset	Required for Browserbase