Stagehand：把浏览器自动化拆成 observe、act、extract 的可验证 AI Agent SDK

如果你曾经把浏览器自动化接上大型语言模型，应该很快会遇到三个问题：页面结构一改，原本的 selector 就失效；把整个 DOM 丢给模型，token 成本与延迟一起上升；还有最现实的安全疑虑——登入资讯、付款资料或其他敏感栏位，不应该因为要让模型「看懂画面」就直接送进模型。

我最近研究 browserbase/stagehand 时，觉得它值得被注意的地方，不只是「可以用自然语言操作浏览器」，而是它把浏览器 Agent 的核心互动拆成三个可以分别理解、测试与治理的动作：observe 用来找出可操作的目标，act 用来执行动作，extract 用来依 schema 撷取资料。这个拆分让浏览器 Agent 不必是一个不可观测的黑盒子，也让开发者比较容易决定哪些步骤交给模型、哪些步骤仍然由程式控制。

本文以 Stagehand 官方 README、官方文件入口与 repository 内的 package metadata 为主，整理它的定位、实作模型、上手方式与限制。我的结论先讲在前面：如果你的问题是「让既有 Playwright 风格的浏览器流程多一层语意能力」，Stagehand 是一个很合理的研究与试作入口；但如果你需要完全可预测的高风险交易流程，仍然不应把每一个决策都交给自然语言代理。

Stagehand 解决的不是「没有 API」

传统浏览器自动化通常有两种极端。

第一种是纯 selector 驱动：开发者用 goto、click、locator、screenshot 等熟悉的浏览器 API 写出完整流程。这种方式可预测、容易测试，但它依赖页面结构。按钮从 #submit 改成另一个 class，或表单的巢状关系改变，测试就可能失效。

第二种是让模型直接看页面，再让模型自行决定下一步。这种方式对介面变动比较有韧性，却容易产生三种工程问题：模型拿到太多无关上下文、每一次动作难以重现，以及成功或失败的原因不容易被观测。

Stagehand 的定位比较像中间层。README 将它描述为 browser agents 的 SDK，同时保留 Playwright 风格的浏览器与元素 API。也就是说，你不需要把整个应用程式改写成「只有 prompt 的自动化」；可以保留确定性的浏览器控制，再把真正需要语意理解的部分交给 observe、act 或 extract。

这个差异很重要。AI Agent 不一定要负责整个流程，才叫 Agent。比较成熟的做法，通常是把模型放在人类最擅长描述、但传统 selector 不容易稳定表达的区段，例如「找到帐单表格中的所有发票」、「开启帐务页面」、「找出电子邮件输入框」。而登入、权限、金额上限、最后送出等高风险步骤，仍然应该保留明确的程式逻辑与验证。

三个核心动作：先理解，再操作，最后取回资料

1. `observe`：把自然语言转成可执行目标

observe 的用途，是让 Agent 根据页面语意找出可以操作的元素。官方范例用它寻找电子邮件与密码输入框，回传的是实际 selector 或可供后续操作使用的结果，而不是让模型直接接触完整凭证内容。

这里的工程价值在于「找目标」与「填入资料」可以分开。你可以让模型判断哪一个栏位是 email，再由程式把真正的值填入；模型只需要知道元素位置，不必知道秘密本身。这个边界不是自动完成的安全保证，但它提供了比「把整张画面和所有栏位值一起送给模型」更好的设计方向。

2. `act`：用意图描述操作，必要时重新计划

act 接收像「click the sign in button」或「open the billing page」这类自然语言指令。Stagehand README 特别强调，当网站表单改版时，act 可以重新寻找执行动作的方法，这就是它所谓的 self-healing 方向。

但我不会把 self-healing 解读成「永远不会坏」。它比较接近「当页面结构变动，但使用者意图与视觉／语意线索仍然存在时，系统有机会重新对应操作」。如果按钮文字改了、权限不足、页面被导向 CAPTCHA，或新的流程需要额外的业务规则，Agent 仍然可能失败。生产环境必须记录每个 action 的输入、候选元素、最后选择与错误原因，并设计 timeout、重试上限和人工接管。

3. `extract`：把非结构化页面变成 schema 验证的资料

