用一句话驱动浏览器：Stagehand 浏览器代理 SDK 入门与实践

用一句话驱动浏览器Stagehand 浏览器代理 SDK 入门与实践【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand如果你写过网页自动化脚本大概都体会过这种烦恼选择器写好了网站一改版就全线报废还得回来手动修。Stagehand 正是为解决这个问题而生的浏览器代理browser agentSDK它把「打开页面、点击按钮、抓取数据」这些操作变成一句自然语言指令并提供 TypeScript、Python、Go 三套 SDK适合想给项目加自动化能力的开发者和 AI 应用作者。从选择器地狱里走出来传统做法是 Playwright 那一路page.click(div.container ul li:nth-child(3) a)。这种方式确定性强但对真实网页来说非常脆弱——页面结构一变脚本就失效而且你要为每个操作手工维护选择器路径。Stagehand 换了一个思路既然维护选择器这么痛苦那就让 AI 来判断该点哪里、该抓什么。它保留了 Playwright 风格的 APIgoto、click、locator、screenshot你熟悉的调用方式基本不变同时新增了三个用自然语言驱动的入口。下面这张对比图很直观左边几行 Stagehand 代码右边是完成同样任务需要的 Playwright 代码。对新手来说这意味着什么你不用再逐个研究页面 DOM 结构把「提取 AI 资助公司及批次号」这样的需求直接说给 SDK它会自己找到对应元素。页面改版后它也会重新定位而不是直接报错——官方把这叫作 self-healing自愈动作。十分钟跑通第一个自动化上手路径很短装 SDK、配密钥、跑一个脚本。以 TypeScript 为例mkdir my-stagehand-app cd my-stagehand-app pnpm init -y pnpm install browserbasehq/stagehand zod装好之后准备两个环境变量OPENAI_API_KEY或其他 LLM 提供商的密钥和BROWSERBASE_API_KEY云端浏览器凭据。脚本部分可以先从官方示例抄起const browser await browserbase.launch({ apiKey: BROWSERBASE_API_KEY }); const stagehand await Stagehand.create({ browser }); const [page] await browser.context.pages(); await page.goto(https://example.com); const result await stagehand.extract( Extract the page heading and description, z.object({ heading: z.string(), description: z.string() }), );这段代码完成了完整闭环启动浏览器、打开页面、用一句话提取结构化数据。你需要关注的只有两处——extract第一个参数是自然语言任务描述第二个参数是 zod schema用来约束返回的 JSON 结构保证拿到的数据字段稳定。完整脚本可以照着 packages/sdk-ts/examples/ 目录下的示例写里面按功能分好了文件act.ts负责点击操作observe.ts负责页面探索caching.ts、batch.ts演示进阶用法。如果你用 Python 或 Go对应的 packages/sdk-python/ 和 packages/sdk-go/ 下也有 README 和同名示例。想直接搭一个可运行的项目脚手架可以用官方 CLInpx create-browser-app执行后会生成一个带浏览器演示页面的项目跑起来就能看到自动化的实时效果比对着文档空想要快得多。三个入口 一个代理覆盖自动化日常Stagehand 把自动化能力拆成四个入口日常 90% 的需求都在这几行 API 里act —— 执行操作。传入一句指令即可比如stagehand.act(Click the Evals button.)。它内部会先找到目标元素再执行点击、输入等动作找到失败时会重试而不是直接崩掉。extract —— 结构化取数。上面示例已经见过特点是返回严格符合 schema 的对象方便直接喂给后端或下游模型。observe —— 先看再动。如果你不确定页面上有哪些可交互元素可以先问一句「这个页面上我能点什么」它会返回一组候选动作和对应选择器。适合写多步脚本前做侦察也能把结果交给page.locator(selector).click()走确定性的 Playwright 式路径执行。agent —— 交给代理自主完成。当任务步骤多、路径不确定时比如「滚动到页面底部点 Leaderboard告诉我第一名是谁」可以直接创建一个 agent给它一句指令让它自己规划步骤、操作页面、返回结果。下面这张图展示的就是一个浏览器代理接到提问后自动操作的完整过程。选择建议很简单步骤固定、追求确定性就用actobserve要取数就用extract任务开放、步骤动态才上agent。能不用 agent 就不用token 成本和执行时间都会更可控。生产环境才关心的几件事如果你的脚本只是个人跑一跑前面的用法就够用了要进生产Stagehand 还准备了几块基础设施。可观测性官方支持与 OpenTelemetry 及 Browserbase 遥测平台打通每一次 extract、act、observe 的输入输出都会记录成轨迹出问题时能回放具体哪一步、在哪页出错。成本与缓存同样页面的重复请求可以直接命中缓存packages/docs/v4/best-practices/caching.mdx 和 cost-optimization.mdx 里讲得很细。回归测试仓库自带的 packages/evals/ 是一套评测框架内置 WebVoyager、online-Mind2Web 等公开数据集可以批量验证代理在真实网站上的成功率。改完提示词或升级 SDK 后跑一轮回归比「手动点两下看看」可靠得多。什么样的任务适合交给它几个比较顺手的场景数据管道从价格页、榜单、招聘列表里定时抽取结构化数据extract zod schema 直接产出入库格式。表单与多步骤流程注册、下单、申请这类点击填写混合的流程用act串起来失败步骤靠自愈机制兜底。站点监控定时observe关键页面检查核心按钮和入口是否还在比选择器监控更抗改版。给 AI 应用加「手」如果你在做 agent 类产品Stagehand 可以作为它的浏览器执行层官方还提供了 MCP 集成方案文档在 packages/docs/v4/best-practices/mcp-integrations.mdx与 Claude Code 等编码代理的接入示例在 packages/integrations/ 下。接下来可以做的三件事克隆仓库git clone https://gitcode.com/GitHub_Trending/stag/stagehand照着根目录 README 用just工具链把三个 SDK 都跑一遍示例先建立对 API 的整体印象。精读 packages/docs/v4/first-steps/ 下的 installation 和 quickstart 两篇把本地浏览器localBrowser.launch和云端浏览器browserbase.launch两种模式都配通——前者免费但占本机资源后者适合要跑在服务器上的场景。把自己手头一个最烦的重复性网页任务拿出来先用observe试探页面结构再决定用act还是extract实现。跑通一个真实任务比读完所有文档更能建立手感。Stagehand 的定位一句话概括Playwright 是为测试写的Stagehand 是给代理写的。它没有替代底层浏览器控制而是给 AI 加了一层「看得懂页面、修得好动作」的接口让自动化脚本从「写一次修一年」变成「说一句话就行」。【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考