Browserbase MCP agent

This example connects to Browserbase's archived local MCP server over stdio. The repository is a historical reference; see Browserbase's hosted MCP setup for new integrations.

import asyncio
import os
from textwrap import dedent

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.mcp import MCPTools


def require_env(name: str) -> str:
    value = os.environ.get(name)
    if not value:
        raise RuntimeError(f"Set {name} before running this example.")
    return value


async def main() -> None:
    require_env("OPENAI_API_KEY")
    browserbase_env = {
        name: require_env(name)
        for name in (
            "BROWSERBASE_API_KEY",
            "BROWSERBASE_PROJECT_ID",
            "GEMINI_API_KEY",
        )
    }

    async with MCPTools(
        command="npx -y @browserbasehq/mcp",
        env=browserbase_env,
        timeout_seconds=120,
    ) as browserbase_tools:
        agent = Agent(
            model=OpenAIResponses(id="gpt-5.2"),
            tools=[browserbase_tools],
            instructions=dedent("""\
                Create a concise Hacker News digest.

                1. Call `start` to open a Browserbase session.
                2. Call `navigate` with the Hacker News URL.
                3. Use `extract` to collect the top stories. Use `observe` and `act` only when needed.
                4. Call `end` after collecting the information.

                Include story titles, links, and a short summary of the main themes.
            """),
            markdown=True,
        )
        await agent.aprint_response(
            "Create a digest from https://news.ycombinator.com.",
            stream=True,
        )


if __name__ == "__main__":
    asyncio.run(main())

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Prepare Node.js

Install Node.js 20 or later, then verify that npx is available:

node --version
npx --version

Install Python dependencies

uv pip install -U "agno[mcp]" openai

Export API keys

export BROWSERBASE_API_KEY="your_browserbase_api_key"
export BROWSERBASE_PROJECT_ID="your_browserbase_project_id"
export GEMINI_API_KEY="your_gemini_api_key"
export OPENAI_API_KEY="your_openai_api_key"

Run the agent

Save the code above as stagehand.py, then run:

python stagehand.py

Available Tools

Tool	Purpose
`start`	Create or reuse a Browserbase session
`navigate`	Navigate to a URL
`observe`	Find actionable elements on the current page
`act`	Perform a natural-language action on the page
`extract`	Extract structured data from the current page
`end`	Close the active Browserbase session

See Browserbase MCP setup for hosted transport and advanced configuration.