用 Mastra 驱动 Stagehand 浏览器 Agent:基于 MCP/stdio 的 Facade 集成实战

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

用 Mastra 驱动 Stagehand 浏览器 Agent:基于 MCP/stdio 的 Facade 集成实战

导读

本文讲解 Stagehand 项目中 packages/integrations/mastra 这一官方示例的实现原理与实战用法:它通过 MCP/stdio 协议,把 Stagehand 的 Facade MCP 服务器暴露给 Mastra Agent,使其可以直接调用 run、snapshot、screenshot 三个浏览器工具。读完本文,你将掌握在 Mastra 中接入 Stagehand 浏览器能力的环境配置、运行命令、工具契约(Tool Contract)与安全边界,并能从源码层面理解这条集成链路每一步发生了什么。

一、集成架构:MCP/stdio 桥接 vs 进程内工具

本示例的本质,是把 Stagehand 的浏览器能力包装成一个独立的 MCP 服务器(Facade),再通过标准输入输出(stdio)协议与 Mastra Agent 进程通信。整个架构是一条清晰的调用链:

Mastra Agent (Node 宿主进程)
        │  MCP over stdio (JSON-RPC)
        ▼
Facade MCP Server(独立子进程,由宿主进程 spawn)
        │  Stagehand + 浏览器(extension service worker)
        ▼
浏览器页面

这条链路在 client.ts 中构建:createFacadeMCPClient 使用 @mastra/mcp 的 MCPClient,以 process.execPath(当前 Node 可执行文件)作为命令、以 facade 的 stdio-server 入口作为参数,spawn 一个子进程:

import { MCPClient } from "@mastra/mcp";
import { fileURLToPath } from "node:url";

export function createFacadeMCPClient(options: FacadeMCPClientOptions = {}) {
  // 先构建 @browserbasehq/stagehand-integrations,保证该 dist 入口存在
  const serverPath = fileURLToPath(
    import.meta.resolve("@browserbasehq/stagehand-integrations/facade/stdio-server"),
  );
  const env = buildAllowlistedEnv();
  Object.assign(env, options.env);
  return new MCPClient({
    id: "stagehand-facade-mastra-example",
    servers: {
      stagehand: {
        command: process.execPath,
        args: [serverPath],
        env,
      },
    },
  });
}

这种设计带来的取舍是明确的:

  • MCP/stdio 桥接方式(本示例采用的路线):任何具备 MCP 客户端能力的框架(不仅是 Mastra)都能消费同一份工具契约,无需为 Stagehand 写特定胶水代码;代价是多出一个子进程和一层 JSON-RPC 跳转。
  • 进程内原生工具方式:把同一份契约绑定为进程内的原生工具,共享一个持久的 Stagehand 会话,没有桥接进程,但绑定代码与框架强耦合。

换言之,Facade 起到"协议中性层"的作用——浏览器能力以统一契约对外暴露,接入方只需实现 MCP 客户端。

二、环境准备与构建

2.1 环境要求

  • Node.js 24 或更新版本:这是硬性要求,见 package.json 中的 "engines": { "node": ">=24" }。之所以要求这么高,是因为代码中直接使用了 import.meta.resolve 等现代 Node 特性来定位服务器入口。
  • pnpm + Turbo:仓库使用 pnpm workspace 组织,通过 turbo.json 编排构建任务。

2.2 先构建 integrations 包

Facade MCP 服务器实现位于独立的 @browserbasehq/stagehand-integrations 包(packages/integrations/core),Mastra 示例通过 import.meta.resolve("@browserbasehq/stagehand-integrations/facade/stdio-server") 解析其 dist 产物。因此运行前必须先从仓库根目录构建它:

pnpm exec turbo run build --filter @browserbasehq/stagehand-integrations

构建完成后,stdio-server 的 dist 入口才会存在,client.ts 中的 import.meta.resolve 才能解析成功。

2.3 环境变量配置

Facade 服务器与 Mastra Agent 分别消费不同的环境变量,二者职责不同,务必区分清楚:

