Stagehand 实战指南5 分钟搭出会自愈的浏览器 Agent 自动化【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand如果你写过网页自动化脚本大概被这两件事折磨过网站改了个 class 名几百行选择器全部报废换成纯 AI Agent 后行为又变得飘忽不定出了错根本没法调试。Stagehand 就是为解决这个两难而生的——它是一套浏览器 Agent SDK核心能力是用自然语言驱动网页操作act、observe、extract 三个原语同时保留确定性的 Playwright 风格 API 兜底并提供选择器失效时自动重新推断的自愈机制。TypeScript、Python、Go 三端 SDK 能力完全对齐。先搞清楚 Stagehand 到底是什么一句话定位Playwright 是为测试写的Stagehand 是为 Agent 写的。它给你两层控制你可以自由混搭自己决定每一步用多少 AIAI 原语act()执行自然语言操作、observe()发现页面上可执行的动作、extract()按 schema 抽取结构化数据。网站改版后Stagehand 会检测到变化并自动刷新动作的执行方式。确定性 APIgoto、click、locator、screenshot这些你会的 Playwright 方法照样能用走 Chrome DevTools Protocol 直驱浏览器零推理开销。另外两个容易被忽略的工程点Token 效率优先页面上下文采用混合无障碍树裁剪Agent 只拿到理解页面所需的信息不多不少。运行时住在浏览器旁边以扩展形式贴近页面执行远端浏览器的操作延迟接近本地。五分钟跑起来安装到第一条自动化第 1 步装依赖以 TypeScript 为例要求 Node.js 22.18Python 3.11 / Go 1.26 也有同等的 SDKmkdir my-stagehand-app cd my-stagehand-app pnpm init -y pnpm install browserbasehq/stagehand zod官方文档对应 packages/docs/v4/first-steps/installation.mdx里面还有 Python 和 Go 的安装方式。第 2 步拿到 Browserbase API Key推荐把浏览器跑在 Browserbase 上托管浏览器是服务端缓存和 Model Gateway 的前提。在控制台首页右侧就能看到 Project ID 和 API Keyexport BROWSERBASE_API_KEYyour_api_key注意一个容易踩的点Stagehand 不会替你读环境变量也不会自动加载 .env 文件——你需要在代码里自己把 key 读出来传给浏览器工厂。不配置模型时Model Gateway 会自动挑选并认证模型所以连模型方的 API Key 都可以省掉。第 3 步写一个最小脚本下面这个脚本把三个原语各跑了一遍存成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); // 1. 抽取带上 schema返回的就是类型化数据 const { data: intro } await stagehand.extract( Extract the value proposition from the page., z.object({ valueProposition: z.string() }), ); console.log(intro.valueProposition); // 2. 操作一句话点击按钮 await stagehand.act(Click the Evals button.); // 3. 观察列出页面上可以做什么 const { data: actions } await stagehand.observe(What can I click on this page?); console.log(actions); } finally { await stagehand.close(); await browser.close(); }pnpm dlx tsx index.ts本地调试阶段不想用云端把browserbase.launch()换成localBrowser.launch()并装好 Chrome 即可详见 packages/docs/v4/configuration/browser.mdx。三原语 一层兜底能力逐个拆act()把操作写成一句人话await stagehand.act(click the add to cart button);act一次只做一件事点击、填表、输入、滚动、下拉选择、拖拽……都支持自然语言指令。关键用法是把复杂流程拆成连续的单步 act 调用——官方文档明确建议这么做packages/docs/v4/basics/act.mdx。它还能自动穿越 iframe 和 Shadow DOM页面快照默认合并所有 frame 的无障碍树复杂 DOM 结构不用你操心。observe()先侦察再行动const { data: actions } await stagehand.observe(find the latest PR);返回一组候选动作每个动作带selector、description、method、arguments。把其中某个Action直接传回act()可以零推理确定性重放const { data: actions } await stagehand.observe(click the login button); await stagehand.act(actions[0]); // 不再消耗模型推理这是生产环境里控制成本、保证确定性的核心套路。extract()拿回的是对象不是字符串const { data } await stagehand.extract( extract product details, z.object({ name: z.string(), price: z.number(), inStock: z.boolean(), }), );TypeScript 用 Zod、Python 用 Pydantic、Go 用类型参数Stagehand 会在返回前按你的 schema 校验结果。列表就包一层数组字段链接用z.url()之类的 URL 类型。给字段加.describe()描述能显著提高抽取准确度详见 packages/docs/v4/basics/extract.mdx。page API确定性的安全网当你明确知道选择器、或者某一步必须零推理时直接用 Playwright 风格的方法。下面这张图对比了同样的提取任务左边 Stagehand 十来行右边手写 Playwright 要翻 DOM 节点、匹配正则、处理列表几十行起两层混搭是 Stagehand 的设计精髓AI 负责易碎的路径确定性 API 负责关键路径每一步用多少 AI 由你定。完整实战一条链抓出结构化数据把三原语串起来是一个典型的生产形态——先观察、再操作、最后带 schema 抽取摘自仓库示例 packages/sdk-ts/examples/act.ts 的思路// 打开目标仓库页 const [page] await browser.context.pages(); await page.goto(https://github.com/browserbase); // 点进 stagehand 仓库 await stagehand.act(click on the stagehand repo); // 观察出最新 PR 链接这个候选动作并确定性点击 const { data: actions } await stagehand.observe(find the latest PR); await page.locator(actions[0].selector).click(); // 带 schema 抽取返回类型化结果 const { data: { author, title } } await stagehand.extract( extract the author and title of the PR, z.object({ author: z.string().describe(The username of the PR author), title: z.string().describe(The title of the PR), }), );新手常踩的 5 个坑一条 act 塞多个步骤。打开筛选面板选 4 星点应用这种多步指令不可靠拆成三次单步 act 才是正确姿势。extract 不给 schema。不带输出形状的抽取结果不可控字段可能缺失就标可选价格带货币符号就用 string 而不是 number。在本地浏览器上开缓存。cache选项只在 Browserbase 会话下生效本地浏览器每次调用都会真实走推理——别以为开了就省钱packages/docs/v4/best-practices/caching.mdx。把密码写进指令文本。用%password%变量占位真实值在本地替换不会暴露给模型开启缓存时携带凭证的调用记得关掉 cache。动态内容没等就抽取。先用page.waitForSelector(...)确认节点出现注意它超时会返回 false 而不是抛错再执行 extract。走向生产的几个进阶开关自愈Stagehand.create({ selfHeal: true })后当act重放的记录选择器失效时会自动重新推断并重试一次。服务端缓存cache: true打开后相同输入的动作直接命中缓存返回不消耗 token缓存键包含指令、页面内容和调用选项跨机器、跨脚本执行都有效。可观测性metrics()可读取每个方法的 token 用量和推理耗时支持 OTel生产环境排查成本问题有抓手。生态MCP 集成Claude Code、Codex 等、LangChain、CrewAI、Mastra 等框架适配都在 packages/integrations/ 下官方定位是Stagehand 是手你自带 Agent 当大脑。接下来可以做的三件事跑通上面那个最小脚本然后打开 packages/docs/v4/first-steps/quickstart.mdx 对照三种语言的完整写法。浏览 packages/sdk-ts/examples/ 里的 act、extract、observe、batch、caching 等示例每个都对应文档里的一类场景。把脚本迁移到真实任务先用 observe 侦察目标页面能做什么把最易碎的步骤换成 act selfHeal其余保留 page 确定性 API——这就是 Stagehand 推荐的混合写法。仓库源码结构、三语言 SDK 细节和贡献指南分别在 packages/sdk-python/README.md、packages/sdk-go/README.md 与 CONTRIBUTING.md遇到问题可以直接翻源码找答案。【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考