Stagehand 浏览器 Agent SDK 完整指南：用 3 个自然语言 API 让 AI 接管网页操作-开发者社区

Stagehand 浏览器 Agent SDK 完整指南：用 3 个自然语言 API 让 AI 接管网页操作

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

如果你写过网页自动化脚本，大概率经历过这样的场景：页面改版后某个按钮换了个 id，跑了几百行的脚本全部失效；或者你想让大模型直接"帮点一下"，却发现它连元素在哪儿都找不到。传统浏览器驱动（如 Playwright）是为人工写测试用例设计的，而 AI Agent 需要的是另一种接口。

项目定位：为浏览器 Agent 而生的 SDK

Stagehand 把自己定义为 "The SDK For Browser Agents"——它是 Browserbase 团队开发的浏览器 Agent 开发工具包（SDK 即 Software Development Kit，可理解为封装好的功能库），目标是让 AI 以更少的 token、更低的延迟、更强的容错能力操作网页。它提供 TypeScript、Python、Go 三套语言 SDK，底层通过 Chrome DevTools Protocol 驱动浏览器，无需依赖 Playwright。

Stagehand 浏览器 Agent SDK 在 Web 应用中的运行示意

它和传统方案的核心区别有三点：

自愈动作：act、observe、extract用自然语言驱动，当网站结构变化时自动重新推断动作目标；
省 token：通过修剪后的可访问性树（页面的"精简大纲"）向模型提供页面上下文；
贴近浏览器运行：以浏览器扩展形式驻留在页面侧，减少往返延迟。

拆解三大核心能力

1. act()：用一句话执行网页操作

不需要写选择器，直接告诉它要做什么：

await stagehand.act("click the add to cart button");

act接收一句自然语言指令，模型会推断目标元素并完成操作。更妙的是，它还能接收observe()返回的现成动作直接重放，此时不经过任何模型推理，执行是确定性的。开启selfHeal后，当记录的选择器失效，它会自动重新推断。详见 act 文档。

2. extract()：把页面变成结构化数据

从网页抓数据最头疼的是页面结构千差万别。extract让你用 schema 定义想要的"输出形状"，Stagehand 会校验结果后再返回，拿到的数据天然带类型：

const { data } = await stagehand.extract( "extract the name of the repository", z.object({ name: z.string() }), );

TypeScript 用 Zod 描述结构，Python 用 Pydantic 模型，Go 则直接由类型参数推导 JSON Schema。详见 extract 文档与示例源码 packages/sdk-ts/examples/extract.ts。

3. observe()：先侦察，再行动

observe()扫描当前页面，返回一组"可执行的动作"（含元素选择器）。它适合在动手前规划多步流程、校验元素是否还存在，或把动作缓存起来以跳过后续模型调用：

const { data: actions } = await stagehand.observe("find the login form");

详见 observe 文档。

快速开始：环境、安装与密钥

环境要求：Node.js ≥ 22.18、Python ≥ 3.11 或 Go ≥ 1.26（三选一，与你的语言栈一致即可）；
本地跑需要已安装 Chrome；用 Browserbase 云浏览器则无需本地浏览器。

安装依赖并配置 Browserbase API 密钥（在 Browserbase 控制台申请）：

pnpm add @browserbasehq/stagehand zod # Python: pip install stagehand export BROWSERBASE_API_KEY=your_api_key

注意 Stagehand 不会替你读环境变量，密钥需要在自己的代码里取出并显式传入。未配置模型时，Model Gateway 会自动为每次推理挑选并鉴权模型，因此连模型厂商密钥都可以省掉。完整说明见安装文档。

第一个可运行的自动化

下面的最小示例串联了三大能力：启动浏览器、打开页面、执行点击、提取结构化内容。运行后可观察到 Agent 在真实页面上的完整动作：

Stagehand 浏览器自动化 Agent 执行演示

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 }); const [page] = await browser.context.pages(); await page.goto("https://stagehand.dev"); await stagehand.act("Click the 'Evals' button."); const { data } = await stagehand.extract( "Extract the value proposition from the page.", z.object({ valueProposition: z.string() }), ); console.log(data.valueProposition);

完整版本见 quickstart 文档，本地开发时可把browserbase.launch()换成localBrowser.launch()，直接驱动本机 Chrome。

组合场景：确定性 + 自愈的混合玩法

单独使用任一能力都够，但组合起来才体现设计意图。一个典型的稳健模式是：先用observe()侦察并锁定动作，再用传统 Playwright 风格定位器执行——既保留了 AI 的灵活性，又保留了确定性执行：

const { data: actions } = await stagehand.observe("find the latest PR link"); await page.locator(actions[0].selector).click();

计划-执行分离：observe的结果可缓存，重复运行时零模型调用（见 caching 最佳实践）；
复杂页面结构：原生支持跨进程 iframe 与封闭 Shadow DOM 的深层定位；
批量命令：batch一次提交多个操作，减少往返；
可观测性：内置 OpenTelemetry 支持，每一步操作都有迹可循。

Stagehand 浏览器 Agent 的可观测性追踪演示

进阶与生态集成

多语言同构：同一套能力在 Python 中同样简洁：

from stagehand import Stagehand, browserbase browser = await browserbase.launch(api_key="...") stagehand = await Stagehand.create(browser=browser) await stagehand.act("click the add to cart button")

Python 源码位于 packages/sdk-python/src/stagehand/，Go SDK 位于 packages/sdk-go/。

Agent 框架集成：官方为 Claude Code、Codex、CrewAI、Deep Agents、Mastra、Pi、Vercel AI SDK 等提供统一适配器，每个集成都暴露run/snapshot/screenshot三个工具，Agent 负责决策，Stagehand 负责管理浏览器会话。详见 integrations 总览。

评估与持续改进：仓库自带一套评测框架，内置 WebVoyager、Mind2Web 等基准任务，可量化你的 Agent 在真实任务上的成功率与成本：

Stagehand 内置 Evals 评测框架的任务运行结果

其他值得关注的方向：速度优化、成本优化、模型与密钥配置、部署建议。