企业官网建设流程全解析

Stagehand 入门指南：用浏览器代理 SDK 跑通自然语言网页自动化

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand

Stagehand 是 Browserbase 出品的浏览器代理 SDK，面向浏览器自动化场景，提供act、observe、extract三个自然语言原语，同时支持 TypeScript、Python 和 Go。你可以用它驱动浏览器完成点击、观测和结构化数据提取，无需手写复杂选择器。

什么时候你会需要它

你写过一个基于选择器的爬虫或 E2E 脚本，上线后页面一改版，点击、提取逻辑就集体失效；要么你给大模型喂整个页面快照，token 成本高得吓人，模型还会被无关元素带偏。再加上目标站点用跨进程 iframe、封闭 Shadow DOM 包裹组件，传统工具连元素都找不到。这类"选择器一断就崩、上下文又太啰嗦"的场景，就是浏览器代理要解决的问题。

为什么是 Stagehand 而不是现成工具

• API 迁移成本低：goto、click、locator、screenshot都是 Playwright 风格，官方定位就是"Playwright 为测试而生，Stagehand 为代理而生"。
• 自愈能力：页面改版后，act、observe检测到选择器失效会自动重新推断并刷新操作方式。
• 省 token：内置混合无障碍树裁剪，只把模型理解页面所需的最小上下文喂给它。
• 延迟更低：运行时以浏览器扩展形式跑在浏览器旁边，减少每次操作的往返开销。
• 兼容复杂 DOM：原生支持跨进程 iframe 与封闭 Shadow DOM，配合深定位器（deep locators）直达嵌套元素。

环境要求与安装步骤

前置清单：Node.js ≥ 22.18（推荐运行时，Bun 也可用）；Python ≥ 3.11 或 Go ≥ 1.26（用对应 SDK 时才需要）；一个BROWSERBASE_API_KEY。想在本地起浏览器调试的话，机器上还需装好 Chrome；走云浏览器则可跳过。

mkdir my-stagehand-app && cd my-stagehand-app pnpm init -y pnpm install @browserbasehq/stagehand zod export BROWSERBASE_API_KEY="bb_live_..."

Python 侧则是pip install stagehand，Go 侧是go get github.com/browserbase/stagehand/packages/sdk-go/v4@v4.0.0。注意：没配置模型时，Browserbase 的 Model Gateway 会自动为每次推理选模型，你不必额外准备模型厂商的 key。

最小可运行示例

把下面代码存为index.ts：

import { browserbase, Stagehand } from "@browserbasehq/stagehand"; import { z } from "zod/v4"; const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY, }); const stagehand = await Stagehand.create({ browser }); try { const [page] = await browser.context.pages(); await page.goto("https://stagehand.dev"); const result = await stagehand.extract( "Extract the value proposition from the page.", z.object({ valueProposition: z.string() }), ); console.log(result.data); await stagehand.act("Click the 'Evals' button."); } finally { await stagehand.close(); await browser.close(); }

运行pnpm dlx tsx index.ts，你会看到云端浏览器自动打开目标页、控制台打印出提取到的文案对象、随后页面上"Evals"按钮被点击。

三个原语与关键概念拆解

• act()：执行单个动作，接受自然语言指令；传入observe()返回的Action则可确定性地直接重放，不再走模型推理。
• observe()：描述你想找什么（如"找出最新 PR"），返回页面上可操作元素的列表，每项带selector，可直接喂给page.locator(selector).click()做确定性点击。
• extract()：配合 Zod schema 把页面内容抽成结构化对象，字段用describe()说明含义，提取结果类型可控。
• 浏览器工厂三选一：browserbase.launch()连云浏览器（支持服务端缓存与 Model Gateway），localBrowser.launch()在本机起 Chromium，localBrowser.connect({ cdpUrl })挂到你已在跑的 Chrome。
• 缓存：开启后act会缓存动作，等价 URL 会命中缓存，省掉重复的 LLM 调用。

这几个场景值得先试

• 本地快速调试：把browserbase.launch()换成localBrowser.launch({ headless: true })即可去掉云浏览器 key，本地迭代更顺手。
• 接入手头 Chrome：localBrowser.connect({ cdpUrl: "http://127.0.0.1:9222" })直接复用已启动的浏览器实例。
• 给自动化加安全边界：用context.setDomainPolicy({ allowedDomains / blockedDomains })限定可访问域名，违规弹窗会被自动关闭，详见 浏览器配置文档。

四条真实的坑

• v3 到 v4 是大版本重构：4.0 围绕新的浏览器协议重写了 TypeScript/Python SDK，老代码升级前先看迁移文档 v3 迁移指南。
• 环境变量它不替你读：官方明确 Stagehand 不会自动读取.env，你得自己加载（如import "dotenv/config"）并把 key 显式传给浏览器工厂。
• 浏览器生命周期归你自己：browser.close()只关它自己启动的浏览器，本地模式下机器上还必须有 Chrome 可执行文件。
• 想省钱就重放：给act开启缓存或selfHeal，选择器断掉时自动重新推断，而不是每次都烧一次模型调用。

进阶可以看这些目录

完整文档在 packages/docs/v4/，按 act、observe、extract 三个原语展开，另有缓存、部署、成本优化等实践章节，v2/v3 旧版文档也留档在同目录。三语言对照示例在 packages/sdk-ts/examples/，Python、Go 示例分别在同层的sdk-python、sdk-go包里。想要压测自己场景的通过率，packages/evals/ 内置了act/extract/observe基准任务和 WebVoyager 等数据集套件，pnpm build:cli后跑evals即可。

受够了给选择器"打补丁"的话，就交给 Stagehand 去自愈吧。

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand