Stagehand v3
Natural language-based browser automation — act, extract, observe, and agent: the four core primitives.
- Four core primitives —
act(),extract(),observe(),agent():act()executes a single browser action based on natural language instructions ("click the login button"),extract()extracts structured data from a page based on a Zod schema,observe()proactively explores a list of possible actions on the current page, andagent()autonomously executes a multi-step workflow. These four are combined to integrate deterministic step control and autonomous agent execution into a single SDK. - v3 architecture rewrite — removal of internal Playwright dependencies: In v3, internal Playwright dependencies are completely removed, and the architecture is switched to directly communicate with the CDP (Chrome DevTools Protocol) engine. Playwright, Puppeteer, or Patchright can be selected and used as the backend. A 20-40% speed improvement is achieved across
act(),extract(), andobserve(). - Three agent modes — CUA, DOM, Hybrid: CUA (Computer Use Agent) mode directly recognizes the screen through vision-based coordinate clicks, DOM mode executes semantic actions through accessibility tree analysis, and Hybrid mode (default from v3.4.0) combines vision and DOM to achieve both accuracy and speed. Incompatible models are automatically routed to DOM mode.
- Multi-LLM provider support: Based on the Vercel AI SDK, major providers such as OpenAI, Anthropic (Claude), and Google Gemini can be freely switched. The Computer Use API supports Anthropic, OpenAI, Google, and Microsoft. When using Browserbase, all supported models can be accessed with a single API key through the Model Gateway.
- Self-healing automation: Because natural language-based instructions are interpreted by AI at runtime, the script automatically adapts even if the website markup changes. This fundamentally eliminates maintenance costs compared to hardcoding CSS selectors. In v3, automatic traversal of Shadow DOM (both open and closed modes) and iFrames is added.
- Action caching system: A dual structure consisting of a Browserbase server-side cache (cache key based on instruction + page content, response time of less than 100ms on HIT) and a local file cache (
cacheDirsetting). The automatic action caching in v3 can automatically convert CUA execution into a deterministic script without inference. - v3 new non-AI primitives:
page,locator,frameLocator,deepLocator(cross-navigation of iFrame + Shadow Root) — used when direct DOM control is needed without AI inference. The precision of traditional automation tools and the flexibility of AI can be selectively used within a single SDK. - Custom tools and MCP integration: User-defined tools can be injected into
agent()to perform actions outside the browser, such as sending emails or calling external APIs. The URL of the MCP (Model Context Protocol) server is passed as an array in the integrations, allowing immediate connection to the external tool ecosystem. - Framework integration: Directly integrated with major automation and web frameworks such as CrewAI, LangChain JS, Playwright, Puppeteer, Selenium, Next.js/Vercel, and Convex. Bun runtime is also officially supported from v3.
💻 System Requirements
Not required (all LLM inference is delegated to an external API provider)
A few tens of MB based on npm packages. Additional space may be required depending on the accumulation of cached files when local caching is enabled (within a few hundred MB).
⚡ Installation
4-1. Quick Start
# TypeScript — Project scaffolding (recommended)
npx create-browser-app
# TypeScript — Add to an existing project
npm install @browserbasehq/stagehand
# Python
pip install stagehand
# Or, when using uv
uv pip install stagehand
4-2. Basic Usage Example (TypeScript)
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";
const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://github.com/browserbase");
// Execute a single action
await stagehand.act("click on the stagehand repo");
// Extract structured data (Zod schema)
const { author, title } = await stagehand.extract(
"extract the author and title of the PR",
z.object({
author: z.string().describe("The username of the PR author"),
title: z.string().describe("The title of the PR"),
}),
);
// Multi-step autonomous agent
const agent = stagehand.agent({
provider: "anthropic",
model: "claude-sonnet-4-6",
});
await agent.execute("Get to the latest PR");
4-3. Environment Variable Configuration
# .env file
BROWSERBASE_API_KEY=your_api_key # When using Browserbase Cloud
OPENAI_API_KEY=your_key # When using OpenAI models
ANTHROPIC_API_KEY=your_key # When using Anthropic models
GOOGLE_API_KEY=your_key # When using Gemini models
🧬 Bio Use Cases
Production Web Scraping Pipeline
Build an automated pipeline for regularly collecting structured data from websites that do not offer an API. Use observe() to pre-explore the page structure, and pass a Zod schema to extract() to extract data such as prices, inventory, and reviews into a JSON structure. With self-healing capabilities, the script can continue to operate without modification even if the target site's UI changes. When a cache hit occurs, the response time is less than 100ms, reducing token costs by up to 90% when processing a large number of pages.
Advanced E2E Test Automation
Solve the problem of existing Playwright/Selenium tests breaking with every selector change. Describe key user flows, such as "Login -> Search for products -> Add to cart -> Checkout," in natural language, and the AI will identify and execute the elements at runtime. In Hybrid mode (default in v3.4.0), run fast, deterministic DOM-based tests, and automatically fall back to DOM mode when using incompatible models to ensure stability.
Browser-Based RPA Agent
Build an RPA agent that integrates browser automation and business logic by injecting custom tools into the agent() primitive. For example, a workflow that logs in to a specific portal every day, downloads a report, extracts the data, and sends it via email can be autonomously executed with a single call to agent(). With MCP integration, subsequent actions such as Slack notifications and database storage can also be handled directly within the agent.
FAQ
What is Stagehand v3?
Four core primitives — act(), extract(), observe(), agent(): act() executes a single browser action based on natural language instructions ("click the login button"), extract() extracts structured data from a page based on a Zod schema, observe() proactively explores a list of possible actions on the current page, and agent() autonomously executes a multi-step workflow. These four are combined to integrate deterministic step control and autonomous agent execution into a single SDK. v3 architecture rewrite — removal of internal Playwright dependencies: In v3, internal Playwright dependencies are completely removed, and the architecture is switched to directly communicate with the CDP (Chrome DevTools Protocol) engine. Playwright, Puppeteer, or Patchright can be selected and used as the backend. A 20-40% speed improvement is achieved across act(), extract(), and observe(). Three agent modes — CUA, DOM, Hybrid: CUA (Computer Use Agent) mode directly recognizes the screen through vision-based coordinate clicks, DOM mode executes semantic actions through accessibility tree analysis, and Hybrid mode (default from v3.4.0) combines vision and DOM to achieve both accuracy and speed. Incompatible models are automatically routed to DOM mode. Multi-LLM provider support: Based on the Vercel AI SDK, major providers such as OpenAI, Anthropic (Claude), and Google Gemini can be freely switched. The Computer Use API supports Anthropic, OpenAI, Google, and Microsoft. When using Browserbase, all supported models can be accessed with a single API key through the Model Gateway. Self-healing automation: Because natural language-based instructions are interpreted by AI at runtime, the script automatically adapts even if the website markup changes. This fundamentally eliminates maintenance costs compared to hardcoding CSS selectors. In v3, automatic traversal of Shadow DOM (both open and closed modes) and iFrames is added. Action caching system: A dual structure consisting of a Browserbase server-side cache (cache key based on instruction + page content, response time of less than 100ms on HIT) and a local file cache (cacheDir setting). The automatic action caching in v3 can automatically convert CUA execution into a deterministic script without inference. v3 new non-AI primitives: page, locator, frameLocator, deepLocator (cross-navigation of iFrame + Shadow Root) — used when direct DOM control is needed without AI inference. The precision of traditional automation tools and the flexibility of AI can be selectively used within a single SDK. Custom tools and MCP integration: User-defined tools can be injected into agent() to perform actions outside the browser, such as sending emails or calling external APIs. The URL of the MCP (Model Context Protocol) server is passed as an array in the integrations, allowing immediate connection to the external tool ecosystem. Framework integration: Directly integrated with major automation and web frameworks such as CrewAI, LangChain JS, Playwright, Puppeteer, Selenium, Next.js/Vercel, and Convex. Bun runtime is also officially supported from v3.
When should I use Stagehand v3?
Natural language-based browser automation — act, extract, observe, and agent: the four core primitives.
What is a biomedical use case for Stagehand v3?
Production Web Scraping Pipeline: Build an automated pipeline for regularly collecting structured data from websites that do not offer an API. Use observe() to pre-explore the page structure, and pass a Zod schema to extract() to extract data such as prices, inventory, and reviews into a JSON structure. With self-healing capabilities, the script can continue to operate without modification even if the target site's UI changes. When a cache hit occurs, the response time is less than 100ms, reducing token costs by up to 90% when processing a large number of pages.
📝 Update Notes
No update notes yet.
🧪 Related Code of Life
No related Code of Life posts yet.