Stagehand Agent 集成指南用 run / snapshot / screenshot 三个工具将持久浏览器接入任意 Agent 框架【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand本篇指南深入剖析 Stagehand 的 Agent 集成层packages/integrations/它把 Stagehand 的浏览器自动化能力收敛为run、snapshot、screenshot三个工具由一个持久浏览器提供支撑既能作为 stdio MCP 服务器被任意 MCP 客户端消费也能作为原生进程内工具直接绑定进 Agent 运行时。读完本文你将掌握三个工具的确切契约、两种消费形态的取舍、完整的环境变量配置以及 Claude Code、Codex、CrewAI、Deep Agents、Eve、fx、Mastra、Pi、Vercel AI SDK 共 9 类框架的具体接入方式。设计理念一套契约处处复用绝不重复定义Stagehand 集成层的核心思路用一个词概括就是facade门面向所有 Agent 框架暴露完全相同的工具面tool surface而不是为每个框架各写一套绑定逻辑。这一点在最顶层的 packages/integrations/README.md 中表述得非常明确工具契约工具描述、schema、运行时校验器、Agent 系统提示词只在core/中定义一次被其他所有地方导入绝不重复声明。这意味着无论你用的是 Claude Code、Codex、Mastra 还是 Vercel AI SDKAgent 看到的工具名、参数结构、JSON Schema 乃至系统提示词都是逐字节一致的。模型在任何一个框架中学会的交互方式例如{op:click,id:1-42}可以无缝迁移到另一个框架。契约的唯一权威出处是core/目录下的 contract.ts。这个文件刻意携带同一份契约的两份副本线缆契约wire contract手写的 JSON Schema 字面量通过tools/list原样广播给 MCP 客户端。它们必须手写因为op判别字段的const类型、逐属性的 guidance 描述在 zod 转 JSON Schema 时无法保留而.refine()干脆什么都不输出。这些措辞与参考契约逐字符锁定——模型就是对着这些描述被提示的。运行时校验器runtime validators文件底部的 zod schemaRefActionSchema、CodeModeRunInputSchema、SnapshotInputSchema、ScreenshotInputSchema负责在tools/call时把参数解析成类型化数据并强制执行线缆 schema 声明的约束例如code/actions的互斥由.refine保证。这份双重定义由 facade-contract.test.ts 守护——任何一侧的漂移都会被测试抓住。测试逐条锁定了三个工具的名字、描述里的关键措辞op (never kind)、id (never ref)、no separate navigate or start tool、6 种动作的属性集合与必填项以及CodeModeRunInputSchema的互斥语义code与actions恰好出现其一。从目录结构看core/包browserbasehq/stagehand-integrations还提供了stagehand-facadestdio MCP 可执行入口以及 code-mode MCP 宿主脚手架见 core/package.json 中的bin与exports字段。三个工具详解整个集成层只有三个工具定义在 contract.ts 的FACADE_TOOLS中。下面逐一拆解。run导航、JavaScript 工作流或快照动作三合一run是唯一能干活的工具。它的核心约束是code与actions必须恰好提供其一。导航没有单独的 navigate 或 start 工具——用await page.goto(https://example.com)完成跳转浏览器在首次工具调用时懒启动。codestring一段 JavaScript 工作流在一个 Playwright 形状的page、context、browser门面上执行。适合多步骤、需要条件判断的复杂流程。actionsarray一批基于最新快照 ID 的动作。每个动作必须使用op绝不能用kind和id绝不能用ref快照 ID 以括号字符串形式从快照中复制。6 种快照动作的完整 schema 如下id均为必填字符串动作 op额外参数说明click—点击元素hover—悬停元素fillvaluestring必填填充输入框typetextstring必填、delaynumber ≥ 0可选逐键输入可指定击键间隔presskeystring必填按键selectvaluesstring 或 string 数组必填下拉框选值工具描述中给出的参考示例是{actions:[{op:click,id:1-42}]}{actions:[{op:fill,id:2-14,value:Miami}]}{actions:[{op:select,id:3-9,values:Lowest price}]}有一个刻意的偏离值得一提线缆 schema 故意不带顶层oneOf: [{required:[code]},{required:[actions]}]因为基于 AI SDK 的 MCP 客户端Eve、Vercel AI SDK会拒绝带顶层 oneOf 的工具输入 schema导致每次run调用在客户端侧就失败。code/actions的互斥由描述文字声明并由CodeModeRunInputSchema的.refine在运行时兜底。从实现看tools.tsrun(code)会把你的代码拼进一段 prelude/epilogue 包裹的 AsyncFunction通过stagehand.experimentalBatch在页面上下文中执行超时 60 秒runActions则把每个动作的id查表解析为 XPath去除尾部文本节点拼装成xpath选择器后逐动作执行同样走experimentalBatch。动作执行器会把press实现为先点击、再按键把select映射为locator.selectOption并返回完成数。snapshot抓取无障碍树并水合元素 IDsnapshot抓取活动页面的 Stagehand 无障碍树accessibility tree并给其中的元素水合出带括号的显示 ID供后续run动作引用。每次调用都会替换活动页面的 ID 映射——快照 ID 只对最新一次快照有效。参数只有一个includeIframesboolean默认true决定是否包含 iframe 内容。snapshot的结果形态是格式化后的文本树。实现上snapshotNow它同时把{ url, xpathById }记入snapshotsByPage映射作为动作 ID → XPath 的查询表。这里引出了三个被测试逐字锁定的错误消息构成了快照 ID 的生命周期契约错误含义No hydrated snapshot exists for the active page; call snapshot first.还没给活动页面做过快照The active page navigated after its snapshot; call snapshot again.快照后页面发生了导航ID 映射已失效Snapshot ID ... is stale or not actionable; call snapshot again.某个 ID 已过期或不可操作screenshot查看页面渲染结果screenshot捕获活动页面的截图返回 MCP 图片块。参数fullPageboolean是否整页截图typepng | jpeg图片格式qualitynumber0–100JPEG 质量。CDP 只对 jpeg 接受 quality且只接受整数实现里会自动Math.round。工具描述建议尺寸受限的 MCP 客户端使用{type:jpeg,quality:40,fullPage:false}。截图传输预算机制针对 size-constrained 的 MCP 客户端stagehand-facade服务器支持--max-screenshot-base64-bytes启动参数至少 1024见 screenshot-transport.ts。在此模式下未指定截图参数时默认降级为 viewport JPEG、quality 40若生成图片超出预算按viewport JPEG quality 40 → 25 → 10逐级重试fullPage强制为 false显式指定的 quality 只降不升全部超限则返回一条小体积错误消息而不是发送一个会让 MCP 客户端切断连接的超大帧。对应行为被 facade-screenshot-transport.test.ts 完整覆盖包括显式 png 超限后依次重试 jpeg 40/25和显式 jpeg 20 超限后重试 20/10 且绝不提升质量两个典型场景。两种消费形态stdio MCP 服务器 与 原生进程内工具同一份契约有两种消费方式各有权衡。这是 README 的核心描述也被 Vercel AI SDK 示例的 README 明确对比过。形态一stdio MCP 服务器通用、零胶水core/包暴露stagehand-facade这个 bin入口为 stdio-server.ts。它以 MCP stdio 传输协议对外服务启动即注册run/snapshot/screenshot三个工具浏览器懒启动MCP 握手后并不会立即拉起浏览器首次工具调用时才创建Stagehand资源ensureResources惰性求值 Promise 缓存捕获SIGINT/SIGTERM/stdin 关闭优雅关闭 Stagehand 与浏览器错误消息统一经过sanitizeErrorMessage脱敏API keysk-、bb_、AIza、Bearer token 等模式会被打码后才返回给客户端。任何 MCP 能力的框架都可以直接消费它代价是一个子进程 一次 JSON-RPC 跳转。MCP 客户端侧与服务器无关所以无需 Stagehand 专属胶水。从 facade-server.test.ts 可以看到一个值得注意的细节服务器初始化后、浏览器启动前tools/list就应当返回与FACADE_TOOLS完全一致的工具列表对非法调用例如缺参数的run要返回isError且不崩溃并保持服务器可用ping正常。形态二原生进程内工具无桥接进程、框架专属StagehandFacadeToolstools.ts把同一套逻辑暴露为可直接调用的类方法run/runActions/snapshot/screenshot。Eve、Pi 这类没有外部进程工具挂载机制的框架或希望共享同一持久 Stagehand 会话的场景采用这种方式无 MCP 连接、无桥接进程但绑定代码是框架专属的。实现上值得注意的两个点串行队列所有操作通过内部 Promise 队列enqueue串行化保证共享一个持久浏览器的并发调用不会互相踩踏状态保持快照 ID 映射snapshotsByPage存活于类实例内——这正是 MCP/stdio 服务器模式下快照 ID 跨调用有效的原因也是 deepagents 示例强调必须用持久ClientSession、不要用默认无状态工具的原因无状态工具每次调用新建进程浏览器与快照 ID 都会丢失。如何选择维度MCP/stdio 服务器原生进程内工具框架适配任何 MCP 能力框架零胶水框架专属代码开销子进程 JSON-RPC 跳转无桥接进程会话服务器进程内持久宿主进程内持久典型场景Claude Code、Codex、CrewAI、Mastra、Vercel AI SDK、fxEve、Pi无 MCP 挂载配置与模型解析所有配置通过环境变量注入解析逻辑集中在 config.ts 的stagehandFacadeConfigFromEnv中由 facade-contract.test.ts 覆盖。核心变量环境变量作用默认行为STAGEHAND_BROWSER浏览器后端local或browserbase设置了BROWSERBASE_API_KEY时默认browserbase否则local非法值直接抛StagehandFacadeConfigErrorBROWSERBASE_API_KEYBrowserbase 会话凭证选 browserbase 后必填BROWSERBASE_PROJECT_IDBrowserbase 项目 ID可选随launchOptions透传STAGEHAND_MODEL_NAMEfacade 服务器使用的模型名未设置时若检测到 Google 凭证则默认google/gemini-3.6-flashSTAGEHAND_MODEL_API_KEY显式模型 API key未设置则按 provider 从环境推断设置 key 但未设模型名会报错模型 provider 的 API key 推断规则google→GOOGLE_GENERATIVE_AI_API_KEY/GEMINI_API_KEY/GOOGLE_API_KEYopenai→OPENAI_API_KEYanthropic→ANTHROPIC_API_KEYgroq→GROQ_API_KEYcerebras→CEREBRAS_API_KEY。另外anthropic 系模型会自动附加anthropic-dangerous-direct-browser-access: true请求头。浏览器选择逻辑的细节值得注意local 模式默认非 headless{ headless: false }测试断言锁定适合观察 Agent 操作browserbase 模式则把执行放到一次性云浏览器中。按框架接入9 个自包含示例packages/integrations/下每个示例都是独立项目安装依赖、导出BROWSERBASE_API_KEY、运行即可详见各自目录的 README。TypeScript 示例把core/作为 workspace 依赖消费Python 项目解析已发布的stagehand包。目录接入方式一句话说明core/—契约、StagehandFacadeTools、stagehand-facadestdio MCP bin、code-mode MCP 宿主脚手架claude-code/MCP/stdioSDK 编程式挂载 .mcp.jsonClaude Agent SDK 示例codex/MCP/stdioconfig 覆盖挂载 config.toml模板Codex SDK 示例crewai/MCP/stdiouv 项目Python CrewAI 示例deepagents/MCP/stdio 原生工具Python LangChain Deep Agents本地 stdio MCP 服务器 Managed Deep Agents 原生工具项目eve/原生工具defineTool绑定Eve 无外部进程工具挂载故原生绑定fx/MCP/stdio用户级 MCP 配置fx 通过~/.fx/mcp.json消费 facademastra/MCP/stdioMCPClientMastra 示例pi/原生工具extension 注册Pi 无内置 MCP扩展直接注册工具vercel-ai/MCP/stdiocreateMCPClientVercel AI SDK 示例构建前置步骤所有示例运行前先从仓库根目录构建core包确保dist入口存在pnpm install pnpm exec turbo run build --filter browserbasehq/stagehand-integrations各示例要求 Node.js 24 或更新版本。Claude Codepackages/integrations/claude-code同时提供两种形态Claude Agent SDK 编程式挂载把 facade 作为 stdio MCP 服务器挂进anthropic-ai/claude-agent-sdk一行启动export ANTHROPIC_API_KEYsk-ant-... export BROWSERBASE_API_KEYbb_live_... pnpm --filter browserbasehq/stagehand-integrations-example-claude-code-facade start Open https://example.com, snapshot it, and report the heading citing the snapshot ID.连接正在运行的 Claude Code CLI项目作用域的.mcp.json即可CLI 继承 shell 环境cd packages/integrations/claude-code claude -p your instruction --mcp-config .mcp.json --allowedTools mcp__stagehand__run,mcp__stagehand__snapshot,mcp__stagehand__screenshotAgent 被限制为只能用mcp__stagehand__*三个工具allowedTools加canUseTool守卫系统提示词直接导入core/的FACADE_AGENT_INSTRUCTIONS。变量CLAUDE_STAGEHAND_MODEL可覆盖 Agent 模型默认claude-sonnet-5。Codexpackages/integrations/codexcodex-sdk 没有进程内 MCP 挂载通过 config.toml 式配置提供 MCP 服务器与 evals 的 codex 测试夹具同机制export OPENAI_API_KEYsk-... export BROWSERBASE_API_KEYbb_live_... pnpm --filter browserbasehq/stagehand-integrations-example-codex-facade start Open https://example.com, snapshot it, and report the heading citing the snapshot ID.连接交互式 CLI 时把目录中的 config.toml 合并进~/.codex/config.tomlCodex 不在配置值中展开 shell 变量需粘贴真实 key或逐项-c传入。注意 SDK 的 config 覆盖与既有[mcp_servers]是合并而非替换需要隔离时用CODEX_HOME指向临时目录。CODEX_PATH_OVERRIDE可指向本地codex二进制。Codex 无原生轮次上限长任务会一直跑到模型完成。CrewAIpackages/integrations/crewaiPython通过crewai-toolsMCP 适配器的一个保留截图子类连接cd packages/integrations/crewai uv sync uv run pytest uv run python agent.py your instruction一个实用的坑CrewAI 的工具循环在此版本是纯文本的crewai-tools的 MCP 适配器会丢弃 MCP 图片块因此该示例把每张截图保存到临时文件并把路径返回给 Agent。CREWAI_MODEL默认openai/gpt-5.6-luna。Deep Agentspackages/integrations/deepagentsPython本地运行默认启动可见的本地 Chromeexport OPENAI_API_KEY... export DEEPAGENTS_MODELopenai:gpt-5.6-luna cd packages/integrations/deepagents uv run --project examples/local python examples/local/agent.py服务器端配置变量包括STAGEHAND_BROWSER默认local、STAGEHAND_HEADLESS默认false、STAGEHAND_START_URL、STAGEHAND_MODEL、STAGEHAND_RUN_TIMEOUT_MS默认 60000。Browserbase 模式默认 1280×720 视口。示例刻意使用持久 MCPClientSession——MultiServerMCPClient.get_tools()的无状态工具每次调用都会新建 stdio 进程丢失浏览器和快照 ID。Managed Deep Agents 示例examples/managed则用 Python Stagehand SDK 直接编写 LangChain 工具线程 ID 由ToolRuntime注入当前 LangGraph SDK 与 Stagehand 的websockets版本冲突通过锁定websockets15.0.1解决。Evepackages/integrations/eve原生工具Eve 没有外部进程工具挂载通过defineTool原生绑定三个工具共享持久会话export BROWSERBASE_API_KEYbb_live_... export OPENAI_API_KEYsk-... pnpm --filter browserbasehq/stagehand-integrations-example-eve-facade dev会话生命周期方面Browserbase 模式下创建一个keepAlive: true会话并把 ID 持久化到临时文件STAGEHAND_EVE_SESSION_FILE可覆盖路径进程重启时重连而非再造新会话等待复用期间会话持续运行计费直到被重连、从 dashboard/API 释放或到达项目超时。模型错误不会重置会话只有连接不健康时才重建。该示例为单会话设计同一进程内并发 Eve 会话会共享页面与登录态。fxpackages/integrations/fxfx 只从用户级~/.fx/mcp.json加载 MCP 服务器仓库级配置被刻意忽略把目录中的mcp.json合并进去并填入 checkout 的绝对路径即可。模板刻意不设environment块fx 在无块时透传完整 shell 环境前面导出的环境变量就是全部配置一旦设置该块PATH/HOME都会消失需显式重述。cd packages/integrations/fx fx ask --json Use the stagehand browser tools: open https://example.com, snapshot it, and report the heading citing the snapshot ID.必须在 fx 目录内运行AGENTS.md与skills/stagehand-facade技能教模型使用精确工具名mcp_stagehand_run/mcp_stagehand_snapshot/mcp_stagehand_screenshotfx v0.0.3 的mcp_search_tools对该服务器查不到结果无指引时运行会卡在工具发现阶段甚至退化成 shell 探索。.fx.json调大了max_tool_result_bytes页面快照超过 fx 64KB 默认值与max_agent_steps。模板以--max-screenshot-base64-bytes60000启动 facade避免超大截图帧触发 fx 断连。headless 运行需在~/.fx/settings.json预允许三个工具或使用--auto浏览器专用工作流还建议denyfx 的run_command防止模型把凭证 dump 进对话记录。Mastrapackages/integrations/mastra通过 Mastra 的MCPClient走 MCP/stdiopnpm --filter browserbasehq/stagehand-integrations-example-mastra-facade test pnpm --filter browserbasehq/stagehand-integrations-example-mastra-facade typecheck pnpm --filter browserbasehq/stagehand-integrations-example-mastra-facade start your instructionMASTRA_STAGEHAND_MODEL默认gpt-5.6-luna。子进程只接收STAGEHAND_*/BROWSERBASE_*变量加 MCP 传输的安全默认值HOME、PATH、SHELL、TERM、USER、LOGNAME宿主完整环境绝不转发。Pipackages/integrations/pi原生工具Pi 无内置 MCP本包是注册三个原生工具的 pi 扩展描述、校验、Agent 指引全部导入browserbasehq/stagehand-integrations/facadecd packages/integrations/pi pi -e ./extensions/stagehand.ts --no-session -p Use your browser tools: open https://example.com, snapshot it, and report the heading citing the snapshot ID. /dev/nullprint 模式读取管道 stdin务必/dev/null非交互运行不显示项目信任提示用-e或先-a信任项目。永久安装用pi install ./packages/integrations/pi。浏览器在首次工具调用时懒启动会话结束时关闭。Vercel AI SDKpackages/integrations/vercel-ai通过createMCPClient走 MCP/stdiopnpm --filter browserbasehq/stagehand-integrations-example-vercel-ai-facade test pnpm --filter browserbasehq/stagehand-integrations-example-vercel-ai-facade typecheck pnpm --filter browserbasehq/stagehand-integrations-example-vercel-ai-facade start your instructionAI_SDK_STAGEHAND_MODEL默认gpt-5.6-luna。OPENAI_API_KEY供宿主进程的 AI SDK Agent 模型使用既不转发也不在传输层继承。安全模型模型编写的代码在浏览器里跑所有示例的安全模型完全一致核心原则有四点run(code)的模型编写 JavaScript 在 Stagehand 浏览器扩展的 service worker 中执行——运行在浏览器侧绝不在你的机器上、绝不在宿主进程内。模型代码拿不到宿主进程的权限。Browserbase 是推荐的隔离边界特权执行环境是一次性云浏览器与宿主机物理隔离。环境变量白名单子进程只继承STAGEHAND_*/BROWSERBASE_*变量MCP 传输再补 PATH 等安全默认Agent 框架自己的模型凭证如ANTHROPIC_API_KEY、OPENAI_API_KEY永远不会到达浏览器会话。错误信息脱敏facade 服务器在返回错误前统一清洗 API key 形态的字符串sk-、bb_、AIza、Bearer 等见 stdio-server.ts 的sanitizeErrorMessage。宿主与浏览器的凭证分离是这套集成架构最值得借鉴的设计。契约校验与测试保障契约的稳定性由三层测试守护均在 core/tests 下facade-contract.test.ts锁定三个工具名与描述措辞、run 的 JSON Schema 结构含无顶层 oneOf的刻意偏离、6 种动作的属性/必填/additionalProperties: false、快照错误标点、code/actions互斥语义、本地浏览器默认非 headlessfacade-server.test.ts以真实 MCPClient连接构建后的 stdio 服务器验证tools/list精确返回FACADE_TOOLS、非法调用返回isError且服务器不崩溃可继续ping、screenshot 的 quality 类型校验facade-screenshot-transport.test.ts验证截图预算解析低于 1024 抛错、默认降级为 viewport JPEG quality 40、超限逐级重试且绝不提升显式质量、全部超限返回小错误。此外还有fx-integration.test.ts、mcp-runtime.test.ts、stdio-lifecycle.test.ts、stdio-server.test.ts分别守护 fx 配置场景、code-mode MCP 宿主与 stdio 生命周期。运行时规则测试rules/ast-grep/sdk-parity.test.ts 等则从另一维度约束 SDK 侧的一致性。总结Stagehand 集成层用三个工具 一个持久浏览器 一份契约的极简设计覆盖了从 MCP 通用消费到原生框架绑定的全部主流接入路径。记住几个关键心智模型接入任何框架都不再需要查文档导航没有独立工具run里await page.goto(...)即可浏览器首次调用时懒启动快照 ID 只对活动页面的最新快照有效导航后必须重新 snapshotrun只收code或actions之一动作只用op/id绝不写kind/ref契约唯一出处是core/模型系统提示词统一用FACADE_AGENT_INSTRUCTIONS模型编写的代码跑在浏览器侧用 Browserbase 做隔离边界凭证永不互通。【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考