变量 用途
STAGEHAND_BROWSER 浏览器后端。设置了 BROWSERBASE_API_KEY 时默认为 browserbase,否则默认为 local。
BROWSERBASE_API_KEY Browserbase API Key,用于云端浏览器。
STAGEHAND_MODEL_NAME Facade 服务器内部使用的模型名。
STAGEHAND_MODEL_API_KEY Facade 服务器模型的 API Key。
MASTRA_STAGEHAND_MODEL Mastra Agent 使用的模型,默认 gpt-5.6-luna。
OPENAI_API_KEY 宿主进程中 Mastra Agent 模型使用。不会转发给 Facade 服务器。

从 config.ts 的 stagehandFacadeConfigFromEnv 源码可以看到更细的规则:

  • STAGEHAND_BROWSER 只接受 local 或 browserbase,其他值会抛出 StagehandFacadeConfigError;未设置时,检测到 BROWSERBASE_API_KEY 则自动选择 browserbase,否则 local。
  • 若 STAGEHAND_BROWSER="browserbase" 但缺少 BROWSERBASE_API_KEY,会直接报错。
  • 若设置了 STAGEHAND_MODEL_API_KEY 却没有 STAGEHAND_MODEL_NAME,同样报错。
  • 未显式指定模型名时,若存在 GOOGLE_GENERATIVE_AI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY,会回退到 google/gemini-3.6-flash;模型 API Key 也会按 provider 从 OPENAI_API_KEY、ANTHROPIC_API_KEY、GROQ_API_KEY、CEREBRAS_API_KEY 等对应变量中推断。
  • local 浏览器默认以 headless: false(有头模式)启动,便于观察浏览器行为。

三、运行 Mastra + Stagehand Agent

构建完成后,在仓库根目录执行以下命令即可运行:

# 运行单元测试
pnpm --filter @browserbasehq/stagehand-integrations-example-mastra-facade test

# 类型检查
pnpm --filter @browserbasehq/stagehand-integrations-example-mastra-facade typecheck

# 真正启动 Agent 并传入指令
pnpm --filter @browserbasehq/stagehand-integrations-example-mastra-facade start "your instruction"

start 脚本对应 package.json 中的 "start": "node src/agent.ts",即直接用 Node 运行 TypeScript 入口。

3.1 Agent 启动流程

agent.ts 是示例的主入口,其执行逻辑清晰可读:

  1. 解析命令行参数:pnpm start "your instruction" 会把后续参数拼接为一条指令,未提供指令时报错退出;
  2. 调用 createFacadeMCPClient() 建立 MCP 连接;
  3. 通过 client.listToolsetsWithErrors() 发现工具集,若有错误或未发现 stagehand 工具集则抛错;
  4. 以 FACADE_AGENT_INSTRUCTIONS(从 @browserbasehq/stagehand-integrations/facade 导入)作为 Agent 指令,模型默认 openai(process.env.MASTRA_STAGEHAND_MODEL ?? "gpt-5.6-luna"),工具为 stagehand 工具集,创建 Mastra Agent:
const agent = new Agent({
  id: "stagehand-facade-agent",
  name: "Stagehand Facade Agent",
  instructions: FACADE_AGENT_INSTRUCTIONS,
  model: openai(process.env.MASTRA_STAGEHAND_MODEL ?? "gpt-5.6-luna"),
  tools,
});
  1. 调用 agent.generate(instruction, { maxSteps: 20 }) 让 Agent 最多执行 20 步工具调用并输出结果;
  2. finally 中调用 client.disconnect() 关闭 MCP 连接——这会让子进程与浏览器一并退出,避免资源泄漏。

值得注意:工具集发现后立即验证,而不是等到调用时才失败。listToolsetsWithErrors 返回的 errors 只要非空,Agent 就会在启动阶段报出"Failed to discover Stagehand facade tools"。

四、Facade 工具契约:run / snapshot / screenshot

Mastra Agent 实际消费的是 Facade 暴露的 三个工具,其契约(工具名、描述、输入 Schema)统一定义在 contract.ts,并由 stdio-server.ts 注册到 MCP 服务器上:

