如何把 Vercel AI SDK 智能体接入 Stagehand 的持久化浏览器工具【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand如果你的 Vercel AI SDK 智能体需要完成真实的网页操作导航、点击、填表、读取页面而不是只调用纯 API可以把它的工具循环接入 Stagehand 的持久化浏览器通过 MCP/stdio 连接到 Stagehand 的 facade MCP server由这一个 server 进程持有浏览器run、snapshot、screenshot三次调用之间页面状态保持不变。本文基于 Stagehand 仓库自带的 Vercel AI SDK 集成示例packages/integrations/vercel-ai给出从构建到运行、再到验证接入生效的完整操作路径。需要注意Stagehand 的这个集成是实验性的只随仓库分发不发布为独立 adapter 包集成文档、集成总览。准备条件开始前确认环境满足以下要求来自文档 PrerequisitesNode.js 24 或更新版本pnpm 11.10.0一个 OpenAI API key供示例智能体使用本地浏览器模式下需要当前版本的 Google Chrome 安装。智能体的默认模型是gpt-5.6-luna见 示例源码 中process.env.AI_SDK_STAGEHAND_MODEL ?? gpt-5.6-luna如果该模型可用就可以直接运行。从仓库构建集成包示例的 MCP 客户端会解析browserbasehq/stagehand-integrations/facade/stdio-server入口并在本地启动它所以必须先构建这个包否则dist服务入口不存在示例 READMEgit clone https://gitcode.com/GitHub_Trending/stag/stagehand cd stagehand pnpm install --frozen-lockfile pnpm exec turbo run build \ --filter browserbasehq/stagehand-integrations构建命令只构建集成相关的包不会运行其他包的构建任务。配置环境变量必做的配置只有两项给宿主进程的 AI SDK 智能体提供模型凭证以及选择浏览器后端。# 示例智能体使用的模型凭证必填 export OPENAI_API_KEYyour-openai-api-key # 替换为你自己的 OpenAI API keyAI_SDK_STAGEHAND_MODEL用于在示例支持的模型中换模型不设置时默认gpt-5.6-luna。浏览器后端二选一默认使用本地 Chrome无需额外配置可选改用 Browserbase 的一次性浏览器需要以下两个变量export STAGEHAND_BROWSERbrowserbase export BROWSERBASE_API_KEYyour-browserbase-api-key # 替换为你自己的 Browserbase API key完整的变量含义见下表来自 集成文档 的 Configuration 一节变量用途AI_SDK_STAGEHAND_MODELAI SDK 智能体的模型。OPENAI_API_KEY示例智能体的凭证。AI SDK 进程不会把它转发给 MCP 子进程。STAGEHAND_BROWSER选择local或browserbase。BROWSERBASE_API_KEY使用 Browserbase 时必填。BROWSERBASE_PROJECT_ID可选的 Browserbase 项目 ID。STAGEHAND_MODEL_NAME可选run内部调用 Stagehand AI 方法如act、extract、observe时使用的模型。STAGEHAND_MODEL_API_KEY设置了STAGEHAND_MODEL_NAME时必填MCP 子进程拿不到宿主侧的模型提供商凭证。注意区分两个模型智能体模型决定调用哪个工具Stagehand 浏览器模型只在传给run的 JavaScript 会调用act、extract、observe这类 AI 方法时才需要配置。启动智能体并执行浏览器任务在仓库根目录运行pnpm --dir packages/integrations/vercel-ai start -- \ Open https://example.com and report the page title.也可以用 示例 README 给出的等价的 filter 形式指令作为start参数传入pnpm --filter browserbasehq/stagehand-integrations-example-vercel-ai-facade start your instruction执行时示例程序做了三件事见 agent 入口 和 MCP 客户端createFacadeMCPClient()把browserbasehq/stagehand-integrations/facade/stdio-server作为子进程启动并建立 stdio MCP 连接——整个任务期间只连接一次通过generateText运行 AI SDK 工具循环工具来自client.tools()系统提示使用共享的FACADE_AGENT_INSTRUCTIONS循环上限为stepCountIs(20)20 步循环结束无论成功失败后在finally中调用client.close()停掉子进程和它管理的浏览器。运行结束后示例会把智能体的最终回复打印到终端console.log(result.text)。对上面example.com的示例指令预期看到的就是一段包含页面标题的回复文本——这是文档示例指令的输出形态不是固定文案。三个工具与持久会话的使用约束接入后的智能体拿到的始终是同一组工具契约定义在 facade contract总览见 集成文档snapshot读取当前页面的精简 accessibility tree并激活hydrate交互元素上带方括号的 ID。每次调用都会替换当前页面的 ID 映射run对 Playwright 风格的page、context、browser对象执行 JavaScript或者发送一批引用 snapshot ID 的动作。code和actions必须且只能提供其一。snapshot 动作支持click、hover、fill、type、press、select例如{ code: await page.goto(https://example.com); return await page.title(); }{ actions: [{ op: click, id: 1-42 }] }screenshot把当前页面拍成 PNG 或 JPEG 供视觉检查。持久性来自一个 MCP client 会话对应一个浏览器这条设计改造示例时必须保留这个生命周期连接一次、加载三个工具、模型循环结束后再关闭。文档明确警告如果每次工具调用都新建 MCP 进程会启动新浏览器并丢失之前的页面状态上一次调用拿到的 snapshot ID 也会全部失效。快照 ID 的生命周期同样要注意ID 只对当前页面最新一次 snapshot 有效页面发生导航或 ID 过期后需要重新 snapshot。契约中对应的错误信息是No hydrated snapshot exists for the active page; call snapshot first.、The active page navigated after its snapshot; call snapshot again.以及Snapshot ID ${id} is stale or not actionable; call snapshot again.。验证接入是否生效有三个层次的验证手段均来自仓库文档和示例代码端到端运行执行上面的start命令终端打印出包含任务结果例如页面标题的智能体回复说明工具循环和浏览器会话都已打通。单元/契约测试示例的test脚本会先构建集成包再跑 vitesttest定义在 package.jsonpnpm --filter browserbasehq/stagehand-integrations-example-vercel-ai-facade test pnpm --filter browserbasehq/stagehand-integrations-example-vercel-ai-facade typecheck其中 client 测试 验证的是这个示例特有的行为host 环境变量允许名单确实传进了启动的 server且名单外的变量测试中叫NOT_ALLOWLISTED_SECRET不会跨进程。测试还覆盖了一个具体的错误形态——当STAGEHAND_BROWSER被设成非法值测试中是invalid时调用snapshot工具会返回isError: true文本内容包含STAGEHAND_BROWSER must be either。如果你的环境里出现同样的报错先检查STAGEHAND_BROWSER只取local或browserbase两个值。 3.工具契约工具名、描述和输入 schema 由 core 包的 facade 契约测试固定不需要在这个示例里重复验证。安全边界与限制run执行的是模型编写的 JavaScript运行位置是 Stagehand 浏览器扩展的 service worker浏览器侧不在 agent 宿主进程里。这段代码能控制浏览器并访问会话内可及的一切。文档的建议是不受信任的任务使用 Browserbase 作为隔离边界并把已登录的浏览器会话及其可及数据视为特权资源。凭证隔离是示例内建的行为MCP 子进程只收到STAGEHAND_*、BROWSERBASE_*开头的环境变量外加传输层补充的HOME、LOGNAME、PATH、SHELL、TERM、USER见 client 实现宿主的模型凭证如OPENAI_API_KEY保留在 AI SDK 进程中不会被转发。因此如果run里的 JavaScript 要调用 Stagehand AI 方法必须单独配置STAGEHAND_MODEL_NAME和STAGEHAND_MODEL_API_KEY。集成是实验性的随仓库分发如果你需要更长的上下文或跨框架的工具契约其他框架的接入见 集成总览Vercel 的 Eve 框架走的是进程内原生绑定的同一套工具契约/v4/integrations/eve页面。更多实现细节可以直接读 MCP 客户端与 agent 循环源码 以及 facade 契约定义。【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考