10分钟跑通Stagehand：自然语言驱动的浏览器Agent SDK快速入门

10分钟跑通Stagehand自然语言驱动的浏览器Agent SDK快速入门【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand维护一套网页自动化脚本最折磨人的往往不是写第一版逻辑而是网站一改选择器就崩、每个按钮都要重新定位、每次回归都要人工点一遍。Stagehand 是 Browserbase 推出的浏览器 Agent SDKThe SDK For Browser Agents它把act、extract、observe三个原语封装成自然语言接口让自动化在页面变动后自我修复。跟着这份 Stagehand 安装与配置指南你需要准备 Node.js 22.18 和一个 Browserbase API Key复制粘贴几行命令就能跑通第一个能点击、能提数的浏览器自动化脚本。项目定位Stagehand 是什么、解决什么问题Stagehand 是一个专为浏览器 Agent 设计的开源 SDK核心解决“用自然语言稳定操作网页、并在站点结构变化后自愈”的问题。它保留你熟悉的 Playwright 风格 APIgoto、click、locator、screenshot同时提供自修复动作、面向 Agent 的页面上下文以及原生对跨进程 iframe 和封闭 Shadow DOM 的支持。官方仓库README。快速上手Stagehand 安装、密钥配置与首个示例整个流程分四步装依赖、配密钥、写脚本、跑起来。以 TypeScript 为例。环境准备确认本机 Node.js 版本不低于 22.18。如果你打算连云端浏览器Browserbase无需本地装 Chrome若用本地浏览器调试需先装好 Chrome。安装依赖任选一种包管理器pnpm add browserbasehq/stagehand zod # 或 npm install browserbasehq/stagehand zod配置密钥Stagehand 不会替你读环境变量也不自动加载 env 文件所以由你的代码把 Key 传给浏览器工厂。这里只需导出一个 Browserbase Key未显式指定模型时Model Gateway 会自动选模无需再配模型厂商 Key。export BROWSERBASE_API_KEYbb_live_...写脚本新建index.ts它依次调用extract、act两个原语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 { data } await stagehand.extract( Extract the value proposition from the page., z.object({ valueProposition: z.string() }), ); console.log(data.valueProposition); await stagehand.act(Click the Evals button.); } finally { await stagehand.close(); await browser.close(); }运行在浏览器控制台看到会话实时录屏pnpm dlx tsx index.ts想改用本机浏览器调试时把browserbase.launch()换成localBrowser.launch({ headless: true })即可省去云端 Key。详见 v4/configuration浏览器配置。核心能力实战act、extract、observe 三大原语上面的脚本只是热身。下面三个原语覆盖了“点、取、看”三类高频操作。用自然语言驱动页面点击与填表。act接收一句自然语言或一个Action单次执行一个动作把它拆成小步串联能组成经得起页面改版的自动化。await page.goto(https://example-store.com); await stagehand.act(click the add to cart button); await stagehand.act(fill the search box with AI browser);每行act会先跑模型推理定位目标再执行点击或填充无需你写选择器。开启selfHeal后即便录制过的选择器失效它也会重新推理恢复执行。用 Schema 约束结构化提取。extract同时接收指令和输出形状TS 用 Zod、Python 用 Pydantic返回前会按形状校验拿到手即为带类型对象。import { z } from zod/v4; // 省略其余 import const { data } await stagehand.extract( extract the product details, z.object({ name: z.string(), price: z.number(), inStock: z.boolean() }), ); console.log(data); // { name: …, price: 99.5, inStock: true }相比手写解析 HTML这种“声明要什么形状”的写法在页面布局微调时明显更抗造。先观察再执行缓存确定性动作。observe返回页面上所有可执行动作的结构化列表你可以先校验、再挑选执行把昂贵推理缓存下来。const { data: actions } await stagehand.observe(find the login button); console.log(actions.map((a) a.description)); // 列出可点击元素 await stagehand.act(actions[0]); // 直接回放 Action跳过推理把observe的结果交给act回放可把重复流程的模型调用降到零是提速和省钱的关键组合。三个原语的完整签名见 v4/basicsAct 参考。生态集成与进阶扩展Stagehand 不止独立使用官方提供了一组主流 Agent 框架的集成把浏览器能力直接挂进已有编排。Claude Code 集成让编码 Agent 直接调用浏览器完成验证见 v4/integrationsClaude Code。Mastra 集成在 Mastra 工作流里复用 Stagehand 页面动作见 v4/integrationsMastra。CrewAI 集成把浏览器步骤接入多 Agent 协作见 v4/integrationsCrewAI。Vercel AI SDK 集成与 AI SDK 的generate/stream流程对接见 v4/integrationsVercel AI SDK。规模上来后建议按以下方向继续调优服务端缓存重复动作跳过 LLM 调用v4/best-practicesCaching速度优化降低往返与推理延迟v4/best-practicesSpeed Optimization成本优化控制 token 与调用开销v4/best-practicesCost Optimization用户数据与隐私会话数据边界处理v4/best-practicesUser Data下一步跑更多官方示例packages/sdk-ts/examples/下含act.ts、extract.ts、batch.ts、webmcp.ts等可直接运行的脚本见 v4/first-stepsQuickstart。系统学习三大原语v4/basicsExtract 参考 与 v4/basicsObserve 参考。从 v3 迁移到 v4 的变更点见 v4/migrationsV3 迁移指南。想给 Stagehand 提 bug fix 或小改进先读 CONTRIBUTING。把第一个脚本跑起来只是把选择器的维护成本交给了 SDK真正的价值在于它能陪你把自动化从“能跑”推到“敢上生产”。【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考