工具 用途
run 在持久化的 Stagehand 浏览器中浏览与自动化网站。可执行一段 JavaScript 工作流(如 await page.goto("https://example.com")),或根据最新快照的 ID 批量执行动作。code 与 actions 二者必须且只能提供其一。
snapshot 抓取活动页面的 Stagehand 无障碍树(accessibility tree),并为后续 run 动作挂载显示的 ID。每次调用都会替换活动页面的 ID 映射。
screenshot 截取活动页面截图。资源受限的 MCP 客户端建议使用视口 JPEG,如 {"type":"jpeg","quality":40,"fullPage":false}。

4.1 run 工具的两种输入模式

run 是核心工具,输入二选一:

  • code(字符串):一段在浏览器扩展 service worker 中执行的 JavaScript。例如导航无需单独的 navigate 工具,直接 await page.goto("https://example.com") 即可。
  • actions(数组):基于最新快照 ID 的动作批次。每个动作必须使用 "op"(绝不使用 "kind")和 "id"(绝不使用 "ref"),ID 从最新快照中按括号形式复制为字符串。支持六种操作:
操作 必填字段 说明
click id 点击快照元素
hover id 悬停快照元素
fill id, value 填充输入框
type id, text 按键输入,可选 delay(毫秒,≥0)
press id, key 点击后按键
select id, values 下拉选择,values 可为字符串或字符串数组

契约示例:{"actions":[{"op":"click","id":"1-42"}]}、{"actions":[{"op":"fill","id":"2-14","value":"Miami"}]}、{"actions":[{"op":"select","id":"3-9","values":"Lowest price"}]}。

4.2 契约的"双份"实现与测试保障

contract.ts 中同一份契约存在两份:

  • JSON Schema 字面量(wire contract):通过 tools/list 精确广播给 MCP 客户端的字节。之所以手写,是因为 const 类型的 op 判别字段和逐属性的引导描述无法从 zod 转换保留,而模型恰恰是依据这些描述被提示的。其中 run 的 Schema 有意去掉了顶层 oneOf——AI-SDK 系 MCP 客户端(如 Eve、Vercel AI SDK)会拒绝带顶层 oneOf 的输入 Schema,导致所有 run 调用在客户端侧就失败;code/actions 的互斥改为在描述中声明、由运行时 zod Schema 的 .refine 强制。
  • zod Schema(运行时校验器):解析 tools/call 参数并强制 wire Schema 声明的内容。

两份契约由 tests/facade-contract.test.ts 等契约测试钉死,防止二者漂移。

4.3 底层执行:从 MCP 调用到浏览器动作

stdio-server.ts 的 tools/call 处理器分派三个工具:

  • run 先解析 CodeModeRunInputSchema,若提供了 code 则调用 tools.run(code),否则调用 tools.runActions(actions);
  • snapshot 调用 tools.snapshot(input) 并返回格式化的快照树文本;
  • screenshot 调用 tools.screenshot(input),若设置了 base64 预算(通过启动参数指定),还会在超出预算时自动压缩,返回带 image 类型 content 的 MCP 响应。

核心实现位于 tools.ts 的 StagehandFacadeTools 类:

  • 快照与动作的联动:snapshot 会把页面的 xpathMap 存进 snapshotsByPage(按 pageId 索引)。runActions 执行前会校验:若无快照则抛 NO_HYDRATED_SNAPSHOT_ERROR;若页面 URL 已与快照时不同则抛 NAVIGATED_SNAPSHOT_ERROR 并清除该页快照;快照 ID 找不到对应 XPath 时抛 staleSnapshotIdError。随后把动作通过 experimentalBatch 在浏览器内批量执行,超时 60 秒。
  • run(code) 的执行容器:tools.ts 用 FACADE_PRELUDE + code + FACADE_EPILOGUE 拼出一段异步函数体,注入 createPlaywrightCompatRuntime(Playwright 兼容运行时),从而让模型写出的 page、context、browser 变量可用;执行异常会被捕获包装成 executionError 信封并还原为宿主进程中的错误抛出。
  • 串行队列:所有操作通过 enqueue 在一条 Promise 队列上串行执行,保证同一会话内快照与动作的顺序一致性。

