舞台工作人员 + 无痕：云浏览器上的AI浏览器自动化

TL;DR:

• Stagehand 是一个将简单英语指令与真实的 Playwright 代码相结合的 AI 浏览器自动化框架，在 Chrome DevTools 协议会话上暴露了三个基本原语——act、extract 和 observe。
• 只需设置一个字段 localBrowserLaunchOptions.cdpUrl 指向 Scrapeless Scraping Browser 的 WebSocket 端点。您的 Stagehand 代码没有其他更改。
• 浏览器在云端运行，因此您的自动化获得了管理会话、指纹识别和住宅出口，而不是必须启动、扩展和保持不受阻塞的本地 Chromium。
• 您提供自己的模型密钥。 Stagehand 调用语言模型进行 act/extract/observe；浏览器和模型是两个独立的关注点。
• 免费开始。 新的 Scrapeless 账户包括免费的 Scraping Browser 欠款 — 请在 app.scrapeless.com 注册。

Stagehand 是来自 Browserbase 的开源框架，位于两个极端之间：每次标记更改都会中断的脆弱选择器脚本，以及无法预测的自由漫游代理。它为您提供了三个可组合的原语——act 用于执行操作，extract 用于提取结构化数据，以及 observe 用于查找元素——每个都由自然语言指令驱动，并返回到您的控制。Stagehand 仍然需要的是一个驱动的浏览器。在本地运行该浏览器意味着要启动 Chromium、进行扩展，并防止其被阻塞。本指南将 Stagehand 与 Scrapeless Scraping Browser 连接，这样框架保持不变，而浏览器则移至云端。下面的每个命令和输出都是从实时运行中捕获的。

此集成为您提供的内容

Stagehand 通过 Chrome DevTools 协议 连接到浏览器。Scrapeless Scraping Browser 正是提供这样的服务：一个您可以通过 WebSocket URL 访问的真实 Chrome 环境。将二者连接起来的意思是：

• 无需操作本地浏览器。 您无需启动、修补或扩展 Chromium；会话在服务器端运行，您与它连接。
• 管理会话和出口。 云浏览器处理真实的设备配置文件和住宅路由，因此 Stagehand 读取的页面看起来像是真实访客的页面。
• 相同的 Stagehand API。 无论浏览器是本地还是远程，act、extract 和 observe 的行为相同——只有连接 URL 的变化。
• 关注点的清晰分离。 Scrapeless 运行浏览器；您选择的模型运行推理。您可以在不接触另一个的情况下更换任一方。

前提条件

• Node.js 20.19+ 或 22.12+ 和一个包管理器（本指南使用 pnpm）。
• Scrapeless Scraping Browser 的 API 密钥——请在 app.scrapeless.com 的免费计划中获取一个。
• 一个模型提供商的 API 密钥。Stagehand 调用语言模型以获得其原语；任何受支持的提供商均可使用。

安装

添加 Stagehand 和 Zod，该库为 extract 的结构化输出提供类型：

pnpm add @browserbasehq/stagehand zod

将 Stagehand 连接到 Scraping Browser

整个集成只需一个字段。Stagehand 的 localBrowserLaunchOptions.cdpUrl 接受 CDP WebSocket 端点；传入 Scrapeless Scraping Browser URL，您的 API 密钥作为 token 查询参数单独提供。模型则以 llmClient 的形式提供。

import { Stagehand, AISdkClient, getAISDKLanguageModel } from "@browserbasehq/stagehand";
import { z } from "zod";

// 您自己的模型提供者（这里是 OpenAI；可以输入任何支持的提供商密钥）。
const model = getAISDKLanguageModel("openai", "gpt-4o-mini", {
  apiKey: process.env.OPENAI_API_KEY,
});

const stagehand = new Stagehand({
  env: "LOCAL",
  llmClient: new AISdkClient({ model }),
  localBrowserLaunchOptions: {
    cdpUrl:
      `wss://browser.scrapeless.com/api/v2/browser` +
      `?token=${process.env.SCRAPELESS_API_KEY}` +
      `&session_ttl=180&proxy_country=US`,
  },
});

await stagehand.init();

在 init() 之后，Stagehand 正在驱动 Scrapeless 托管的 Chrome 会话。Playwright 上下文可用作 stagehand.context，而三个 AI 原语则存在于 stagehand 实例中。

驱动页面

导航使用标准的 Playwright 上下文。获取活动页面并转到目标：

const context = stagehand.context;
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://news.ycombinator.com", { waitUntil: "domcontentloaded" });

observe — 用简单英语查找元素

observe 返回解析的选择器的候选元素，因此您可以在运行操作之前检查操作将针对的内容：

const candidates = await stagehand.observe("顶部导航栏中的登录链接");
console.log(candidates[0]);

一次实时运行返回了一个解析的候选项：

// 从实时抓取器运行中捕获。
{
  "description": "顶部导航栏中的登录页面链接",
  "method": "click",
  "arguments": [],
  "selector": "xpath=/html[1]/body[1]/center[1]/table[1]/tbody[1]/tr[1]/td[1]/table[1]/tbody[1]/tr[1]/td[3]/span[1]/a[1]"
}

