Stagehand：Browserbase 推出的智能浏览器自动化工具，让 AI 直接操作浏览器

1. Stagehand 是什么

Stagehand 是一个由 Browserbase 开发的 AI 浏览器自动化框架，它的核心思想是将传统的代码驱动浏览器自动化（如 Playwright）与 AI 代理的自然语言理解能力相结合，创造出更灵活、更可靠的自动化解决方案。

核心定位：

• 为开发者提供一种混合模式的浏览器自动化工具

• 既保留代码操作的确定性和可靠性

• 又引入 AI 的灵活性和适应性

解决的问题： 传统浏览器自动化工具（如 Selenium、Playwright）需要编写大量低级别代码来处理各种页面交互，而纯 AI 代理虽然灵活但在生产环境中可能不够稳定。Stagehand 正是为了解决这一矛盾而设计的。

2. 功能特色

2.1 混合操作模式

Stagehand 最大的特色是支持混合操作模式，允许开发者根据任务性质灵活选择最佳实现方式：

2.2 智能数据提取

Stagehand 提供了强大的数据提取功能，结合自然语言指令和结构化验证：

const { author, title } = await page.extract({
 instruction: "提取PR的作者和标题",
 schema: z.object({
  author: z.string(),
  title: z.string(),
 }),
});

这一功能大大简化了从复杂网页中提取结构化数据的过程，无需编写繁琐的选择器代码。

2.3 多 AI 提供商支持

Stagehand 支持多种 AI 提供商，包括：

• OpenAI（特别是计算机使用模型）

• Anthropic

• 其他符合 OpenAI API 格式的提供商

这种灵活性使开发者可以根据项目需求和成本考量选择最合适的 AI 模型。

2.4 操作预览与缓存

为了提高开发效率和降低成本，Stagehand 提供了：

• 操作预览：在实际执行前可以预览 AI 计划执行的操作

• 结果缓存：对重复的操作进行缓存，避免重复执行和不必要的 API 调用

2.5 与 Playwright 的无缝集成

Stagehand 构建在 Playwright 之上，保留了其所有强大功能，同时添加了 AI 增强能力。开发者可以随时在 Stagehand 环境中使用原生 Playwright API。

3. 技术细节

3.1 技术栈

3.2 架构设计

Stagehand 的核心架构包括：

1. StagehandContext：管理浏览器实例、页面和 AI 代理

2. StagehandPage：扩展 Playwright Page 对象，添加 AI 功能

3. Agent 系统：处理复杂的 AI 驱动任务

4. LLM 客户端：与不同 AI 提供商交互的统一接口

5. 工具系统：提供 AI 可以使用的各种工具（如页面操作、数据提取等）

3.3 工作原理

当使用 AI 功能时，Stagehand 的工作流程如下：

1. 收集当前页面信息（DOM、截图等）

2. 将任务指令和页面信息发送给 AI 模型

3. AI 模型分析任务并生成一系列操作

4. Stagehand 执行这些操作并返回结果

5. 对于复杂任务，可能会进行多轮交互

4. 应用场景

4.1 网页数据提取

• 从电商网站提取产品信息

• 从新闻网站抓取文章内容

• 从社交媒体收集用户数据

4.2 自动化测试

• 生成基于自然语言的测试用例

• 处理动态变化的 UI 元素

• 辅助进行端到端测试

4.3 流程自动化

• 自动完成重复性工作流程

• 处理需要跨多个网站的任务

• 实现轻量级的 RPA（机器人流程自动化）

4.4 智能助手

• 构建能够浏览网页获取信息的 AI 助手

• 实现需要实时网络数据的问答系统

• 开发能够与网站交互的聊天机器人

4.5 搜索引擎增强

• 创建能够深入网站内容的智能搜索工具

• 实现需要多步骤信息聚合的搜索任务

5. 使用方法

5.1 安装

# 使用 npm
npm install @browserbase/stagehand

# 或使用 yarn
yarn add @browserbase/stagehand

# 或使用 pnpm
pnpm add @browserbase/stagehand

5.2 基本配置

创建配置文件 stagehand.config.ts：