五、安全模型

安全是这条集成链路中最重要的设计,README 与源码双重印证了以下边界:

5.1 模型代码在浏览器内执行,不在宿主进程

run(code) 执行的是模型编写的 JavaScript,但它运行在扩展的 service worker 中,即浏览器侧,绝不运行在 Node 宿主进程中。宿主进程只负责 spawn Facade 服务器并持有 MCP 连接,模型编写的代码无法直接触达宿主进程的 Node 上下文。

5.2 Browserbase 是推荐的隔离边界

隔离的关键在于浏览器本身。示例推荐使用 Browserbase 云端浏览器作为隔离边界——模型代码造成的破坏被限制在可销毁的远程浏览器实例中,这与"无头浏览器执行任意代码"场景下的最佳实践一致。本地 local 模式(默认 headless: false)则直接复用本机浏览器,隔离强度低。

5.3 环境变量白名单:宿主环境永不完整转发

这是源码层面最直观的防御措施。client.ts 中的 buildAllowlistedEnv 只允许 STAGEHAND_* 和 BROWSERBASE_* 前缀的变量穿过进程边界:

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;
}

子进程收到的是这些白名单变量加上 MCP 传输的安全默认值(HOME、PATH、SHELL、TERM、USER、LOGNAME),宿主进程的完整环境变量永远不会被转发。这意味着宿主中可能存在的其他密钥、令牌不会泄漏给承载模型代码的子进程。

这一行为被 client.test.ts 的测试显式钉死:测试设置了 NOT_ALLOWLISTED_SECRET 并断言 buildAllowlistedEnv() 结果中不存在该变量;同时验证了 listToolsetsWithErrors 能发现唯一的 stagehand 工具集,且工具名与描述与 FACADE_TOOLS 导出的源真值逐一对齐。

5.4 错误信息脱敏

即便发生错误,Facade 服务器在回传错误时也会调用 sanitizeErrorMessage(见 stdio-server.ts),将 apiKey、token、sk-*、bb_live_* / bb_test_*、AIza*、Bearer 等模式替换为 [redacted],避免密钥通过 MCP 错误通道泄露。

六、测试与验证

集成包自带 vitest 单元测试(pnpm --filter ... test),覆盖本示例区别于契约测试的独特逻辑:

  1. 工具集发现:通过宿主环境白名单启动 MCP 客户端后,listToolsetsWithErrors 应无错误、且只发现 stagehand 一个工具集;工具名与描述必须与 FACADE_TOOLS 完全一致。
  2. 白名单过滤:STAGEHAND_BROWSER=local 会被保留,NOT_ALLOWLISTED_SECRET 不会被携带。

测试中每个用例结束后都会调用 client.disconnect() 并清理环境变量,保证子进程与浏览器被正确回收——这本身就是"连接生命周期管理"的绝佳示范。

七、小结与延伸

通过 packages/integrations/mastra 这个官方示例,你可以看到一条可复用的"框架无关浏览器接入"路径:Facade MCP 服务器(stdio-server.ts)以统一的 run / snapshot / screenshot 契约暴露 Stagehand 能力,任意 MCP 客户端框架都能以同样的方式接入;run 让模型直接书写浏览器内 JavaScript,snapshot + 动作批次则提供了更可控、可校验的交互路径;而"浏览器内执行 + Browserbase 隔离 + 环境变量白名单 + 错误脱敏"构成了完整的安全纵深。

若需更进一步,可在 packages/integrations/core/src/facade 下阅读契约定义与工具实现,或参考 packages/integrations 中其他框架(如 Claude Code、Codex、Eve、Vercel AI SDK、Pi、Mastra 等)的接入示例,对比"MCP 桥接"与"进程内绑定"两种模式在各自生态中的落地差异。

登录后查看全文
stagehand