extract — 将页面转换为类型化数据

extract 接收一个指令和一个 Zod schema，并返回与 schema 匹配的数据。schema 是契约；Stagehand 从页面填写它：

const result = await stagehand.extract(
  "提取首页的前 3 个故事标题及其得分",
  z.object({
    stories: z.array(z.object({ title: z.string(), points: z.number() })).max(3),
  }),
);
console.log(result);

实时运行返回了直接来自首页的类型化行：

// 从实时运行中捕获 — 来自首页的真实标题和得分。
{
  "stories": [
    { "title": "在没有 GPU 的情况下，在 13 年老的 Xeon 上以每秒 5 个令牌运行 Gemma 4 26B (neomindlabs.com)", "points": 82 },
    { "title": "Telegram 数据中心的神秘 (dev.moe)", "points": 163 },
    { "title": "开源内存用于编码代理，通过 SSH 同步 (github.com/vshulcz)", "points": 43 }
  ]
}

act — 从指令中执行操作

act 在页面上执行简单英语操作。在这里，它单击一个导航链接，将会话移动到新 URL：

console.log(page.url()); // https://news.ycombinator.com/
await stagehand.act("点击顶部导航栏中的'新'链接");
await page.waitForLoadState("domcontentloaded");
console.log(page.url()); // https://news.ycombinator.com/newest

实时运行从 https://news.ycombinator.com/ 导航到 https://news.ycombinator.com/newest，确认指令解析为真正的点击。

关闭会话

在运行完成时释放云浏览器：

await stagehand.close();

为什么在 Scrapeless 上运行浏览器

Stagehand 对浏览器的存在没有明确的意见 — 这使得 cdpUrl 的切换如此简洁。自己运行 Chromium 对于笔记本电脑演示来说很好，但真正的工作负载意味着并发、会话卫生，并在多个页面之间保持不被阻塞。Scrapeless 抓取浏览器是一个真实的 Chrome 环境，具有现实的设备和指纹配置文件以及住宅出口，通过同一 CDP WebSocket 连接 Stagehand 已经可以使用。您保持 Stagehand 的编程模型，将浏览器操作交给托管服务。连接选项 — 会话寿命、区域和指纹 — 在 Scraping Browser 文档 中覆盖，想要不同 CDP 驱动的代理集成请参见 Hermes 浏览器技能教程。

在 app.scrapeless.com 上获取您的免费计划密钥，抓取浏览器的积分涵盖第一次运行。

结论

Stagehand 通过您指向的单个 URL 提供 act、extract 和 observe。将 localBrowserLaunchOptions.cdpUrl 设置为 Scrapeless 抓取浏览器端点，提供您的模型密钥，框架在托管的云浏览器上保持不变运行 — extract 返回 schema 类型的数据，act 从简单英语驱动页面。连接是一个字段；您在上面构建的一切保持不变。
准备在云浏览器上运行您的 Stagehand 脚本吗？从 Scrapeless 仪表板 免费开始，查看 Scraping Browser 产品页面，或在 Scrapeless 定价 上比较计划。

常见问题

问：什么是 Stagehand？
答：Stagehand 是来自 Browserbase 的一个开源浏览器自动化框架，它在 Chrome DevTools 协议会话的基础上增加了三个自然语言原语——act、extract 和 observe，因此您可以将简单的英语指令与确定性的 Playwright 代码混合使用。

问：Stagehand 如何连接到 Scrapeless Scraping Browser？
答：在 Stagehand 构造函数中设置 localBrowserLaunchOptions.cdpUrl 为 Scrapeless WebSocket 端点 wss://browser.scrapeless.com/api/v2/browser，并将您的 API 密钥作为 token 查询参数。然后，Stagehand 通过 CDP 驱动云会话。

问：我还需要语言模型密钥吗？
答：需要。Scrapeless 提供浏览器；Stagehand 调用模型执行 act、extract 和 observe。通过 Stagehand 的模型配置提供您自己的提供者密钥——浏览器和模型保持分开。

问：当我转到云浏览器时，我的 Stagehand 代码会改变吗？
答：不会。只有连接 URL 会改变。无论浏览器是本地的还是远程的 Scrapeless 会话，act、extract、observe 和 Playwright 上下文的行为是相同的。

问：我如何从页面获取结构化数据？
答：使用指令和 Zod 模式调用 extract。Stagehand 返回一个符合模式的对象——例如一个 { title, points } 的数组——因此您获得的是类型化数据，而不是原始 HTML。

问：我如何设置浏览器的区域？
答：将 proxy_country 查询参数添加到 Scrapeless CDP URL，以便会话的出站流量与您想要查看的市场匹配。

问：我可以在对元素进行操作之前检查它吗？
答：可以。使用描述调用 observe；它会返回匹配的元素，并提供已解析的选择器和建议的方法，您可以在执行 act 之前进行查看。