用 Mastra 驱动 Stagehand 浏览器 Agent:基于 MCP/stdio 的 Facade 集成实战
用 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 是示例的主入口,其执行逻辑清晰可读:
- 解析命令行参数:
pnpm start "your instruction"会把后续参数拼接为一条指令,未提供指令时报错退出; - 调用
createFacadeMCPClient()建立 MCP 连接; - 通过
client.listToolsetsWithErrors()发现工具集,若有错误或未发现stagehand工具集则抛错; - 以
FACADE_AGENT_INSTRUCTIONS(从@browserbasehq/stagehand-integrations/facade导入)作为 Agent 指令,模型默认openai(process.env.MASTRA_STAGEHAND_MODEL ?? "gpt-5.6-luna"),工具为 stagehand 工具集,创建 MastraAgent:
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,
});
- 调用
agent.generate(instruction, { maxSteps: 20 })让 Agent 最多执行 20 步工具调用并输出结果; 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),覆盖本示例区别于契约测试的独特逻辑:
- 工具集发现:通过宿主环境白名单启动 MCP 客户端后,
listToolsetsWithErrors应无错误、且只发现stagehand一个工具集;工具名与描述必须与FACADE_TOOLS完全一致。 - 白名单过滤:
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 桥接"与"进程内绑定"两种模式在各自生态中的落地差异。