extract 是我认为最容易落地的部分。你可以用自然语言描述要撷取的资讯，再提供 schema，让结果不是一段不可控的文字，而是可以被后续程式检查的资料。

官方范例是从表格撷取所有发票，并回传 schema-validated data。这使它适合用在研究助理、营运资料整理、后台报表汇出或跨网站的资料搜集。不过 schema 验证只能保证资料符合形状，不能保证来源内容正确。金额、日期、币别与权限状态仍应做栏位级验证，必要时保留原始页面或截图作为稽核证据。

一段可验证的最小流程

Stagehand 官方 README 提供 TypeScript、Python 与 Go 的使用范例。以下示范 TypeScript 的概念，重点是保留「先观察、再动作、最后撷取」的分层，而不是把所有事情塞进一个 prompt。

import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";
const browser = await localBrowser.launch({ userDataDir: "./browser-data" });
const stagehand = await Stagehand.create({ browser });
try {
  const [page] = await browser.context.pages();
  await page.goto("https://example.com/invoices");
  const table = await stagehand.observe("find the invoice table");
  console.log("table target:", table);
  await stagehand.act("open the invoices section");
  const result = await stagehand.extract(
    "extract every invoice from the table",
    z.object({
      invoices: z.array(
        z.object({
          number: z.string(),
          date: z.string(),
          total: z.string(),
        }),
      ),
    }),
  );
  console.log(result.data.invoices);
} finally {
  await browser.close();
}

这段程式有几个值得保留的界线。page.goto 是明确的程式操作；observe 与 act 处理需要理解介面的部分；extract 的输出则经过 schema 转换。实际导入时，我会再加上 URL allowlist、页面来源检查、敏感栏位遮罩、资料笔数上限与结果验证。若流程会修改资料，还要把读取与写入分成不同权限，不能因为 Agent 能找到按钮，就自动授予它修改帐务资料的权限。

如何开始：先跑本机，再决定是否使用云端浏览器

目前 repository 的主 workspace 是 4.0.0，TypeScript SDK package metadata 显示版本 4.1.0；Python SDK 也标示为 4.1.0。这提醒我们一件事：实际安装前要以你要使用的 package registry 与 release 状态为准，不要只看 repository 根目录版本。

TypeScript 前置条件

官方 README 的本机范例以 Node.js 与 pnpm 为入口，workspace 的 engines 要求 Node.js 至少 22.18.0，并且本机执行需要安装 Chrome。可以先建立一个干净目录，再安装 SDK：

pnpm add @browserbasehq/stagehand zod

接着用上面的最小范例验证三件事：浏览器能否启动、页面能否载入、模型与 Stagehand 是否能完成一次 observe 或 extract。不要一开始就串接正式帐号；先用公开测试页或本机 mock page，确认 log、timeout 与错误处理都能工作。

Python 与 Go 的选择

如果团队主要使用 Python，官方 package metadata 要求 Python 3.11 以上，安装入口是：

python -m pip install stagehand

在本地开发环境中，我会优先使用专案自己的虚拟环境或 uv 管理依赖，避免污染系统 Python。Go SDK 则在 README 中以 github.com/browserbase/stagehand/packages/sdk-go/v4 为 import 路径。三种语言的核心概念一致，但不要假设每个版本的 API 细节完全相同，应该以各 SDK 的官方 quickstart 与型别定义为准。

本机浏览器与 Browserbase

Stagehand 可以使用本机 browser，也可以指向 Browserbase 的 hosted browser。这两条路径的价值不同：本机适合开发与可控测试，云端浏览器则比较适合需要远端执行、工作阶段管理、录制与集中观测的团队。

README 也提到 Model Gateway、server-side caching、verified mode、residential proxies、persistent contexts 与 session recordings 等 Browserbase 能力。这些是服务整合与平台能力，不应直接算成 Stagehand SDK 本身的离线功能。导入前要分清楚：哪些能力在本机可用，哪些需要 Browserbase 帐户、API key 或特定方案。

对 AI Chain 团队最有价值的地方

一、把「浏览器 Agent」变成可拆解的 workflow

最值得借鉴的不是某一个 API 名称，而是设计方式。当我们把流程拆成 observe、act、extract，就能为每一段设定不同的评估指标：

