Stagehand: The AI Browser Automation Framework
Control browsers with natural language and code for flexible, maintainable, reliable automation.
Evidence shows: CLI tests explicitly verify that raw argv values (e.g., URLs and tokens) are not sent to telemetry, demonstrating sensitive data protection; dependency overrides (pnpm overrides) show proactive mitigation of known vulnerabilities; but user confirmation mechanisms (e.g., confirmation before act) and rollback functionality are missing. Deductions: user confirmation and rollback absent, data flow transparency only partially shown (e.g., telemetry events), external effects (e.g., browser actions) not explicitly restricted.
Evidence shows: CI workflow includes lint, build, unit tests, e2e tests, and tests cover error handling (e.g., CLI error messages); dependency versions pinned (pnpm-lock.yaml) and overrides ensure availability. Deductions: self-consistency partially shown (e.g., CLI command naming), failure messages verified in tests but not comprehensively covered.
Evidence shows: README describes multiple use cases (act, agent, extract), supports local and Browserbase environments; CLI provides various commands (cloud fetch, search, etc.). Deductions: trigger precision (e.g., act instruction parsing) not detailed, environment fit (e.g., browser versions) relies on external configuration.
Evidence shows: README provides installation and build instructions, LICENSE is MIT, CI workflow reflects maintenance responsibility; but explicit version changelog and known limitations are missing. Deductions: naming stability (e.g., CLI commands) not explicitly guaranteed, version changelog absent.
Evidence shows: Output formats (JSON, table) and file output supported, CLI provides multiple features (fetch, search, projects, etc.), marginal value high; but cost-benefit (e.g., token consumption) not quantified. Deductions: cost-benefit lacks data support.
Evidence shows: README claims (e.g., reliability) are supported by tests, but no specific evidence links provided; test files (e.g., cli-cloud-contract.test.ts) verify API contracts. Deductions: claim traceability insufficient, cross-source corroboration limited, fact-inference separation unclear.
- User confirmation mechanism missing: actions like act may execute directly, use with caution.
- Rollback functionality not provided: no automatic recovery after failed automation.
- Data flow transparency limited: specific use and storage of telemetry data not detailed.
- Dependency security relies on overrides, but no vulnerability scan report provided.
What does this agent do, and when should you use it?
Stagehand is a browser automation framework that combines AI with code, letting developers use natural language for actions while retaining precise control via code. Built on a CDP engine, it offers core APIs like act(), agent(), and extract() for individual actions, multi-step tasks, and structured data extraction. The framework features auto-caching and self-healing, remembering repeated actions to reduce LLM inference and recovering when websites change. Written in TypeScript and managed with pnpm, it integrates into existing Node.js projects. It requires an LLM API key and optionally Browserbase credentials.
Stagehand interacts with the browser via its CDP engine, providing act() to execute a single natural language instruction (e.g., 'click on the stagehand repo'), agent() for multi-step tasks (e.g., 'Get to the latest PR'), and extract() to pull structured data (e.g., PR author and title) with Zod schemas. It automatically caches actions to avoid LLM calls and self-heals when page changes break automation. Setup can be done via npx create-browser-app or by cloning and building with pnpm.
- Frontend developers needing to automate tests for dynamic web apps without writing brittle selectors.
- Data engineers extracting structured data from sites with frequently changing HTML.
- DevOps engineers monitoring web dashboards and performing routine clicks via natural language.
- QA engineers replacing fragile selectors with natural language to stabilize test suites.
- Product managers prototyping automation workflows quickly without deep coding knowledge.
What are this agent's strengths and limitations?
- Blends natural language with code, allowing flexibility on unfamiliar pages and precision when needed.
- Auto-caching remembers repeated actions, saving tokens and reducing latency.
- Offers clear APIs (act, agent, extract) covering a wide range of automation needs.
- Built on CDP and Playwright, providing a stable and debuggable foundation.
- Requires LLM API keys, incurring per-use costs.
- Depends on Browserbase for remote browser management, adding a third-party service.
- As a relatively new framework, its ecosystem and docs are less mature than Selenium or Playwright.
- Primarily TypeScript/Node.js, which may be a barrier for developers in other languages.
How do you install or deploy this agent?
Requires Node.js and pnpm. Clone the repo: git clone https://github.com/browserbase/stagehand.git, cd in, run pnpm install and pnpm run build. Alternatively, use npx create-browser-app to scaffold a new project. You'll need an LLM API key (e.g., OpenAI) and Browserbase credentials–copy .env.example to .env and fill in values.
How do you use this agent?
After install, run pnpm run example to try the sample. In code, use stagehand.act("click on the stagehand repo") for single actions, stagehand.agent().execute("Get to the latest PR") for multi-step, and stagehand.extract(...) with a Zod schema to get data. Ensure env vars are set for LLM and Browserbase.
How does this agent compare with similar options?
Compared to traditional automation tools like Selenium or Playwright, Stagehand lets you replace some low-level code with natural language, reducing maintenance overhead.
FAQ
Does Stagehand support Python?
What credentials do I need?
How does Stagehand handle website changes?
Can I install Stagehand into an existing project?
pnpm add "github:browserbase/stagehand#<branch>&path:/packages/core".