Stagehand x CrewAI 集成实战基于 MCP/stdio 的 Facade 桥接方案【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand导读本文讲解如何在 Python CrewAI 框架中接入 Stagehand 浏览器 Agent 能力通过一个保留截图信息的crewai-toolsMCP 适配器子类将 Stagehand Facade MCP 服务器基于 stdio 协议暴露的run、snapshot、screenshot三个工具挂载给 CrewAI Agent。读完本文你将掌握该集成的完整环境搭建、环境变量配置、运行方式、截图保留机制以及其背后的安全模型与源码级实现原理。该集成位于仓库的 packages/integrations/crewai 目录是 Stagehand 多框架集成矩阵Claude Code、Codex、Eve、Mastra、Vercel AI SDK 等中的 Python 一员详见 packages/integrations/README.md。一、整体架构CrewAI 如何驱动 Stagehand FacadeCrewAI 本身是纯文本的工具调用循环不具备直接操作浏览器的能力。本示例的桥接思路是Facade MCP 服务器由browserbasehq/stagehand-integrations包的stagehand-facadestdio 服务器扮演入口为 stdio-server.ts它维护一个持久化浏览器对外只暴露三个工具run、snapshot、screenshotCrewAI 侧agent.py通过mcpadapt的MCPAdapt以 stdio 方式拉起 Node 子进程再把 MCP 工具转换为 CrewAI 的BaseTool关键适配点crewai-tools的CrewAIToolAdapter在转换时会丢弃 MCP 的ImageContent块文本化转换因此示例实现了一个ImageSavingToolAdapter子类在转换前把截图写入临时文件并用文本块替换从而保住截图能力。从源码结构看这套“三个工具 一个持久化浏览器”的契约被定义在 core/src/facade/contract.ts 中一次供所有宿主框架复用不在各示例中重复维护。二、环境准备与依赖安装2.1 前置要求Node.js 24facade 服务器是 Node 子进程core 的 package.json 声明node 22.18.0但本示例明确要求 24uvPython 依赖管理工具项目通过uv sync安装Python3.11,3.14见 pyproject.toml。2.2 安装步骤先在仓库根目录安装依赖并构建 integrations 包使 facade 服务器入口文件dist/facade/stdio-server.mjs存在pnpm install pnpm exec turbo run build --filter browserbasehq/stagehand-integrations然后安装 Python 依赖cd packages/integrations/crewai uv sync依赖声明于 pyproject.tomlcrewai1.15,2crewai-tools[mcp]1.15,2dev 组pytest9,10、ruff0.15,1注意resolve_server_path()见 agent.py硬编码查找core/dist/facade/stdio-server.mjs若找不到会抛出明确报错并提示先执行上面的 turbo build 命令因此构建顺序不可省略。三、环境变量配置一张表看懂全部变量变量用途STAGEHAND_BROWSER浏览器后端。设置了BROWSERBASE_API_KEY时默认为browserbase否则为local。BROWSERBASE_API_KEYBrowserbase API Key云端浏览器隔离边界的关键凭据。STAGEHAND_MODEL_NAME/STAGEHAND_MODEL_API_KEYFacade 服务器使用的模型及其 API Key。CREWAI_MODELCrewAI Agent 模型默认为openai/gpt-5.6-luna。OPENAI_API_KEY供宿主进程中 CrewAI Agent 模型使用不会被转发给 facade 子进程子进程环境变量是显式的STAGEHAND_*/BROWSERBASE_*白名单。关于最后一行源码中的实现非常清晰facade_env()只透传以STAGEHAND_或BROWSERBASE_开头的环境变量见 agent.py并将注释明确说明“模型提供方凭据例如OPENAI_API_KEY被刻意不转发”。3.1 底层配置解析逻辑Facade 服务器侧的环境变量解析位于 core/src/facade/config.ts值得展开STAGEHAND_BROWSER只接受local或browserbase两个值其它值直接抛StagehandFacadeConfigError未显式设置时存在BROWSERBASE_API_KEY就选browserbase否则选localrequestedBrowser ?? (browserbaseApiKey ? browserbase : local)选browserbase却缺 Key 会报错STAGEHAND_MODEL_API_KEY设置了但没给STAGEHAND_MODEL_NAME也会报错未显式指定模型时若检测到 Google 系 KeyGOOGLE_GENERATIVE_AI_API_KEY/GEMINI_API_KEY/GOOGLE_API_KEY默认模型为google/gemini-3.6-flash模型名采用provider/name格式自动从环境推断对应 provider 的 Keyopenai / anthropic / groq / cerebras 等local模式默认headless: false有头浏览器browserbase模式透传projectId。四、运行方式从packages/integrations/crewai/目录执行uv run pytest uv run python agent.py your instructionuv run pytest运行 test_contract.py 中的契约测试uv run python agent.py your instruction把命令行参数拼接为任务描述交给 CrewAI。不给指令时脚本会打印用法并退出退出码 2见 agent.py。运行后 Crew 会执行kickoff()Agent 通过三个工具完成浏览器任务最终输出一份“任务完成情况及结果”的简要报告expected_output定义见 agent.py。4.1 契约测试三个工具名与提示词被钉死test_contract.py的三个测试分别验证test_facade_tool_contract会话暴露的工具名排序后必须恰好为[run, screenshot, snapshot]且run工具描述中必须出现never kindtest_image_saving_tool_adapter_preserves_screenshot构造一个含TextContentImageContent的假CallToolResult验证适配器把 PNG 字节写入stagehand-screenshot-*.png临时文件、返回文本路径、且原始 base64 不再出现在结果中test_instructions_match_canonical_constant当仓库内存在core/src/facade/contract.ts时校验agent.py中手抄的FACADE_AGENT_INSTRUCTIONS与 TypeScript 端规范常量逐字一致归一化空行后比较防止两侧提示词漂移。也就是说Agent 的系统提示词并非每个示例各写一份而是以 contract.ts 中的FACADE_AGENT_INSTRUCTIONS为唯一真源。五、三个 Facade 工具契约与用法5.1 工具清单来自 contract.ts 的FACADE_TOOLS工具输入 Schema 要点说明runcode字符串或actions数组二者恰好提供一个导航 自动化都在这里传 JavaScript 走code传快照动作批量走actions。动作必须用op绝不用kind和id绝不用refID 需从最新快照复制为字符串。snapshotincludeIframes布尔默认true抓取活动页面的可访问性树并注入带括号的元素 ID每次调用都会替换活动页面的 ID 映射。screenshotfullPage布尔、typepng/jpeg、quality0–100截取活动页面。对尺寸受限的 MCP 客户端推荐{type:jpeg,quality:40,fullPage:false}。run支持的快照动作类型由RefActionSchema定义见 contract.tsclick、hover只需opidfill额外value字符串type额外text可选delay非负数字press额外key字符串select额外values字符串或字符串数组至少一项。运行时CodeModeRunInputSchema通过.refine强制code与actions二选一见 contract.ts。值得一提的实现细节线缆层刻意不设顶层oneOf互斥因为基于 AI SDK 的 MCP 客户端如 Eve、Vercel AI SDK会拒绝带顶层oneOf的输入 Schema导致run在客户端就被拒绝——互斥改为描述文本声明 运行时校验该偏差在 contract.ts 的注释中有明确记录。5.2 提示词Agent 被明确要求“只用一个持久化浏览器”FACADE_AGENT_INSTRUCTIONS原文contract.ts规定恰好三个工具snapshot检查页面并注入元素 ID、run执行快照动作或 Playwright 风格pageAPI 的 JavaScript、screenshot视觉检查简单交互用 snapshot 动作多步工作流用run code每个动作只用op和idID 仅对活动页面最新一次快照有效导航或 ID 过期后必须重新 snapshot不要启动另一个浏览器。5.3 服务端执行链路tools.tscore/src/facade/tools.ts 中的StagehandFacadeTools是三个工具的服务端实现几个关键点快照水合snapshot()保存pageId → { url, xpathById }映射runActions()执行前校验未先快照则报NO_HYDRATED_SNAPSHOT_ERROR页面 URL 与快照时不一致则报NAVIGATED_SNAPSHOT_ERROR并删除缓存ID 查不到对应 XPath 则报staleSnapshotIdError(id)——这些错误常量同样定义在 contract.ts动作执行通过experimentalBatch在浏览器上下文内运行一段预置的ACTION_RUNNER_SOURCE用locator依次执行 click/hover/fill/type/press/select返回{ completed }代码执行run(code)把用户代码包进FACADE_PRELUDE/FACADE_EPILOGUE后注入浏览器上下文提供page、context、browser等 Playwright 兼容运行时createPlaywrightCompatRuntime见 runtime.ts用户代码抛错会以 envelope 形式回传并重新抛出串行队列所有操作经enqueue排队避免并发操作同一个浏览器截图支持 JPEG quality 取整以及“Base64 预算内压缩”screenshot-transport.ts。六、截图保留机制为什么需要 ImageSavingToolAdapter当前版本的 CrewAI 工具循环是纯文本的且crewai-tools的 MCP 适配器会丢弃 MCP 图片块。为让 Agent 仍能“看到”页面ImageSavingToolAdapteragent.py的做法是包裹原工具 callable遍历CallToolResult.content非图片块原样保留ImageContent块则按 MIME 类型image/jpeg→.jpeg、image/png→.png解码写入tempfile.mkstemp生成的临时文件前缀stagehand-screenshot-用一条文本块Screenshot saved to path.替换图片块再交给父类做文本化转换。因此每次截图后Agent 拿到的是一个本地文件路径打开该文件即可查看截图。七、安全模型模型代码跑在哪里run(code)执行的是模型撰写的 JavaScript其运行位置是本示例最需要理解的安全边界代码通过experimentalBatch在扩展的 service worker 中浏览器侧执行绝不在宿主进程中运行Python 宿主进程只负责拉起 facade 服务器Node 子进程并持有 MCP 连接模型撰写的 JavaScript 不会进入宿主进程Browserbase 是推荐的隔离边界把浏览器放到 Browserbase 云端配置BROWSERBASE_API_KEY模型代码即使有越界行为也被限制在浏览器沙箱与云端会话内子进程环境变量白名单STAGEHAND_*/BROWSERBASE_*进一步确保宿主侧的模型凭据如OPENAI_API_KEY不会被模型代码读到。服务器侧还有一层防护sanitizeErrorMessagestdio-server.ts在错误回传时对 API Key、Bearer Token、bb_前缀 Browserbase Key、Google AIza Key 等做脱敏避免凭据泄露到 Agent 上下文。八、常见排查方向报错“Stagehand facade server not found”说明core/dist/facade/stdio-server.mjs尚未构建回到仓库根目录执行pnpm exec turbo run build --filter browserbasehq/stagehand-integrations报错“node was not found”宿主进程通过shutil.which(node)定位 Nodeagent.py需确保 Node 24 在PATH中STAGEHAND_BROWSER 取值错误 / browserbase 缺 Key查看stagehandFacadeConfigFromEnv的校验分支config.ts按 3.1 节约束配置Agent 抱怨 ID 失效快照 ID 只对活动页面的最新快照有效导航后必须先重新snapshot。结语本示例的价值在于把“浏览器自动化”能力以最小的契约面三个工具、一个持久化浏览器、纯文本 MCP 传输接入 CrewAI同时通过截图适配器弥补crewai-tools的文本化限制。理解其契约定义contract.ts、配置解析config.ts、服务端工具实现tools.ts与安全边界service worker 环境白名单后你既可以直接照搬运行也可以把同样的模式迁移到其它 MCP 客户端框架中。【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考