observe 评估找对元素的比例，以及是否误选敏感栏位。
act 评估任务完成率、重试次数与平均延迟。
extract 评估 schema 通过率、栏位正确率与人工抽查结果。

这比只记录「整个 Agent 成功或失败」更有用。失败发生时，我们可以知道是找不到元素、动作被拒绝，还是资料撷取后验证失败。

二、保留传统自动化的逃生门

Stagehand 不是要求你放弃 Playwright 风格 API。这让它比较适合渐进式导入：先把一个脆弱的 selector 区段换成 observe，再把某个资料表换成 schema-based extract，其余流程维持原状。当模型服务不可用时，也可以为关键路径准备明确 selector 或人工审核 fallback。

三、同一套概念覆盖多种语言

官方 README 同时展示 TypeScript、Python、Go 的 SDK 入口。对有不同服务团队的组织来说，这降低了概念转换成本。不过跨语言不代表跨环境零成本：浏览器生命周期、非同步模型、错误型别与套件版本仍要分别测试。

限制与我不建议的用法

第一，self-healing 不能取代测试。网站改版后，Agent 可能「做完了一件看似合理、其实不是原本任务」的事情。因此要对关键结果做 postcondition 检查，例如确认 URL、页面标题、资料笔数与栏位值，而不是只看没有抛出例外。

第二，自然语言不是安全策略。若 Agent 能看到付款页面，就可能在错误情境下理解错误金额或错误帐户。所有不可逆操作都应该设计确认闸门，并限制模型可读取和可操作的网域、路径与元素。

第三，schema 验证不是事实验证。total 是字串且符合格式，不表示它真的等于页面上的总额。涉及财务、医疗、法律或权限的资料，必须建立独立的交叉验证与人工覆核。

第四，云端服务的能力与成本要独立评估。Browserbase、Model Gateway、快取、录制与代理等功能可能需要额外的帐户与费用。不要把 README 中的云端平台描述，误当成安装开源 SDK 后就自动拥有的功能。

第五，凭证管理必须先于 Agent。官方范例特别示范了 observe 找栏位，而不是把密码交给模型；实际系统仍应使用环境变数、secret manager、最小权限帐户与遮罩后的 log。任何「模型永远不会看到秘密」的说法，都必须透过实际资料流与 telemetry 验证，而不能只靠 API 名称推论。

我会怎么评估是否导入

如果要在团队内做一周 proof of concept，我会采用以下顺序。

第一天先建立没有正式凭证的测试页，记录浏览器启动、网路错误、模型请求与每一个 Stagehand 动作。第二天只测 extract，用固定 HTML 与固定 schema 建立基准资料。第三天加入 observe，比较 selector 版与语意版在页面小幅改版后的差异。第四天才加入 act，并且只允许非破坏性操作。第五天注入错误：空页面、权限不足、按钮消失、网路逾时、重复提交，确认系统会停止而不是自动猜测。最后两天再评估本机 Chrome 与云端 browser 的成本、延迟、可观测性与资料合规。

这个顺序有一个好处：你不会因为一个成功的 demo，就直接相信整个 Agent workflow 已经适合生产。先把结果定义、失败行为与资料边界固定下来，再扩大自然语言操作的范围。

结论：把模型放在最需要理解的地方

我认为 Stagehand 的核心价值，是把「浏览器自动化」重新整理成一个可组合的 Agent SDK，而不是单纯替 selector 加上一层聊天介面。observe、act、extract 让意图理解、操作执行与资料输出各自有清楚的责任边界；Playwright 风格 API 则保留了传统自动化的控制感。

它适合的团队，是已经有浏览器流程，想逐步处理页面变动、自然语言查询或结构化撷取的人。它不适合被当成「只要给一句话，就能安全操作所有网站」的万用代理。真正能不能落地，取决于你是否补上权限隔离、结果验证、可观测性、重试上限与人工接管。

如果你正在做研究助理、后台资料整理、跨网站查询或浏览器型 coding agent，我会建议先从一个只读、可重跑、可验证的 extract workflow 开始，再逐步引入 observe 和 act。先让模型帮你理解介面，再让它在明确边界内行动，通常比一开始就把整个浏览器交给它更可靠。

参考资料