📦 官方信息

项目	地址
官网	https://stagehand.dev
文档	https://docs.stagehand.dev
GitHub	https://github.com/browserbase/stagehand
Discord	https://stagehand.dev/discord
Python 版	https://github.com/browserbase/stagehand-python

开发方： Browserbase（企业级浏览器基础设施公司）

🎯 什么是 Stagehand？

Stagehand 是一个 AI 浏览器自动化框架，用自然语言和代码来控制网页浏览器。

"The AI Browser Automation Framework"

核心理念： 结合 AI 的能力和代码的精确性，让网页自动化变得灵活、可维护、真正可靠。

🤔 解决什么问题？

传统自动化面临两个极端：

方案	问题
Selenium/Playwright	太脆弱——网站 UI 一变，脚本就挂
AI Agent	太不可控——行为不可预测，难以调试

Stagehand 的答案： 让你在「代码」和「自然语言」之间自由选择，需要 AI 时用 AI，需要精确时用代码。

🛠️ 四大核心原语

原语	作用	示例
act()	执行单个自然语言动作	await stagehand.act("click the login button")
extract()	提取结构化数据	await stagehand.extract("extract price", z.number())
observe()	发现页面可用动作	await stagehand.observe("find submit buttons")
agent()	完全自主执行多步骤工作流	await agent.execute("apply for this job")

🚀 快速开始

一行命令启动

npx create-browser-app

代码示例

import { stagehand } from '@browserbasehq/stagehand';

const page = stagehand.context.pages()[0];
await page.goto("https://github.com/browserbase");

// 用自然语言执行单个动作
await stagehand.act("click on the stagehand repo");

// 用 Agent 执行多步骤任务
const agent = stagehand.agent();
await agent.execute("Get to the latest PR");

// 提取结构化数据
const { author, title } = await stagehand.extract(
  "extract the author and title of the PR",
  z.object({
    author: z.string().describe("PR 作者用户名"),
    title: z.string().describe("PR 标题"),
  }),
);

💡 Agent 三种模式

模式	说明	适用场景
CUA	计算机视觉驱动，基于屏幕坐标操作	通用网页操作，支持 Computer Use 模型
DOM	基于 DOM 树操作	需要精确 DOM 结构的场景
Hybrid	混合模式，视觉 + DOM	需要两者的复杂场景

支持的 CUA 模型

• google/gemini-2.5-computer-use-preview

• openai/computer-use-preview

• anthropic/claude-sonnet-4

✨ 核心特性

🎯 精确控制

• 在同一次自动化中混合使用 AI 动作和确定性代码

• 完全控制 AI 的使用程度

🔄 自愈能力（Self-Healing）

• 自动缓存动作，网站变化时自动适应

• 无需 LLM 推理即可重复运行

💰 节省成本

• 缓存机制避免重复的 LLM 调用

• Token 消耗大幅降低

🌐 广泛兼容

• 支持所有 Chromium 内核浏览器：Chrome、Edge、Arc、Brave 等

• 自动处理 iFrame 和 Shadow DOM

📊 对比传统方案

--	Playwright/Selenium	AI Agent	**Stagehand**
定位方式	CSS/XPath 选择器	完全自主	任意选择
维护成本	高（UI 变则挂）	难预测	低（自愈 + 缓存）
可控性	高（代码精确控制）	低	高（可选择）
调试难度	中	高	低（可预览动作）
学习成本	中	低	低（自然语言）

🐍 Python 版本

Stagehand 还有 Python 实现：

pip install stagehand

文档：

https://github.com/browserbase/stagehand-python

🎨 配合 Director 使用

Stagehand 支持与 Director（AI 代码生成工具）集成，可以直接用自然语言生成 Stagehand 脚本：

# 用 Director 生成 Stagehand 脚本

npx create-browser-app --template director

总结： Stagehand 是一个介于「传统自动化」和「AI Agent」之间的中间地带——你既有代码的精确控制力，又有 AI 的灵活性，特别适合需要可靠、可维护、可调试的生产级网页自动化场景。