Stagehand

Stagehand is an SDK for controlling web browsers with AI agents. It's built by Browserbase for developers who already use Playwright, Puppeteer, or Selenium but need automation that survives site changes and works well with LLMs. If you're writing agents that need to click, extract, and observe web pages without brittle selectors breaking every time a site updates its DOM, Stagehand targets that problem directly.

Instead of replacing Playwright, Stagehand layers agent-friendly primitives on top of it. You get the same goto, click, locator, and screenshot calls you already know, plus natural-language methods (act, observe, extract) that let an LLM decide what to do on a page and then execute it deterministically. When a page's structure changes, Stagehand detects the drift and re-resolves the action instead of failing outright.

Key features

• Familiar APIs: Playwright-style methods (goto, click, locator, screenshot) work as expected, so existing automation knowledge transfers directly.
• Self-healing actions: act, observe, and extract use natural language to find and execute actions, then adapt automatically when the underlying page markup changes.
• Token efficiency: a hybrid accessibility tree trimming approach feeds agents only the page context they need, cutting LLM token usage.
• Lower latency: Stagehand runs as an extension next to the browser, reducing round-trip time for page actions compared to remote-driver approaches.
• Complex DOM support: native handling of out-of-process iframes, closed Shadow DOMs, and deep nested locators.
• Multi-language support: a complete browser driver available in TypeScript, Python, and Go from a single monorepo.
• Production features: WebMCP, clipboard support, batch commands, and OpenTelemetry (OTel) support for observability.

Ideal use cases

Stagehand fits teams building browser-based AI agents that need to complete multi-step tasks on real websites: filling forms, extracting structured data, navigating unfamiliar UIs, or running workflows that break when a site's layout shifts. It's a good fit if you're already comfortable with Playwright semantics and want to add LLM-driven fallback behavior without rewriting your automation stack.

It also works for scraping and data-extraction pipelines where you want structured output (via extract with a schema) rather than raw HTML parsing, and for teams running automation in production who need observability (via OTel) and deterministic control (via Playwright-style locators) alongside AI flexibility.

It's not the right tool if you need pure, deterministic UI testing with no AI involvement, since plain Playwright or Selenium will be simpler and cheaper to run at scale. It also assumes access to an LLM provider (like OpenAI) and, for full functionality, a Browserbase account; teams unwilling to manage API keys or pay for model calls may find plain browser-automation frameworks more straightforward.

Installation

Stagehand is distributed as packages for TypeScript, Python, and Go, and the repo is a monorepo you can also build from source.

To build and run from source, you need just to coordinate pnpm, uv, and go:

git clone https://github.com/browserbase/stagehand.git
cd stagehand
just install
just generate
just build

Stagehand works best with an LLM provider API key and Browserbase credentials exported as environment variables:

export OPENAI_API_KEY="your-openai-api-key"
export BROWSERBASE_API_KEY="your-browserbase-api-key"

Run any of the included TypeScript examples with:

just example act # runs packages/sdk-ts/examples/act.ts

For the equivalent Python and Go setup, check the READMEs in packages/sdk-python and packages/sdk-go. Full setup details for all three languages are in the project's CONTRIBUTING.md, and the Quickstart Guide covers installing the published packages directly rather than building from source.