Stagehand SDK

The integrations workspace package contains adapters designed to connect Stagehand with other frameworks and agentic systems.

Key integration paths include:

1. Code-mode stdio entrypoint: Currently provides the MCP (Model Context Protocol) host and process lifecycle. While it does not yet advertise specific tools, it serves as the foundation for future code-mode capabilities.
2. Deep Agents (Python): The deepagents/ Python project offers both local and managed LangChain Deep Agents integrations. These integrations expose stateful browser tools—specifically run, snapshot, and screenshot—leveraging the Stagehand Python SDK.

Stagehand is a browser automation framework designed to control web browsers using a combination of natural language and code. It is built to bridge the gap between brittle, selector-based automation (like Playwright or Puppeteer) and unpredictable AI agents.

Stagehand provides four core primitives that allow developers to choose the level of autonomy required for a task:

1. Act: Execute specific actions using natural language commands.
2. Extract: Pull structured data from a page using schemas.
3. Observe: Discover available actions or elements on a page.
4. Agent: Automate entire workflows autonomously using an agentic mode.

It is compatible with all Chromium-based browsers (Chrome, Edge, Arc, Brave, etc.) and is optimized for use with Browserbase cloud infrastructure.

The Convex integration allows you to run AI-powered browser automation directly within serverless Convex functions. It wraps the Stagehand REST API to enable Convex actions to control cloud browsers via Browserbase.

Key capabilities include:

• Act: Perform browser actions (clicking, typing, navigating) using natural language instructions.
• Extract: Use Zod schemas to extract structured data from web pages using natural language.
• Observe: Identify and analyze interactive elements on a webpage.
• Agent: Execute autonomous, multi-step tasks that require AI-driven decision-making.

Common use cases include data extraction pipelines (storing web data directly in Convex), automated background workflows, form automation, and complex multi-step web processes.

The Browserbase MCP Server enables AI-powered browser automation by integrating Stagehand with the Model Context Protocol (MCP). It allows MCP clients to control browsers using natural language commands, navigate web pages, extract structured data, and manage browser session lifecycles.

Key Capabilities:

• Natural Language Automation: Use plain English (e.g., "click the login button") instead of complex selectors.
• Web Interaction: Navigate, click, type, scroll, and fill forms.
• Data Extraction: Automatically extract structured information from complex websites.
• Session Management: Explicitly create, reuse, and close browser sessions, including maintaining authentication states and cookies.

Stagehand is designed for production-grade browser automation with the following characteristics:

• Full Playwright Compatibility: You can use any Playwright API alongside Stagehand commands.
• Multi-Language Support: Provides first-class TypeScript and Python SDKs with type safety.
• Browser Compatibility: Works with all Chromium-based browsers including Chrome, Edge, Arc, and Brave.
• Precise Control: Allows mixing deterministic code with AI-powered actions.

WebMCP is a browser API that allows you to discover and invoke capabilities exposed directly by a web page as callable tools. Instead of driving a UI through clicks, you can call a tool with typed input (defined via JSON Schema) to perform complex actions like checkouts in a single call.

Key distinction: WebMCP tools are registered by the page itself. They are not tools you define manually in your model; they are tools the website chose to publish for discovery.

const tools = await page.tools();
const [checkout] = tools;

const invocation = await checkout.invoke({ input: { quantity: 2 } });
const response = await invocation.result();

console.log(response.status, response.output);

The agent() method turns high-level natural language tasks into fully autonomous browser workflows. It can execute complex, multi-step sequences by understanding web interfaces through either DOM manipulation or computer vision. You can customize the agent's behavior by specifying an LLM provider and model, setting a systemPrompt, and configuring maxSteps.

await agent.execute("apply for a job at browserbase")

A BrowserContext is used to coordinate pages and browser state that is shared across them (such as cookies, headers, and domain policies). You can access the current context via browser.context.

Quick Start (TypeScript)

const context = browser.context;
const page = await context.newPage();

Quick Start (Python)

context = browser.context
page = await context.new_page()

Prompt-only Extraction

Call extract with just a natural language string. The output will be wrapped in an object with an extraction key.

TypeScript: const result = await page.extract("extract the name of the repository");
Python: result = await page.extract("extract the name of the repository")
Output Shape: { extraction: string }

Extract with no parameters

Calling extract() with no arguments returns a hierarchical tree representation of the root DOM (the Accessibility Tree). This is not passed through an LLM.

TypeScript: const pageText = await page.extract();
Python: pageText = await page.extract()
Output Shape: { pageText: string }

While Stagehand provides AI-driven interaction, you can use standard page.locator(selector) for deterministic, non-AI interactions.

Note that selectors returned by Stagehand's observe method are XPath strings prefixed with xpath=. You can use these directly with standard Playwright-style locators.

# Using an AI-generated XPath selector
await page.locator("xpath=/html/body/div[2]/button").click()

# Standard CSS selectors
await page.locator("#email").fill("user@example.com")
count = await page.locator("li.result").count()