Stagehand Documentation — The SDK for Browser Agents
by Browserbase
Make an LLM drive a real browser without selectors that break — and keep deterministic control where the page is stable.
Overview
Stagehand is Browserbase's open-source SDK for browser agents, and its documentation doubles as the best current tutorial on getting an LLM to drive a real browser reliably. The docs open with a quickstart, installation, and an 'AI Rules' page that feeds coding assistants the correct v4 idioms, then teach four core primitives: act, which executes a natural-language action such as clicking a button; extract, which pulls structured data from a page against a schema you define; observe, which enumerates the actions actually available on a page so an agent can plan before committing; and WebMCP, which lists and invokes tools a page registers itself. Configuration covers running locally against any Chromium install or on Browserbase's hosted browsers, plugging in any LLM provider, logging and observability. The section that separates this from a README is Best Practices: prompting for reliable automation, real-world observe patterns, caching resolved actions to cut token spend, managing multiple tabs, persisting user data across sessions, speed and cost optimization, cloud deployment, and calling Model Context Protocol servers from inside an automation. An API reference documents Stagehand, Context, Page, Locator, Clipboard, WebMCP and Response, and a v3-to-v4 migration guide records the current breaking changes. The library is MIT-licensed with 23.8k GitHub stars and first-class TypeScript, Python and Go support.
At a Glance
- Topic
- Agentic
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~2-3 hours to work through the quickstart, the four primitives and the best-practices section; a reference thereafter
- Provider
- Browserbase
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Drive a browser using the act, extract and observe natural-language primitives
- ✓Pull structured data from arbitrary pages against a schema you define
- ✓Use observe to plan an action before executing it instead of clicking blind
- ✓Cache resolved actions so a repeat run costs tokens once rather than every time
- ✓Mix deterministic Playwright-style locators with AI primitives in the same script
- ✓Call MCP servers and page-registered WebMCP tools from inside an automation
- ✓Deploy browser agents to the cloud and manage sessions, tabs and persisted user data
Highlights
- •Four primitives instead of a black-box agent, so you keep deterministic control wherever the page is stable
- •First-class TypeScript, Python and Go SDKs — unusual for an AI browser library, most ship TypeScript only
- •The Show HN debut drew 326 points and 86 comments in January 2025, and the v4 SDK was posted to Hacker News again in August 2026
- •23.8k GitHub stars under an MIT licence, with a documented v3-to-v4 migration path rather than a silent rewrite
- •Runs locally against any Chromium browser — Browserbase's hosted browsers are an optional production step, not a lock-in
Who It’s For
Best For
- ✓Engineers building agents that must operate websites with no API
- ✓Teams whose Playwright or Puppeteer scrapers break on every DOM change
- ✓AI engineers adding web browsing as a tool to an existing agent
- ✓Automation and QA engineers moving from selector-based scripts to intent-based ones
Prerequisites
- •Working TypeScript, Python or Go, plus basic async programming
- •An API key for an LLM provider — the primitives call a model at runtime
- •Familiarity with Playwright or Puppeteer concepts helps but is not required
FAQ
What is Stagehand Documentation — The SDK for Browser Agents?
Official documentation for Stagehand, the open-source SDK Browserbase builds for browser agents. It is written for engineers who have hit the wall where Playwright selectors break on every site redesign, but who find a fully autonomous browser agent too unpredictable to put in production. You finish able to write automations that mix deterministic Playwright-style calls with natural-language primitives, cache them to control cost, and deploy them.
Is Stagehand Documentation — The SDK for Browser Agents free?
Stagehand Documentation — The SDK for Browser Agents is free to access.
What level is Stagehand Documentation — The SDK for Browser Agents for?
Stagehand Documentation — The SDK for Browser Agents is aimed at a intermediate audience. Recommended background: Working TypeScript, Python or Go, plus basic async programming, An API key for an LLM provider — the primitives call a model at runtime, Familiarity with Playwright or Puppeteer concepts helps but is not required.
How long does Stagehand Documentation — The SDK for Browser Agents take?
Expect roughly ~2-3 hours to work through the quickstart, the four primitives and the best-practices section; a reference thereafter. Most learners work through it at their own pace.
What will I learn from Stagehand Documentation — The SDK for Browser Agents?
You'll learn: Drive a browser using the act, extract and observe natural-language primitives; Pull structured data from arbitrary pages against a schema you define; Use observe to plan an action before executing it instead of clicking blind; Cache resolved actions so a repeat run costs tokens once rather than every time; Mix deterministic Playwright-style locators with AI primitives in the same script; Call MCP servers and page-registered WebMCP tools from inside an automation; Deploy browser agents to the cloud and manage sessions, tabs and persisted user data.
Topics
Sources
This page was written from 2 sources, 1 on domains other than docs.stagehand.dev.