import { defineConfig } from "@browserbase/stagehand";

export default defineConfig({
 llm: {
  provider: "openai",
  model: "computer-use-preview",
  apiKey: process.env.OPENAI_API_KEY,
 },
 browser: {
  headless: false, // 开发环境建议设置为false以查看浏览器操作
 },
});

5.3 基本用法

import { stagehand } from "@browserbase/stagehand";

async function run() {
 // 启动浏览器
 await stagehand.start();

 // 获取页面实例
 const page = stagehand.page;

 // 使用Playwright API进行确定性操作
 await page.goto("https://github.com/browserbase");

 // 使用AI单步操作
 await page.act("点击stagehand仓库");

 // 使用AI代理执行复杂任务
 const agent = stagehand.agent();
 await agent.execute("找到最新的PR");

 // 提取结构化数据
 const { author, title } = await page.extract({
  instruction: "提取PR的作者和标题",
  schema: z.object({
   author: z.string(),
   title: z.string(),
  }),
 });

 console.log(`PR作者: ${author}, 标题: ${title}`);

 // 关闭浏览器
 await stagehand.stop();
}

run().catch(console.error);

5.4 高级用法

自定义工具

import { stagehand } from "@browserbase/stagehand";

// 定义自定义工具
const tools = {
 getCurrentWeather: {
  description: "获取指定城市的当前天气",
  parameters: { city: "string" },
  handler: async ({ city }: { city: string }) => {
   // 调用天气API的代码
   return `北京的天气是晴朗，25°C`;
  },
 },
};

async function run() {
 await stagehand.start();

 const agent = stagehand.agent({ tools });
 const result = await agent.execute("告诉我北京的天气");

 console.log(result);

 await stagehand.stop();
}

run().catch(console.error);

操作预览

// 预览AI计划执行的操作而不实际执行
const plan = await page.planAct("找到搜索框并输入'人工智能'");
console.log("AI计划执行的操作:", plan);

// 如果满意，可以执行该计划
await page.executePlan(plan);

6. 常见问题解答

6.1 Stagehand 与 Playwright 有什么关系？

Stagehand 是基于 Playwright 构建的，它扩展了 Playwright 的功能，添加了 AI 能力。你可以将 Stagehand 视为"AI 增强版的 Playwright"。

6.2 使用 Stagehand 需要付费吗？

Stagehand 本身是开源的（MIT许可证），可以免费使用。但它需要调用 AI API（如 OpenAI），这部分通常是按使用量付费的。

6.3 Stagehand 适合生产环境吗？

是的，Stagehand 设计时就考虑了生产环境的需求。它提供了缓存机制、错误处理和可配置的超时设置，使其能够在生产环境中稳定运行。

6.4 Stagehand 支持哪些浏览器？

由于基于 Playwright，Stagehand 支持 Chromium、Firefox 和 WebKit（Safari）浏览器。

6.5 如何处理动态变化的网页？

Stagehand 的 AI 能力使其特别适合处理动态网页。AI 可以"看到"整个页面并理解其结构，而不仅仅依赖于固定的选择器。

6.6 Stagehand 有 Python 版本吗？

是的，Browserbase 也提供了 Stagehand 的 Python 版本：stagehand-python

7. 相关链接

• GitHub 仓库：https://github.com/browserbase/stagehand

• Browserbase 官网：https://browserbase.com

• Python 版本：https://github.com/browserbase/stagehand-python

8. 总结

Stagehand 代表了浏览器自动化领域的一次创新尝试，它巧妙地将确定性代码操作与 AI 的灵活性相结合，创造出一种更强大、更适应性强的自动化工具。通过允许开发者在同一个框架中无缝切换代码操作和自然语言指令，Stagehand 既保留了传统自动化工具的可靠性，又引入了 AI 处理复杂、多变场景的能力。无论是用于数据提取、自动化测试、流程自动化还是构建智能助手，Stagehand 都提供了一个强大而灵活的平台。对于需要处理兼具确定性和不确定性的浏览器交互流程的开发者来说，Stagehand 无疑是一个值得深入探索的工具。