Stagehand is an AI-powered browser automation framework that enables developers to control web browsers using a combination of natural language and code. Built and maintained by Browserbase, it bridges the gap between brittle low-level automation tools (Selenium, Playwright, Puppeteer) and unpredictable pure AI agents by allowing developers to choose when to use AI versus deterministic code.
Sources: README.md46-52 packages/core/README.md46-52
Stagehand is a TypeScript/JavaScript monorepo providing browser automation capabilities through natural language and code. The core package @browserbasehq/stagehand (packages/core/package.json2-4) exposes the framework's primary orchestration layer with four primary primitives:
| Primitive | Method Signature | Purpose |
|---|---|---|
| act | stagehand.act(instruction) | Execute single browser actions via natural language README.md77-78 |
| extract | stagehand.extract(instruction, schema) | Extract structured data with Zod schema validation README.md84-91 |
| observe | stagehand.observe(instruction) | Discover interactive elements and available actions README.md77-78 |
| agent | stagehand.agent().execute(instruction) | Execute multi-step autonomous workflows README.md80-82 |
The framework's core innovation is intelligent caching and self-healing (README.md58-59). These systems convert AI-driven workflows into deterministic scripts that execute significantly faster (20-40% speed increase in V3) by skipping LLM inference while maintaining the ability to involve AI when page structures change CHANGELOG.md8-10
Sources: README.md46-92 packages/core/README.md46-92 CHANGELOG.md8-10
The repository is structured as a monorepo managed by turbo (package.json8 package.json59) containing the SDK, server components, and evaluation suites.
Diagram: Stagehand Monorepo Overview
| Package Directory | npm Package | Primary Purpose |
|---|---|---|
| packages/core | @browserbasehq/stagehand | Main AI web browsing framework packages/core/package.json2-4 |
| packages/evals | @browserbasehq/stagehand-evals | Evaluation suite for Stagehand packages/evals/package.json2-5 |
| packages/server-v3 | @browserbasehq/stagehand-server-v3 | Stagehand API server v3 packages/server-v3/package.json2-4 |
| packages/cli | N/A | CLI tool for local browser automation and debugging package.json11 |
For details, see Monorepo Structure and Packages.
Sources: package.json1-62 pnpm-lock.yaml83-170 CHANGELOG.md28-34
| Feature | Description |
|---|---|
| Hybrid Control | Mix natural language act() with deterministic code README.md54 |
| Auto-Caching | Save actions to local storage to run faster without LLM tokens CHANGELOG.md10 |
| Self-Healing | Automatically detects website changes and reinvokes AI to fix the automation README.md58-59 |
| Multi-Provider | Support for OpenAI, Anthropic, Google, and others via AI SDK packages/core/package.json87-118 |
| Deep Locators | Traversal across iframes and shadow roots (open & closed mode) CHANGELOG.md15-19 |
| MCP Integration | Support for Model Context Protocol servers and custom tools CHANGELOG.md28 packages/core/package.json91 |
| Computer Use | Visual understanding and coordinate-based actions for complex UIs CHANGELOG.md24-25 |
| Evaluation Tiering | Two-tier framework for deterministic tool tests and LLM benchmarks packages/evals/package.json2-5 |
Sources: README.md46-59 CHANGELOG.md3-20 packages/core/package.json87-118 CHANGELOG.md28-40
Sources: README.md72-91 packages/core/README.md72-91
Stagehand operates as an orchestration layer that bridges high-level AI instructions with low-level browser protocols.
Diagram: Stagehand System Flow
The SDK can be configured to run in different environments:
playwright-core, puppeteer-core, or patchright-core packages/core/package.json69-73@browserbasehq/sdk packages/core/package.json89Sources: README.md109-110 CHANGELOG.md9-15 packages/core/package.json69-101
To get started with Stagehand, you can use the official scaffolding tool:
For manual installation and configuration of environment variables like OPENAI_API_KEY or BROWSERBASE_API_KEY, see Installation and Quick Start.
Sources: README.md60-66
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.
