Stagehand Claude Agent 集成指南:用 Claude Agent SDK 与 MCP Facade 构建浏览器 Agent
Stagehand Claude Agent 集成指南:用 Claude Agent SDK 与 MCP Facade 构建浏览器 Agent
导读
本文基于 stagehand 仓库中 packages/integrations/claude-code/README.md 及其配套源码,讲解如何将 Claude 智能体(Agent)与 Stagehand 的浏览器自动化能力对接:通过 @anthropic-ai/claude-agent-sdk 以编程方式嵌入 Claude Agent,并把 Stagehand 的 Facade(run / snapshot / screenshot 三个工具)以 stdio MCP 服务器的形式挂载给 Agent。读完本文,你将掌握两种接入方式(SDK 编程式嵌入、Claude Code CLI 的 .mcp.json 项目级配置)、完整的环境变量配置、安全模型,以及 Facade 底层三个工具的契约与实现原理。
该示例是一个"可运行的完整范例"(runnable example):安装依赖、导出密钥、一行命令即可让 Claude Agent 驱动浏览器执行任务。
一、整体架构:Claude Agent + Stagehand Facade over MCP/stdio
整个集成方案的核心思路是双向接线:
- 一侧是 Claude 智能体:由
@anthropic-ai/claude-agent-sdk的query()启动,负责理解用户指令并决定调用哪些工具; - 另一侧是 Stagehand Facade:一个把 Stagehand 的浏览器能力包装成三个 MCP 工具的 stdio 服务器,通过标准 MCP 协议与 Agent 通信;
- 中间是 MCP/stdio 通道:Agent 侧的 SDK 以
mcpServers配置启动一个子进程(即 facade 的 stdio 服务器),子进程通过标准输入输出与 Agent 交换 JSON-RPC 消息。
从 stdio-server.ts 的源码可以看到,服务器基于 @modelcontextprotocol/sdk 的 McpServer + StdioServerTransport 构建,并注册了三个工具:run、snapshot、screenshot。Agent 每调用一次工具,都会通过 tools/call 请求到达该服务器,再由 StagehandFacadeTools 转译为对浏览器实例的真实操作。
注意:这个示例属于"Facade"风格——把浏览器能力收敛为三个固定的、面向 Agent 的工具,与完整的 Stagehand MCP 服务器(tools 更丰富)是两套不同的集成路径,本文聚焦前者。
二、环境准备与构建
2.1 版本要求
示例包在 package.json 中声明了运行时约束:
"engines": {
"node": ">=24"
}
因此需要 Node.js 24 或更高版本。包的脚本定义如下:
"scripts": {
"start": "node src/agent.ts",
"test": "pnpm -w exec turbo run build --filter @browserbasehq/stagehand-integrations && vitest run",
"test:unit": "vitest run",
"typecheck": "tsc --noEmit"
}
2.2 构建 integrations 包
在仓库根目录执行(README 原样保留的命令):
pnpm install
pnpm exec turbo run build --filter @browserbasehq/stagehand-integrations
第一步安装整个 pnpm workspace 的依赖;第二步通过 turbo 单独构建 @browserbasehq/stagehand-integrations 包。之所以必须显式构建,是因为 facade 的 stdio 服务器入口(facade/stdio-server)要作为可执行子进程被拉起,而其产物需要先生成。构建成功后,产物会出现在 packages/integrations/core/dist/facade/ 下(例如 .mcp.json 中引用的 stdio-server.mjs)。
2.3 导出密钥
export ANTHROPIC_API_KEY=sk-ant-...
export BROWSERBASE_API_KEY=bb_live_...
ANTHROPIC_API_KEY:Claude Agent SDK 的凭证,用于 Agent 本身调用 Claude 模型;BROWSERBASE_API_KEY:Browserbase 云浏览器的凭证。README 明确说明 Browserbase 是默认且推荐的浏览器后端——这是安全模型的关键一环,详见第五节。
三、方式一:通过 Claude Agent SDK 编程式嵌入(推荐)
3.1 一行命令运行
构建完成后,在仓库根目录执行:
pnpm --filter @browserbasehq/stagehand-integrations-example-claude-code-facade start "Open https://example.com, snapshot it, and report the heading citing the snapshot ID."
命令由两部分组成:pnpm --filter <包名> start 选中示例包并运行其 start 脚本(即 node src/agent.ts),后面的引号内是交给 Agent 的指令。示例指令演示了完整闭环:打开页面 → 调用 snapshot 获取可访问性树 → 依据快照中的元素 ID 汇报标题。
3.2 入口实现剖析
入口 src/agent.ts 是理解整个接线的关键,核心逻辑如下:
import { query } from "@anthropic-ai/claude-agent-sdk";
import {
FACADE_AGENT_INSTRUCTIONS,
FACADE_TOOLS,
} from "@browserbasehq/stagehand-integrations/facade";
export const STAGEHAND_TOOL_NAMES = FACADE_TOOLS.map((tool) => `mcp__stagehand__${tool.name}`);
// 解析出 stdio 服务器入口的绝对路径
const serverPath = fileURLToPath(
import.meta.resolve("@browserbasehq/stagehand-integrations/facade/stdio-server"),
);
const result = query({
prompt: instruction,
options: {
model: process.env.CLAUDE_STAGEHAND_MODEL ?? "claude-sonnet-5",
maxTurns: 20,
systemPrompt: FACADE_AGENT_INSTRUCTIONS,
mcpServers: {
stagehand: {
command: process.execPath,
args: [serverPath],
env: buildAllowlistedEnv(),
},
},
allowedTools: STAGEHAND_TOOL_NAMES,
canUseTool: async (toolName) =>
toolName.startsWith("mcp__stagehand__")
? { behavior: "allow", updatedInput: undefined }
: { behavior: "deny", message: "Only stagehand browser tools are permitted." },
},
});
逐项说明:
| 配置项 | 作用 | 源码依据 |
|---|---|---|
prompt |
用户指令,来自命令行参数(支持 -- 分隔符后传参) |
agent.ts |
model |
Agent 使用的模型,默认 claude-sonnet-5,可用 CLAUDE_STAGEHAND_MODEL 覆盖 |
agent.ts |
maxTurns |
最大推理轮次,示例固定为 20,防止失控循环 | agent.ts |
systemPrompt |
直接复用 facade 包导出的规范指令 FACADE_AGENT_INSTRUCTIONS |
agent.ts |
mcpServers |
以当前 Node 可执行文件拉起 facade stdio 服务器,并通过 buildAllowlistedEnv() 传入白名单环境变量 |
agent.ts |
allowedTools |
显式只允许三个 mcp__stagehand__* 工具 |
agent.ts |
canUseTool |
运行时兜底:凡非 mcp__stagehand__ 前缀的工具一律拒绝 |
agent.ts |
allowedTools 与 canUseTool 的双重限制是刻意设计:无头(headless)运行中,任何悬而未决的权限提示都会导致流程挂死,所以直接"只允许 stagehand 工具、拒绝其余一切"。
STAGEHAND_TOOL_NAMES 由 FACADE_TOOLS 映射而来,三个工具名在运行时呈现为 mcp__stagehand__run、mcp__stagehand__snapshot、mcp__stagehand__screenshot。这一映射关系被测试 agent.test.ts 锁定:
it("allows exactly the namespaced facade tools", () => {
const expected = FACADE_TOOLS.map((tool) => `mcp__stagehand__${tool.name}`).sort();
expect([...STAGEHAND_TOOL_NAMES].sort()).toEqual(expected);
});
Agent 的流式结果按 message.type === "result" 且 subtype === "success" 判定为成功并输出最终结果;main() 通过 import.meta.main 判断是否作为入口直接执行,失败时由 handleFailure 输出错误并置退出码为 1。
3.3 环境变量白名单
src/env.ts 实现了一个非常关键的安全函数 buildAllowlistedEnv():
export function buildAllowlistedEnv(): Record<string, string> {
const env: Record<string, string> = {};
for (const [key, value] of Object.entries(process.env)) {
if (/^(STAGEHAND_|BROWSERBASE_)/.test(key) && value) {
env[key] = value;
}
}
return env;
}
只有键名以 STAGEHAND_ 或 BROWSERBASE_ 开头的主机环境变量才会被透传给 facade 服务器子进程。测试同样覆盖了这一点:
it("allowlist excludes non-STAGEHAND/BROWSERBASE host vars", () => {
process.env.STAGEHAND_BROWSER = "local";
process.env.NOT_ALLOWLISTED_SECRET = "must-not-cross";
// 断言 STAGEHAND_BROWSER 会进入白名单,而 NOT_ALLOWLISTED_SECRET 不会
});
这正是 README"安全模型"一节的技术落点:你的 Anthropic 凭证永远不会被转交给浏览器会话,因为 ANTHROPIC_API_KEY 不在白名单前缀之列。
四、环境变量速查表
README 给出了四个核心变量,结合 facade 的配置解析源码 config.ts 可进一步明确取值范围与行为:
| 变量 | 用途 | 默认值 / 取值约束 | 行为细节(源码佐证) |
|---|---|---|---|
STAGEHAND_BROWSER |
选择浏览器后端 | 未设置时:若存在 BROWSERBASE_API_KEY 则用 browserbase,否则用 local |
只接受 local / browserbase,其他值抛 StagehandFacadeConfigError |
BROWSERBASE_API_KEY |
Browserbase 会话凭证 | 无默认值 | 当后端为 browserbase 时必须提供,否则直接报错;可配 BROWSERBASE_PROJECT_ID |
CLAUDE_STAGEHAND_MODEL |
Agent 使用的模型 | claude-sonnet-5 |
仅在 SDK 方式中生效,作为 query() 的 model 选项 |
ANTHROPIC_API_KEY |
Claude Agent SDK 凭证 | 无默认值 | 仅供 Agent 调用模型,永远不进入浏览器会话 |
此外,facade 服务器本身还会读取一组 STAGEHAND_* 环境变量来配置 Stagehand 的模型(见 config.ts):
STAGEHAND_MODEL_NAME:Stagehand 内部使用的模型名。未设置时,若检测到GOOGLE_GENERATIVE_AI_API_KEY/GEMINI_API_KEY/GOOGLE_API_KEY任一 Google 密钥,则推断为google/gemini-3.6-flash;STAGEHAND_MODEL_API_KEY:显式模型密钥。注意:设置了它却未设置STAGEHAND_MODEL_NAME会被拒绝,因为缺少模型名无法推导 provider;- provider 密钥还可按惯例从
OPENAI_API_KEY、ANTHROPIC_API_KEY、GROQ_API_KEY、CEREBRAS_API_KEY等变量中推断; - 当 provider 为 anthropic 时,会自动附加
anthropic-dangerous-direct-browser-access: true请求头(这是 Anthropic 针对浏览器工具访问的显式授权头)。
local 后端的启动参数固定为 { headless: false }——即本地运行会弹出可见的浏览器窗口,方便调试。
五、Facade 三工具契约:run / snapshot / screenshot
无论 Agent 通过 SDK 还是 CLI 接入,最终执行的工具面完全相同。工具定义位于 contract.ts,统一由 FACADE_TOOLS 导出:
export const FACADE_TOOLS = [
{ name: "run", description: RUN_TOOL_DESCRIPTION, inputSchema: RUN_INPUT_SCHEMA },
{ name: "snapshot", description: SNAPSHOT_TOOL_DESCRIPTION, inputSchema: SNAPSHOT_INPUT_SCHEMA },
{ name: "screenshot", description: SCREENSHOT_TOOL_DESCRIPTION, inputSchema: SCREENSHOT_INPUT_SCHEMA },
];
5.1 snapshot:生成可操作的可访问性快照
- 输入:
{ includeIframes?: boolean },默认true; - 行为:抓取活动页面的 Stagehand 可访问性树(accessibility tree),并把其中的元素 ID(形如
1-42的括号化 ID)映射到 XPath,缓存为快照状态。README 的示例指令中"report the heading citing the snapshot ID"正是指这段流程。
5.2 run:执行代码或动作批
run 是能力最强的工具,支持两种互斥输入(由 CodeModeRunInputSchema 的 .refine 在运行时强制"二选一",且显式禁止 kind / ref 字段):
code(JavaScript 工作流):在 Stagehand 浏览器扩展的 service worker 中执行模型编写的 JavaScript。代码通过FACADE_PRELUDE+ 用户代码 +FACADE_EPILOGUE拼装成批处理回调,经stagehand.experimentalBatch注入浏览器端执行(见 tools.ts)。前置代码中createPlaywrightCompatRuntime会为代码提供page/context/browser等 Playwright 形状的 API,因此 Agent 可以直接写await page.goto("...");actions(快照动作批):基于最近一次snapshot返回的元素 ID,执行click、hover、fill、type、press、select六种操作。执行前会做三重校验:无快照时报NO_HYDRATED_SNAPSHOT_ERROR;页面在快照后发生导航时报NAVIGATED_SNAPSHOT_ERROR;ID 失效时报staleSnapshotIdError。因此 snapshot 后若页面发生导航,必须重新 snapshot——这也是FACADE_AGENT_INSTRUCTIONS中明确要求的 Agent 行为。
所有工具调用通过内部的 enqueue 串行队列排队执行(tools.ts),保证对浏览器的操作不会并发交错;每次 run 与动作批执行都有 60 秒超时。
5.3 screenshot:可视化检查
- 输入:
{ fullPage?: boolean; type?: "png" | "jpeg"; quality?: number }; - 输出:base64 编码的图片数据与 MIME 类型(
image/png或image/jpeg); - 细节:
quality仅对 JPEG 生效且会取整;对于尺寸受限的 MCP 客户端,契约描述推荐{"type":"jpeg","quality":40,"fullPage":false}。stdio 服务器还会按启动参数解析 base64 预算,必要时自动降级压缩以适配传输(见 stdio-server.ts)。
5.4 规范系统提示词
Facade 的 Agent 指令统一来自 contract.ts 中的 FACADE_AGENT_INSTRUCTIONS,其核心约束是:
- 你只控制一个持久浏览器,工具只有三个:
snapshot、run、screenshot; - 简单交互用 snapshot 动作,多步骤工作流用
run代码; run的code与actions二选一,动作必须用op与id,绝不使用kind/ref;- 快照 ID 仅对活动页面的最近一次快照有效,导航后或 ID 失效需重新 snapshot;
- 不要另起浏览器。
该提示词是跨框架共享的"规范版本"——README 强调它从 facade 包导入,是为了让 Eve、Vercel AI SDK、deepagents 等宿主示例保持 Agent 引导语完全一致。
六、方式二:连接交互式 Claude Code CLI
如果不想用 SDK,而是希望直接复用已经安装的 claude 命令行工具,本目录下的项目级 .mcp.json 就是全部所需配置:
{
"mcpServers": {
"stagehand": {
"command": "node",
"args": ["../core/dist/facade/stdio-server.mjs"]
}
}
}
Claude Code 会自动继承你 shell 的环境变量,因此上一节导出的密钥就是全部配置,无需在 JSON 里重复写入。
6.1 交互模式
cd packages/integrations/claude-code
claude
进入交互式 REPL 后,Agent 即可通过 mcp__stagehand__* 三个工具操控浏览器。
6.2 无头一次性模式
claude -p "your instruction" --mcp-config .mcp.json --allowedTools "mcp__stagehand__run,mcp__stagehand__snapshot,mcp__stagehand__screenshot"
参数说明:
| 参数 | 作用 |
|---|---|
-p |
以一次性(无头)模式运行并直接给出指令 |
--mcp-config .mcp.json |
显式指定本项目的 MCP 服务器配置 |
--allowedTools |
白名单限定的工具列表,与 SDK 方式的 allowedTools 语义一致 |
注意 .mcp.json 中的 args 使用的是相对路径 ../core/dist/facade/stdio-server.mjs,因此该命令必须在 packages/integrations/claude-code 目录内(或能正确解析该相对路径的位置)执行。
七、安全模型:三层隔离边界
README 的安全章节可以概括为三层防线:
-
代码执行位置:
run工具执行的是模型编写的 JavaScript,但它运行在 Stagehand 浏览器扩展的 service worker 内(浏览器侧),而不是你的宿主机上。从 tools.ts 的FACADE_PRELUDE可以看到,代码被拼入experimentalBatch回调并注入浏览器扩展执行,宿主机只负责调度与收发结果——这本身就是一道强隔离。 -
推荐隔离边界:Browserbase 云浏览器:当使用 Browserbase 作为后端时,"特权执行环境"是一个一次性(disposable)的云端浏览器。即使模型写出了恶意或错误代码,其影响范围也被限制在可随时销毁的隔离容器内,不会触碰本地文件系统与本地网络。
-
环境变量白名单:SDK 示例通过
buildAllowlistedEnv()只向 facade 服务器透传STAGEHAND_*/BROWSERBASE_*前缀的变量。因此你的 Anthropic 凭证永远不会到达浏览器会话。stdio 服务器侧还有第二重防御:sanitizeErrorMessage 会在回传错误信息前对apiKey/token/sk-*/bb_live_*/ GoogleAIza*/Bearer等敏感串做脱敏替换,防止密钥经错误消息泄露到 Agent 上下文中。
此外,stdio 服务器对生命周期管理也很细致:SIGINT / SIGTERM / stdin 关闭都会触发优雅关闭,等待资源释放并关闭 Stagehand 与浏览器实例(stdio-server.ts)。
八、进一步探索
- 集成示例与入口:packages/integrations/claude-code/(
src/agent.ts、src/env.ts、tests/agent.test.ts、.mcp.json) - Facade 工具实现:packages/integrations/core/src/facade/tools.ts
- 工具契约与提示词:packages/integrations/core/src/facade/contract.ts
- 配置解析:packages/integrations/core/src/facade/config.ts
- stdio MCP 服务器:packages/integrations/core/src/facade/stdio-server.ts
- Facade 公共导出:packages/integrations/core/src/facade/index.ts
仓库还提供面向 Codex、Eve、Mastra、Vercel AI SDK、CrewAI、Pi 等其他框架的同构集成(见 packages/integrations/ 目录),它们共享同一套 FACADE_TOOLS 与 FACADE_AGENT_INSTRUCTIONS,掌握了本文的契约与安全模型即可触类旁通。