Every AI agent demo ends at the same wall: the browser. Playwright was built for testing, not for agents — raw DOM dumps are token-hungry, selectors break on every redesign, and iframes plus shadow DOM turn simple scripts into nightmares.
Stagehand, the open-source SDK from Browserbase with more than 24k GitHub stars, fixes exactly that. In this guide I show you what it is, how its architecture works in 4 steps, and how to run your first agent in 5 minutes with commands verified against the real README.
1. What Is Stagehand: Stars, License, and the Big Idea
Stagehand is the SDK for browser agents, maintained by Browserbase. It gives you the Playwright-style API you already know — goto, click, locator, screenshot — plus three natural-language primitives (act, observe, extract) that keep working when websites change. One protocol, three SDKs: TypeScript, Python, and Go.
Repository
github.com/browserbase/stagehand
Stars
~24.1k on GitHub (Sep 2026)
License
MIT — fully open source
npm Package
@browserbasehq/stagehand (v4.0.1)
SDKs
TypeScript, Python, Go
Docs
docs.stagehand.dev
The one-sentence pitch
Playwright was built for testing — Stagehand is built for agents. Deterministic control where you want it, self-healing AI actions where you need them, all running on an engine that lives next to the browser instead of across a slow round-trip.
Why is it trending? Because every serious agent eventually needs to click, read, and fill real websites. Prompting a generic model with raw HTML burns tokens and breaks weekly. Stagehand trims the accessibility tree to exactly what the agent needs, resolves actions through its own CDP engine, and recovers automatically when the page changes underneath you.
2. How It Works: The Architecture in 4 Steps
You do not need to understand every internal to ship with Stagehand, but this 4-step mental model explains why it beats piping HTML into an LLM yourself.
Step 1 — Familiar deterministic API
Playwright-style · CDP engine
goto, click, locator, screenshot — the methods you and your agents already know. Under the hood a CDP engine runs next to the browser, cutting round-trip latency and handling out-of-process iframes and closed shadow DOMs natively.
Step 2 — Three AI primitives
act · observe · extract
act() performs an action from a plain-English instruction, observe() tells you what is actionable on the page, and extract() pulls structured data with a zod schema. Natural language in, reliable selectors and typed data out.
Step 3 — Self-healing, token-efficient context
a11y-tree trimming · auto-recovery
Hybrid accessibility-tree trimming feeds the model exactly what it needs — nothing more. When a site redesigns, Stagehand detects the drift and refreshes how actions resolve instead of throwing a dead-selector error at 3am.
Step 4 — Run anywhere: local or cloud
local Chromium · Browserbase
It works locally out of the box with any Chromium. When you are ready for production, the same code runs on Browserbase cloud browsers with session replay, captcha solving, agent identity, and zero-infrastructure deploy via Functions.
The mental model I use
Deterministic code for the happy path, AI primitives for the messy parts, and the full agent() loop only when the task genuinely needs autonomy. Most production flows I build are 80% locators and 20% act/extract — that ratio is the whole point.
3. Quickstart: From Zero to a Working Agent in 5 Minutes
Two verified paths, both taken straight from the official README and docs. Path A scaffolds a ready-to-run app with the CLI. Path B drops Stagehand into a project you already have. Either way you need an LLM provider key, plus a Browserbase key only if you want cloud browsers.
A — Scaffold a sample project (fastest)
npx create-browser-app cd my-stagehand-app cp .env.example .env # Add your API keys npm start # Run the example script
B — Install in your existing app
npm install @browserbasehq/stagehand
Configure environment (.env)
OPENAI_API_KEY=your_api_key BROWSERBASE_API_KEY=your_api_key
Automate: the act / observe / extract loop (from the README)
import { browserbase, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";
const browser = await browserbase.launch({
apiKey: process.env.BROWSERBASE_API_KEY,
});
const stagehand = await Stagehand.create({
browser,
model: { modelName: "openai/gpt-5.4-mini", apiKey: process.env.OPENAI_API_KEY },
});
const [page] = await browser.context.pages();
await page.goto("https://github.com/browserbase");
await stagehand.act("click on the stagehand repo");
const { data: actions } = await stagehand.observe("find the latest PR");
await page.locator(actions[0].selector).click();
const { data } = await stagehand.extract(
"extract the author and title of the PR",
z.object({ author: z.string(), title: z.string() })
);Tip: dotenv is on you
Stagehand does not auto-load .env files. If you use one, install dotenv and call dotenv.config() in your own code first. And remember: local Chromium needs nothing else — skip the Browserbase key entirely until you want cloud sessions.
4. Real-World Use Cases
Stagehand shines wherever a deterministic script would rot within weeks. These are the five patterns I see working in production, ordered by how often they pay off.
Browser-agent evals
Reliability engineering
Stagehand ships its own evals culture. Score act/observe/extract runs across site changes and catch regressions before your users do — the highest-ROI habit in this whole guide.
Structured web scraping
extract + zod
Pull typed records (prices, listings, PR metadata) with a schema instead of regexing HTML. When the layout shifts, the model adapts while your downstream types stay frozen.
Form filling and QA flows
act + locators
Checkout flows, signup funnels, admin panels. Drive the stable skeleton with locators and let act() absorb the flaky steps — CAPTCHAs and auth walls go to Browserbase cloud.
Research and monitoring agents
agent() + search/fetch
Nightly competitor scans, Hacker News digests, docs watchers. The browserbase facade even exposes Search and Fetch without launching a browser for the cheap parts of the job.
Tool use via MCP
Model Context Protocol
Expose Stagehand through its MCP server so Claude or any MCP client can drive a real browser as a tool. Your agent gets hands, not just words.
5. When NOT to Use Stagehand
Honest section, because every LLM call has a price. Stagehand is the wrong tool surprisingly often — here is how I draw the line after shipping both sides of it.
✅ Reach for Stagehand
- • Flows driven by AI on sites that change layout regularly
- • Structured extraction where selectors rot faster than you can maintain them
- • Teams needing TS, Python, or Go against one protocol, local first
- • Agent evals and cloud fleets with replay, captchas, and identity
❌ Skip it
- • Fully static pages — plain fetch plus a parser is 100x cheaper
- • Frozen internal tools where raw Playwright selectors never break
- • Air-gapped or no-model-key environments (every act() needs an LLM)
- • Ultra-low-latency budgets where one model call per action blows the p99
Golden rule
Deterministic by default, AI where it pays. If a locator survives three months untouched, it never needed a model. If you have edited the same selector twice this quarter, that step belongs to act().
Conclusion
Stagehand earns its 24k stars by respecting a simple truth: agents live in the browser, and the browser is hostile terrain. Familiar APIs keep the easy parts cheap, act/observe/extract absorb the chaos, and the local-first plus cloud path means your prototype and your production fleet are the same codebase.
Clone the repo, run npx create-browser-app, and automate one annoying flow this week — a login, a scrape, a form. Measure the tokens, keep the evals, and you will know within days whether your roadmap needs it.
Stagehand in 30 seconds
Primitives
- • act — do this
- • observe — what can I do
- • extract — typed data
Run it
- • npx create-browser-app
- • npm i @browserbasehq/stagehand
- • local or Browserbase
Remember
- • MIT, 24k+ stars
- • TS · Python · Go
- • deterministic first
