Stagehand AI 浏览器自动化实战指南：5 个真实场景让脚本更稳更省

Stagehand AI 浏览器自动化实战指南：5 个真实场景让脚本更稳更省

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

Stagehand 是一个为浏览器 Agent 而生的 SDK：它把网页的无障碍树交给大模型理解，让你用一句自然语言就能完成点击、填表和数据提取，同时提供 TypeScript、Python、Go 三套官方 SDK。这篇文章不罗列功能，而是按真实项目里最常遇到的五个问题——重复执行烧钱、多步流程慢、多页面并行、成本失控、何时让 AI 自主浏览——逐一给出 Stagehand 的官方做法。每个方案都能在官方文档里找到对应实现，照着做即可验证。

先用 10 行脚本建立手感

第一次接触 Stagehand，只需要认识三个核心方法。安装后，用 Browserbase 云端浏览器启动一个会话（本地调试可换成localBrowser.launch()，无需 API key）：

pnpm install @browserbasehq/stagehand zod

import { browserbase, Stagehand } from "@browserbasehq/stagehand"; const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY }); const app = await Stagehand.create({ browser }); const page = (await browser.context.pages())[0]; await page.goto("https://example.com/search"); // 1. 操作页面：自然语言即可 await app.act("type 手机壳 into the search box"); // 2. 提取结构化数据：用 zod 描述你要的形状 const { data } = await app.extract( "extract the first three product titles", z.object({ items: z.array(z.string()) }), ); // 3. 探测页面：不执行，只列出可执行的动作 const { data: actions } = await app.observe("find the filter buttons");

三个方法各管一摊，后面所有技巧都是围绕它们展开的：

完整入门步骤见 quickstart 文档，可运行的示例代码在 packages/sdk-ts/examples/。

场景一：同一流程天天跑，如何不再重复付推理费

问题：一个登录流程或固定报表采集每天都在执行，页面没变，但每次都完整调用大模型，费用随运行次数线性增长。

做法：Stagehand 在服务端缓存act()、observe()、extract()的结果。开启方式是在初始化时加一个选项：

