Stagehand TypeScript SDK 完全指南用 act、observe、extract 构建自愈式浏览器 Agent【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehandStagehand 是面向浏览器 Agent 的专用 SDK它把 Playwright 熟悉的 API 与「自愈式」自然语言原语act、observe、extract结合起来让 AI Agent 用更少的 Token 理解页面、在网站改版后自动恢复、并可靠地完成生产级自动化任务。本文以 packages/sdk-ts/README.md 为骨架结合 TypeScript SDK 源码packages/sdk-ts/src与仓库内 11 个官方示例完整讲解核心 API、浏览器驱动localBrowser / browserbase、模型配置、缓存与 WebMCP 等能力并给出从源码构建与运行示例的完整步骤。Stagehand 是什么为 Agent 而生的浏览器 SDK官方定位很直接Playwright was built for testing, Stagehand is built for agents.。Playwright 面向测试场景Stagehand 面向 Agent 场景。它提供了一套跨 TypeScript、Python、Go 三种语言的完整浏览器驱动——本篇文章聚焦其中的 TypeScript SDKnpm 包名browserbasehq/stagehand当前仓库版本为 4.0.2见 packages/sdk-ts/package.json。与直接调用 Playwright 或裸 CDP 相比Stagehand 的差异化能力集中体现在五点这也是仓库 README 明确定义的定位1. 熟悉的 APIAgent 可以直接使用你已经熟悉的 Playwright 风格方法goto、click、locator、screenshot。从 src/index.ts 的导出可以看到SDK 对外暴露了Page、Locator、BrowserContext、Response、BrowserClipboard等类底层通过 CDP 引擎与浏览器通信但使用体验与 Playwright 保持一致。2. Token 效率优先Stagehand 采用混合可访问性树裁剪hybrid accessibility tree trimming只把 Agent 理解页面真正需要的信息送入模型其余一概剔除。这意味着更少的 Token 消耗、更低的推理成本。3. 生产环境更快Stagehand 以浏览器扩展extension的形式运行在浏览器旁边压缩了 Agent 与页面之间的物理距离显著减少页面上所有操作的往返延迟。从 packages/extension 目录的结构可以印证扩展包含servicesactService、extractService、observeService、llmService、understudyCDP 与页面代理层等模块TS SDK 通过extensionAssets.ts加载这套扩展见 src/extensionAssets.ts。4. 自愈式原语act、observe、extract三个自然语言接口是 Stagehand 的灵魂当网站结构发生变化时Stagehand 能自动检测并用刷新后的定位方式重新执行动作这就是「自愈」self-healing的含义。5. Agent 需要的特性WebMCP页面主动向 Agent 注册工具、剪贴板支持、自愈动作、批量命令batch、面向嵌套 iframe 的深度定位器deep locators、以及 OTel 可观测性支持。快速开始一份可运行的完整示例README 给出了最精炼的入门示例它同时展示了 Browserbase 云浏览器 Stagehand 核心三原语的最短链路import { browserbase, Stagehand } from browserbasehq/stagehand; import { z } from zod/v4; const { BROWSERBASE_API_KEY, OPENAI_API_KEY } process.env; const browser await browserbase.launch({ apiKey: BROWSERBASE_API_KEY, }); const stagehand await Stagehand.create({ browser, model: { modelName: openai/gpt-5.4-mini, apiKey: OPENAI_API_KEY, }, }); // Stagehands CDP engine provides an optimized, low level interface to the browser built for automation const [page] await browser.context.pages(); await page.goto(https://github.com/browserbase); // Use act() to execute individual actions await stagehand.act(click on the stagehand repo); // Use observe() to see whats actionable on the page const { data: actions } await stagehand.observe(find the latest PR); // Use locators for deterministic Playwright-style actions await page.locator(actions[0].selector).click(); // Use extract() to get structured data from the page 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), }), );逐段拆解这段代码browserbase.launch负责在 Browserbase 云端创建一个带 Stagehand 扩展的浏览器会话它返回的browser对象具备.context属性用于拿到页面。Stagehand.create是 SDK 唯一的构造入口。从 src/stagehand.ts 源码可以看到create是一个静态异步工厂它先用 zod 校验入参随后通过claimStagehandBrowser认领浏览器句柄再建立RPCClient并发送stagehandInit初始化请求最后把BrowserContext挂载到浏览器句柄上。所有初始化都在一个带有超时截止时间withStagehandInitDeadline的流程中完成若初始化失败且无法确定原因还会自动关闭浏览器以防资源泄漏。browser.context.pages()拿到的是经过 Stagehand 扩展优化的 CDP 页面对象page.goto、page.locator().click()都是确定性deterministic操作。act/observe/extract是三个自然语言接口详见下一节。Python 与 Go 开发者可以在仓库中看到等价示例packages/sdk-python/README.md 与 packages/sdk-go/README.md。核心原语深度解析act / observe / extract这三个方法定义在 src/stagehand.ts 中它们共享同一个调用模式解析客户端选项 → 确定目标页面未显式传page时取当前活动页activePage()→ 通过RPCClient把指令发给扩展侧 → 返回结构化结果。async act(instruction: string, options?: StagehandClientActOptions): PromiseActResult; async observe(instruction?: string, options?: StagehandClientObserveOptions): PromiseObserveResult; async extractSchema extends z.ZodType(instruction: string, schema: Schema, options?: ...): PromiseExtractResultSchema;act执行单个动作act接收一句自然语言指令如 click on the stagehand repo由 LLM 将其解析为具体的浏览器动作并执行。从 src/stagehand.ts 可以看到它最终通过 RPC 方法stagehandAct发送pageId与instruction返回ActResult其中result.data.success表示动作是否成功、result.data.message携带失败原因。官方示例 examples/act.ts 演示了完整的校验逻辑const result await stagehand.act( Click the link that provides more information about Example Domain, ); console.log(JSON.stringify(result.data, null, 2)); if (!result.data.success) { throw new Error(act() failed: ${result.data.message}); }除了字符串指令act还接受结构化的Action类型支持对具体元素执行点击、输入、悬停、滚动等确定性操作。observe观察页面上可执行的动作observe返回页面上与指令相关的候选动作列表。README 示例中observe(find the latest PR)的返回结果里每个动作都带有selector字段可以直接交给page.locator(selector)执行——这就是「自然语言发现 确定性执行」的典型组合。其底层实现见 src/stagehand.tsobserve的指令参数是可选的不传指令时它列出页面上所有可交互元素传指令时只返回与该意图相关的动作。若页面没有匹配动作examples/observe.ts 中result.data.length 0即为空结果信号。extract从页面抽取结构化数据extract把自然语言指令 zod 模式schema转换为结构化 JSON 输出。它内部做了两件关键事见 src/stagehand.ts模式序列化z.toJSONSchema(resolvedSchema)把 zod schema 转成 JSON Schema再通过 RPC 传给扩展侧 LLM结果强校验拿到扩展侧返回的response.data后用resolvedSchema.parse(...)在客户端再次校验保证返回数据严格符合你声明的结构——类型安全在运行时依然有效。若省略 schema 参数SDK 会使用默认的DefaultExtractDataSchema返回未约束的结构化数据。examples/extract.ts 展示了最简用法const result await stagehand.extract( Extract the page heading and description, z.object({ heading: z.string(), description: z.string(), }), ); console.log(JSON.stringify(result.data, null, 2));另外act/observe/extract都支持locator、ignoreLocators与page三个扩展选项见 src/clientSchemas.tslocator把操作限定在某个定位器范围内ignoreLocators显式排除某些区域page指定非活动页作为目标。浏览器驱动localBrowser 与 browserbaseStagehand.create要求传入一个由 SDK 工厂创建的浏览器句柄。SDK 提供两个工厂localBrowser本地 Chrome与browserbaseBrowserbase 云浏览器二者定义在 src/browser/factories.ts入口导出在 src/index.tsexport { browserbase, localBrowser }。localBrowser.launch 完整参数表localBrowser.launch的选项由LocalBrowserLaunchOptionsSchema定义见 src/clientSchemas.ts全部可选参数类型说明headlessboolean是否无头运行Agent 场景通常设为true官方示例默认{ headless: true }executablePathstring自定义 Chrome/Chromium 可执行文件路径argsstring[]追加的浏览器启动参数portnumber调试端口userDataDirstring用户数据目录配合preserveUserDataDir控制是否保留preserveUserDataDirboolean关闭时是否保留用户数据目录devtoolsboolean是否打开 DevToolschromiumSandboxboolean是否启用 Chromium 沙箱ignoreDefaultArgsboolean \| string[]忽略默认启动参数proxy{ server, bypass?, username?, password? }代理配置localestring浏览器区域设置viewport{ width, height }视口尺寸deviceScaleFactornumber设备像素比hasTouchboolean是否模拟触屏ignoreHTTPSErrorsboolean是否忽略 HTTPS 证书错误downloadsPathstring下载目录路径acceptDownloadsboolean是否接受下载keepAliveboolean是否在关闭句柄时保活浏览器进程注意一个约束当acceptDownloads为true时downloadsPath必填否则launch会直接抛错该校验在 src/browser/factories.ts。此外localBrowser.connect支持通过cdpUrl连接一个已在运行、且已加载 Stagehand 扩展的浏览器extensionId可选指定。browserbase.launch 与 connectbrowserbase.launch需要apiKey必填与可选的baseUrl默认https://api.browserbase.com见DEFAULT_BROWSERBASE_URL。其余会话选项直接透传给 Browserbase SDK 的SessionCreateParams即你在 Browserbase 控制台创建会话时能看到的那套选项区域、代理、视口等。从源码看src/browser/factories.tsbrowserbase.launch会创建远程会话并基于 Browserbase 预加载的扩展建立连接。browserbase.connect则通过sessionId连接一个已存在的 Browserbase 会话。两者的选择逻辑很清晰本地开发 / 单元测试用localBrowser生产级、需要服务端缓存等能力时用browserbase——例如缓存示例 examples/caching.ts 顶部就明确注释 Server-side caching requires a Browserbase browser session.底层CDP 引擎Stagehand.create建立的RPCClient见 src/rpcClient.ts直接基于 CDPChrome DevTools Protocol工作。README 中有一句关键说明Stagehands CDP engine provides an optimized, low level interface to the browser built for automation。换句话说page.goto、locator.click这些确定性方法并非调用 Playwright而是走 Stagehand 自己实现的 CDP 引擎src/cdpClient.ts、src/page.ts、src/locator.ts这也是它能以扩展形式贴近浏览器、压低往返延迟的原因。模型配置与自定义 LLMStagehand.create的model字段有两种形态形态一内置模型配置即 README 示例中的写法——modelName如openai/gpt-5.4-mini加apiKey。协议侧由ModelConfigSchema定义见 packages/protocol/schemas.tsSDK 侧通过ModelConfigSchema校验后随初始化参数传给扩展。形态二客户端 LLM 回调ClientLLM。model.generate是一个本地实现的函数类型由ClientLLMSchema约束见 src/clientSchemas.ts签名是(params: LLMGenerateParams) PromiseLLMGenerateResult。该函数只在客户端运行、绝不跨 RPC 传输因此你可以接入任意 LLM 供应商。官方示例 examples/customLlm.ts 演示了如何用 OpenAI SDK 实现generateWithOpenAI解析params.systemPrompt、消息列表与responseFormatJSON Schema调用openai.responses.create后返回{ role, content, outputFormat, structuredContent, usage }结构的结果并回传 token 用量用于 Stagehand 的计量与缓存统计。const stagehand await Stagehand.create({ browser, model: { generate: generateWithOpenAI, }, });从 src/stagehand.ts 源码可以看到SDK 检测到model.generate存在时会把它注册为 RPC 方法llmGenerate的处理器——扩展侧的所有 LLM 请求都会回调到你的函数上。更多 Agent 能力缓存、WebMCP、批处理、剪贴板与文件上传仓库 packages/sdk-ts/examples 目录下共有 11 个官方示例除了act、observe、extract三个基础示例外其余示例覆盖了 README「Features agents need」一节提到的能力caching.ts服务端缓存通过extract的cache: { threshold: 1 }选项启用缓存。threshold表示结果被重复命中的次数门槛——设为 1 时第一次调用后第二次相同请求即命中缓存。结果元数据metadata.cache会报告命中/未命中原因以及节省的 Token 数CacheTokenSavings未启用缓存时该字段缺席。注意服务端缓存依赖 Browserbase 会话。webmcp.tsWebMCPWebMCP 允许网页主动向 Agent 注册工具。示例展示了完整调用链page.tools({ timeout: 5_000 })获取页面注册的工具 →tool.invoke({ input })发起调用 →invocation.result()取回结果const tools await page.tools({ timeout: 5_000 }); const calculateSum tools.find((tool) tool.name calculateSum); const invocation await calculateSum.invoke({ input: { a: 19, b: 23 } }); const result await invocation.result();SDK 侧类型为WebMCPTool与WebMCPInvocation见 src/webmcp.ts协议类型定义在 packages/protocol/types.ts。batch.ts批量命令stagehand.experimentalBatch(callback, input?, options?)把一段可序列化的 JavaScript 回调发送到浏览器侧批量执行。源码src/stagehand.ts会校验回调必须是可序列化函数拒绝[native code]、超时必须是正整数且不超过MAX_CALLBACK_BATCH_TIMEOUT_MS并支持options.page指定目标页面。clipboard / browserClipboardBrowserClipboard类src/browserClipboard.ts为 Agent 提供剪贴板读写能力。fileUpload.tsfileUpload模块src/fileUpload.ts导出FileInput/FilePayload类型用于向页面上传文件。pageEvents.ts订阅Page事件如 CDP 事件见PageCDPEvent、PageEventListener类型与 src/page.ts。modelGateway.ts / customLogging.ts分别演示模型网关接入与自定义日志logging配置支持level: debug|info|warn|error|off、format: pretty|json、onLog回调见 src/clientSchemas.ts。从 src/index.ts 的导出清单还可以看到完整公开类型面ObserveResult、ActResult、ExtractResult、CacheStatus、Variables、StagehandMetrics等其中CacheStatus用于区分缓存命中的建立阶段hit/miss/stale/disabled是判断缓存行为的依据。从源码构建与运行示例Stagehand 是一个 TypeScript、Python、Go 三语言 monorepo使用just驱动pnpm、uv与go三个工具链。完整构建流程git clone https://gitcode.com/GitHub_Trending/stag/stagehand.git cd stagehand just install just generate just buildjust install安装三种语言的依赖pnpm workspace uv go modulesjust generate生成各语言 SDK 的协议相关代码例如 Go 侧 scripts/generate.go 与 Python 侧 scripts/generate.py 所对应的生成流程just build构建各包产物。运行示例前需要准备 LLM 供应商的 API Key若使用 Browserbase 示例还需 Browserbase 凭证。把它们导出到环境变量export OPENAI_API_KEYyour-openai-api-key export BROWSERBASE_API_KEYyour-browserbase-api-key然后运行 packages/sdk-ts/examples 目录下的任意示例just example act # runs packages/sdk-ts/examples/act.tsjust example name会运行同名示例文件act、observe、extract、caching、customLlm、customLogging、batch、fileUpload、modelGateway、pageEvents、webmcp共 11 个。注意本地示例act/observe/extract等使用localBrowser.launch({ headless: true })不依赖 Browserbase而caching示例依赖BROWSERBASE_API_KEY。完整的三语言环境搭建见仓库 CONTRIBUTING.md。运行测试同样走 pnpm 工作区SDK 测试脚本定义在 packages/sdk-ts/package.jsonpnpm test/test:unit/test:browser测试代码位于 packages/sdk-ts/tests其中tests/integration覆盖了page.goto响应、locator 内容方法、剪贴板、文件上传、多标签页等真实浏览器行为。在仓库内继续深入快速上手文档packages/docs/v4/first-steps/quickstart.mdx、packages/docs/v4/first-steps/introduction.mdxSDK 参考手册packages/docs/v4/reference含stagehand、act、observe、extract、locator、page、clipboard、webmcp等TypeScript SDK 源码packages/sdk-ts/src核心入口 stagehand.ts、配置校验 clientSchemas.ts、浏览器工厂 browser/factories.ts扩展侧实现act/extract/observe 服务packages/extension/services协议定义与跨语言类型同步packages/protocoltypes.ts、schemas.ts、schema-registry.ts集成生态packages/integrationsClaude Code、Codex、CrewAI、DeepAgents、Eve、FX、Mastra、Pi、Vercel AI SDK 等适配器许可协议LICENSEMIT LicenseStagehand 为 Browserbase, Inc. 商标从「快速开始」里的一行Stagehand.create到扩展侧真实执行的act/extract/observe服务Stagehand 把「Agent 与浏览器交互」这件事拆解成了清晰的 CDP 引擎 自然语言原语 自愈定位三层结构。理解了这个分层无论是接入自有 LLM、接入云浏览器还是定位缓存命中问题你都能在源码与示例中找到对应的落点。【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考