Stagehand 是一个由 Browserbase 团队维护的人工智能驱动的网页浏览框架，它是 Playwright 的后继者，提供了三个简单的 API（act、extract 和 observe），这些 API 提供了构建自然语言驱动的网页自动化操作的基础。

Stagehand 的目标是提供一个轻量级、可配置的框架，没有过于复杂的抽象，同时模块化地支持不同的模型和模型提供商。它不会帮你订披萨，但会帮助你可靠地自动化网页操作。

每个 Stagehand 函数接受一个原子指令，例如 act("点击登录按钮") 或 extract("找到红色的鞋子")，生成相应的 Playwright 代码来完成该指令，并执行它。

开始使用

1. 安装 Stagehand 包

   bash

   npm install @browserbasehq/stagehand zod

2. 配置你的模型提供商 你需要提供你想要使用的模型提供商的 API 密钥。默认的模型提供商是 OpenAI，你也可以使用 Anthropic 或其他提供商。更多支持的模型信息可以在 API 参考中找到。

   bash

   export OPENAI_API_KEY=sk-...
   export ANTHROPIC_API_KEY=sk-...

3. 创建 Stagehand 实例 如果你计划在本地运行浏览器，你还需要安装 Playwright 的浏览器依赖。

   bash

   npm exec playwright install

   然后你可以这样创建一个 Stagehand 实例：

   javascript

   import { Stagehand } from "@browserbasehq/stagehand";
   import { z } from "zod";
   
   const stagehand = new Stagehand({
     env: "LOCAL",
   });

   如果你计划在远程运行浏览器，你需要设置 Browserbase API 密钥和项目 ID。

   bash

   export BROWSERBASE_API_KEY=...
   export BROWSERBASE_PROJECT_ID=...

   javascript

   import { Stagehand } from "@browserbasehq/stagehand";
   import { z } from "zod";
   
   const stagehand = new Stagehand({
     env: "BROWSERBASE",
   });

4. 运行你的第一个自动化操作

   javascript

   await stagehand.init();
   await stagehand.page.goto("https://github.com/browserbase/stagehand");
   await stagehand.act({ action: "点击贡献者" });
   const contributor = await stagehand.extract({
     instruction: "提取顶级贡献者",
     schema: z.object({
       username: z.string(),
       url: z.string(),
     }),
   });
   console.log(`我们最喜欢的贡献者是 ${contributor.username}`);

   这个简单的代码片段将打开一个浏览器，导航到 Stagehand 仓库，并记录顶级贡献者。

API 参考

• Stagehand() 用于创建 Stagehand 的实例。

• init() 异步初始化 Stagehand 实例。在调用其他方法之前应该先调用此方法。

• act() 允许 Stagehand 与网页交互。提供一个动作，如 "搜索 'x'" 或 "选择最便宜的航班"（小的原子目标执行效果最佳）。

• extract() 使用 zod 从当前页面抓取结构化文本。给定指令和模式，你将收到结构化数据。

• observe() 用于获取当前页面上可以采取的操作列表。它有助于为你的计划步骤添加上下文，或者如果你不确定你所在的页面。

• page 和 context page 和 context 分别是 Playwright 的 Page 和 BrowserContext 的实例。使用这些方法与 Stagehand 使用的 Playwright 实例交互。最常见的是，你会使用 page.goto() 导航到一个 URL。

• log() 用于在浏览器控制台打印消息。这些消息将保留在 Browserbase 会话日志中，并且可以在会话完成后用于调试。

模型支持

Stagehand 利用通用的 LLM 客户端架构来支持来自不同提供商的各种语言模型。这种设计允许灵活性，使得集成新模型时对核心系统的更改最小。不同的模型对不同的任务效果更好，所以你可以选择最适合你需求的模型。

如何工作

SDK 有两个主要阶段：

1. 处理 DOM（包括分块 - 见下文）。
2. 根据 DOM 的当前状态采取 LLM 驱动的操作。

提示技巧

提示 Stagehand 比包括代理框架在内的其他高级框架更字面和原子。以下是一些帮助你制定有效提示的指南：

• 使用具体且简洁的动作。
• 将复杂任务分解为更小的原子步骤。
• 使用 observe() 从当前页面获得可操作的建议。
• 不要使用宽泛或模糊的指令。
• 不要将多个动作合并为一个指令。
• 不要期望 Stagehand 执行高级规划或推理。

通过遵循这些指南，你将提高 Stagehand 在网页自动化中的可靠性和有效性。记住，Stagehand 在执行精确、定义良好的动作方面表现出色，因此保持你的指令原子化将带来最好的结果。

我们把代理行为留给更高级别的代理系统，它们可以使用 Stagehand 作为工具。