stagehand README

The project's README from github.com/browserbase/stagehand. As one markdown file: README.md.

Stagehand is the SDK for browser agents.
Read the Docs

MIT License Discord Community

browserbase%2Fstagehand | Trendshift

Ask DeepWiki

What is Stagehand?

Stagehand is the SDK for browser agents. Playwright was built for testing, Stagehand is built for agents. Use familiar APIs, self-healing actions, and network-level security across TypeScript, Python, and Go.

Why Stagehand?

Stagehand gives browser agents an interface built for how they actually work. It combines familiar Playwright-style APIs with self-healing actions, agent-optimized page context, and native support for complex DOM structures like out-of-process iframes and closed Shadow DOMs.

Agents use fewer tokens, recover when websites change, and complete tasks more reliably. With a complete browser driver across TypeScript, Python, and Go, Stagehand delivers the flexibility of AI without sacrificing the speed, control, determinism, reliability, and observability required in production.

1. Familiar APIs

The Playwright-style methods you and your agents already know and love (goto, click, locator, screenshot).

2. Token efficiency as a priority

Stagehand's hybrid accessibility tree trimming gives your agents exactly what they need to understand the page and nothing more.

3. Faster in production

Stagehand runs as an extension next to the browser, closing the distance and reducing round-trip latency for all actions on the page.

4. Self-healing primitives

Use act, observe, and extract with natural language to automate pages. When sites change, Stagehand detects it and refreshes how the actions happen on the page automatically.

5. Features agents need

WebMCP, clipboard support, self-healing actions, batch commands, deep locators for nested iframes, and OTel support.

Getting Started

Check out our Quickstart Guide for more information:

Example

Here's how to build a sample browser automation with Stagehand:

import { browserbase, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

const { BROWSERBASE_API_KEY, OPENAI_API_KEY } = process.env;

const browser = await browserbase.launch({
  apiKey: BROWSERBASE_API_KEY,
});

const stagehand = await Stagehand.create({
  browser,
  model: {
    modelName: "openai/gpt-5.4-mini",
    apiKey: OPENAI_API_KEY,
  },
});

// Stagehand's CDP engine provides an optimized, low level interface to the browser built for automation
const [page] = await browser.context.pages();
await page.goto("https://github.com/browserbase");

// Use act() to execute individual actions
await stagehand.act("click on the stagehand repo");

// Use observe() to see what's actionable on the page
const { data: actions } = await stagehand.observe("find the latest PR");

// Use locators for deterministic Playwright-style actions
await page.locator(actions[0].selector).click();

// Use extract() to get structured data from the page
const {
  data: { author, title },
} = await stagehand.extract(
  "extract the author and title of the PR",
  z.object({
    author: z.string().describe("The username of the PR author"),
    title: z.string().describe("The title of the PR"),
  }),
);

See the Python and Go READMEs for equivalent examples.

The same browserbase facade also exposes Browserbase Search and Fetch without launching a browser:

const results = await browserbase.search({
  apiKey: BROWSERBASE_API_KEY,
  query: "browser agent frameworks",
  numResults: 5,
});
const fetchResult = await browserbase.fetch({
  apiKey: BROWSERBASE_API_KEY,
  url: results.results[0].url,
  format: "markdown",
});

Documentation

Visit docs.stagehand.dev to view the full documentation.

Build and Run from Source

Stagehand is a TypeScript, Python, and Go monorepo. We use just to drive pnpm, uv, and go together.

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

Stagehand is best when you have an API key for an LLM provider and Browserbase credentials. Export them so they're available on process.env:

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

Then run any of the scripts in packages/sdk-ts/examples:

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

See CONTRIBUTING.md for the full TypeScript, Python, and Go setup.

Contributing

[!NOTE] We highly value contributions to Stagehand! For questions or support, please join our Discord community.

We're focused on improving reliability, extensibility, speed, and cost in that order of priority. If you're interested in contributing, bug fixes and small improvements are the best way to get started. For more involved features, we strongly recommend reaching out to Miguel Gonzalez or Paul Klein in our Discord community before starting to ensure that your contribution aligns with our goals.

Acknowledgements

We'd like to thank the following people for their major contributions to Stagehand:

License

Licensed under the MIT License.

Copyright 2026 Browserbase, Inc.

"Stagehand" is a trademark of Browserbase, Inc.

stagehand (browserbase/stagehand)

Searching Database…

25.7K ·GitHub
Stagehand
这是什么?Stagehand 是一个用于构建浏览器代理的 SDK——也就是驱动真实浏览器去提取数据并与任意网站交互的代码代理或 AI 代理,提供 TypeScript、Python 和 Go 的 SDK。
它和直接用 Playwright 有什么不同?Playwright 是为测试而生的;Stagehand 是为代理而生的。你仍可以使用 Playwright 风格的方法(goto、click、locator、screenshot),同时还能加入自然语言的 act、observe 和 extract 操作、专为代理优化的页面上下文,以及对跨进程 iframe 和封闭 Shadow DOM 的支持。
TypeScript 项目的搭建流程是什么样的?按照 docs.stagehand.dev 上的快速入门指南,安装你所用语言的 SDK(TypeScript 侧需要 Node >= 22.18.0)。导出 LLM 提供商的 API 密钥和 Browserbase 凭据,然后运行 packages/sdktz/examples 里的示例脚本。
网站改版之后,我的自动化会怎样?Stagehand 会检测到变化并自动刷新操作的执行方式,让你的代理自行恢复,而不是悄悄失效。
它是给做网站测试的 QA 工程师用的,还是给构建代理的开发者用的?给构建浏览器代理和生产级网页自动化的开发者用的——Stagehand 把自己定位为 Playwright 测试定位的代理版对应物,把可靠性、可观测性和成本当作生产环境的问题来对待。
Stagehand 到底运行在哪里?它是一个代码 SDK,而不是需要安装的应用:TypeScript SDK 运行在 Node.js 22.18.0 及以上版本,另外还有 Python 和 Go 的 SDK,分别运行在它们各自的常规运行时上。
Stagehand 免费开源吗?是的——它采用 MIT 许可证,由 Browserbase, Inc. 开发。
我的代理会不会为了读取整页内容而浪费 token?token 效率是其明确承诺的优先事项:Stagehand 的混合无障碍树裁剪只给代理恰好需要的页面上下文——不多一分。
每个任务都需要完整的浏览器会话吗?不需要——同一个 browserbase 接口还提供了无需启动浏览器的 Browserbase Search 和 Fetch,简单的查询完全可以跳过页面自动化。
我可以把 Claude Code 或 Codex 这类编程代理接到它上面吗?可以——项目说明中把 Claude Code、Codex、Eve 和 Mastra 列为受支持的上手方式。
它自带哪些生产环境功能?WebMCP 支持、剪贴板支持、批量命令、用于嵌套 iframe 的深度定位器,以及 OpenTelemetry(OTel)支持。团队表示他们的优先级依次是可靠性、可扩展性、速度和成本。
What are similar projects?browser-use, browser-harness, scout, nanobrowser, invisible_playwright_mcp, moli, maxun, webcmd
Which topics is it in?cloud-browser, browser-agent, headless-chrome, web-automation, cdp, data-extraction, dom, agentic, playwright, web-scraping, browser-automation, sdk
Creator
browserbase
Size
198.9 MB
Stars
25.7K
Updated
CommitOct 15Release@browserbasehq/[email protected]Aug 28
Age
2y
Commits · 90 Days