const app = await Stagehand.create({ browser, cache: true, // 服务端缓存；也可写成 cache: { threshold: 2 } 控制生效门槛 });

• threshold（命中门槛）：浏览器端需要看到多少次相同结果后才开始直接回放。设为1时，第二次相同调用即命中。
• 如何验证：每次调用的metadata.cache.status会返回HIT、MISS或DISABLED，命中时还会记录节省的 token 数，效果可直接量化。
• 自愈机制：缓存回放是确定性的。如果页面改版导致记录的选择器失效，Stagehand 会自动退回完整推理，并把新结果写入缓存，流程不会中断。
• 注意：缓存依赖 Browserbase 会话，本地浏览器下该选项不生效。

详细的键构成（指令 + 页面内容 + 参数）、动态值处理与失效边界，见 caching 最佳实践。

场景二：多步流程太慢？先 observe 做计划，再批量回放

问题：填一个 8 个字段的形式，如果写 8 次act("填写 xx 字段")，就要做 8 次模型推理，既慢又贵。

做法：利用observe()的"只规划不执行"特性，一次推理拿到全部字段的Action，再循环回放。回放传入的是Action对象而非自然语言，Stagehand 会直接按记录的选择器和方法执行，不再推理：

// 一次推理，规划所有字段 const { data: fields } = await app.observe("find all input fields in the signup form"); // 逐个回放，后续步骤零推理开销 for (const field of fields) { await app.act(field); }

官方基准测试中，一个"填表 → 提交 → 确认"的三步流程用这种模式从约 8 秒降到约 0.5 秒（推理次数从 3 次变为 1 次）。

进阶：动态值不要写进指令。账号、密码这类值如果拼在指令字符串里，会随每次运行变化而破坏缓存，还可能进入模型上下文。用variables占位符，模型只看到%password%，真实值在执行前本地替换：

await app.act("fill the login form", { variables: { username: "alice@example.com", password: process.env.USER_PASSWORD, }, });

该模式的完整讲解与耗时对比见 speed-optimization 文档。

场景三：多个页面同时处理，用多标签页并行

问题：需要同时采集两个竞品页面，或对比多个搜索结果，串行执行把总时长翻倍。

做法：在同一个浏览器上下文里开多个标签页，每个调用通过page选项指定目标页，再用Promise.all并发：

const pageA = await browser.context.newPage(); const pageB = await browser.context.newPage(); await Promise.all([pageA.goto(urlA), pageB.goto(urlB)]); const [resA, resB] = await Promise.all([ app.extract("extract the pricing table", PriceSchema, { page: pageA }), app.extract("extract the pricing table", PriceSchema, { page: pageB }), ]);

两个容易踩的坑：

1. 页面对象是固定的：点击后如果浏览器打开了新标签页，之前持有的page仍指向旧标签；要么重新读取活动页，要么为每个标签显式持有引用。
2. locator 属于创建它的页：一个标签页上生成的 locator 不能拿去另一个标签页解析。

多标签页的完整模式（包括setActivePage切换默认目标）见 using-multiple-tabs 文档。

场景四：成本账单怎么控住？三个可量化的旋钮

问题：任务量上来后，模型调用费 + 浏览器会话费开始可见地增长。

Stagehand 提供的控制手段可以归纳为三个旋钮：

模型选择：不配置model时，Model Gateway 会为每次调用自动选模型，一个 key 出账单；想精细控制时，可以在单次调用上覆盖：

// 默认：轻量模型处理绝大多数步骤 const app = await Stagehand.create({ browser, model: { modelName: "google/gemini-2.5-flash" }, }); // 只在关键的一次提取上升级到强模型 await app.extract("summarize the contract terms", TermsSchema, { model: { modelName: "anthropic/claude-sonnet-4-6" }, });

会话复用：把timeout从默认的 1 小时调短（如 30 分钟），并对连续任务开启keepAlive复用会话，避免每次冷启动。用完记得await app.close()和await browser.close()。

用量监控：metrics()返回 token 计数（不直接返回金额），乘以供应商的输入/输出单价即可换算成本；其中totalCachedInputTokens单独列出，方便确认缓存命中带来了多少折扣。

模型路由规则、会话参数与预算控制的完整参考见 models 配置 和 cost-optimization 文档。

场景五：什么时候该让 AI 自主浏览整个任务

问题：任务不是固定流程，而是"打开 Hacker News，找出今天最有争议的帖子，总结前三条评论"这种需要 AI 自己看屏幕、自己决策的步骤。

现状说明（以仓库内文档为准）：

• v3 时代：Stagehand 内置agent()，支持mode: "cua"对接 Google、Anthropic、OpenAI 的 Computer Use 模型，一行execute({ instruction, maxSteps })即可让模型自主操作浏览器，详见 computer-use 文档。
• v4 时代：官方移除了内置 agent（v3 → v4 迁移指南 中agent({ mode: "cua" })标注为无等价物），回归act / observe / extract三个原语，把"多步规划"交还给你的代码或外部编排层。这也意味着：自主浏览能力现在由你在三个原语之上实现——observe()看一步、act()走一步、失败时换模型重试——每一步都可控、可缓存、可回放。

简单选型建议：

• 流程固定且重复→ 三个原语 + 缓存，成本最低、最稳定；
• 任务开放、步骤不定→ v3 的 cua agent 或在你自己的编排层里用"observe 规划 + act 执行"循环，配合maxSteps类限制防止跑飞。

延伸阅读：文档与源码地图

掌握以上五个场景后，基本覆盖了一个生产级浏览器自动化项目的全部关键决策点：用缓存消除重复推理、用 observe 回放压缩多步流程、用多标签页换并行、用模型与旋钮控制账单、在流程开放时再引入自主浏览。建议下一步直接从 quickstart 跑一个脚本，然后按自己项目里最先痛的那个场景深入对应章节。

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