如何把 Vercel AI SDK 智能体接入 Stagehand 的持久化浏览器工具-育师

如何把 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 包（集成文档、集成总览）。

准备条件

开始前确认环境满足以下要求（来自文档 Prerequisites）：

Node.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服务入口不存在（示例 README）：

git 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_KEY="your-openai-api-key" # 替换为你自己的 OpenAI API key

AI_SDK_STAGEHAND_MODEL用于在示例支持的模型中换模型，不设置时默认gpt-5.6-luna。

浏览器后端二选一：

默认使用本地 Chrome，无需额外配置；
可选：改用 Browserbase 的一次性浏览器，需要以下两个变量：

export STAGEHAND_BROWSER="browserbase" export BROWSERBASE_API_KEY="your-browserbase-api-key" # 替换为你自己的 Browserbase API key

完整的变量含义见下表（来自集成文档的 Configuration 一节）：

变量	用途
`AI_SDK_STAGEHAND_MODEL`	AI 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脚本会先构建集成包再跑 vitest（test定义在 package.json）：

pnpm --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页面）。