Stagehand Claude Agent 集成指南:用 Claude Agent SDK 与 MCP Facade 构建浏览器 Agent

原创2026-09-11 22:35:472,211 阅读
文章标签:人工智能AI Agent浏览器控制GUI 自动化MCP 服务工具调用AI 应用Agent 评测AI 评测网页爬虫

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 字段):

  1. code(JavaScript 工作流):在 Stagehand 浏览器扩展的 service worker 中执行模型编写的 JavaScript。代码通过 FACADE_PRELUDE + 用户代码 + FACADE_EPILOGUE 拼装成批处理回调,经 stagehand.experimentalBatch 注入浏览器端执行(见 tools.ts)。前置代码中 createPlaywrightCompatRuntime 会为代码提供 page / context / browser 等 Playwright 形状的 API,因此 Agent 可以直接写 await page.goto("...");
  2. 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 的安全章节可以概括为三层防线:

  1. 代码执行位置:run 工具执行的是模型编写的 JavaScript,但它运行在 Stagehand 浏览器扩展的 service worker 内(浏览器侧),而不是你的宿主机上。从 tools.ts 的 FACADE_PRELUDE 可以看到,代码被拼入 experimentalBatch 回调并注入浏览器扩展执行,宿主机只负责调度与收发结果——这本身就是一道强隔离。

  2. 推荐隔离边界:Browserbase 云浏览器:当使用 Browserbase 作为后端时,"特权执行环境"是一个一次性(disposable)的云端浏览器。即使模型写出了恶意或错误代码,其影响范围也被限制在可随时销毁的隔离容器内,不会触碰本地文件系统与本地网络。

  3. 环境变量白名单:SDK 示例通过 buildAllowlistedEnv() 只向 facade 服务器透传 STAGEHAND_* / BROWSERBASE_* 前缀的变量。因此你的 Anthropic 凭证永远不会到达浏览器会话。stdio 服务器侧还有第二重防御:sanitizeErrorMessage 会在回传错误信息前对 apiKey / token / sk-* / bb_live_* / Google AIza* / Bearer 等敏感串做脱敏替换,防止密钥经错误消息泄露到 Agent 上下文中。

此外,stdio 服务器对生命周期管理也很细致:SIGINT / SIGTERM / stdin 关闭都会触发优雅关闭,等待资源释放并关闭 Stagehand 与浏览器实例(stdio-server.ts)。


八、进一步探索

仓库还提供面向 Codex、Eve、Mastra、Vercel AI SDK、CrewAI、Pi 等其他框架的同构集成(见 packages/integrations/ 目录),它们共享同一套 FACADE_TOOLS 与 FACADE_AGENT_INSTRUCTIONS,掌握了本文的契约与安全模型即可触类旁通。

登录后查看全文
stagehand