ACP 协议适配器详解：Vercel AI SDK 7 如何接入 Grok Build

2026年8月13日，Vercel 正式通过 ACP 协议适配器，让 Grok Build 接入 AI SDK 7 的 HarnessAgent。这意味着，产品可以沿用同一套应用接口运行 Grok Build；面对 Vercel 目前支持的九种编程执行框架，也不必再为每一种重写编排层。

Vercel 的 ACP 协议适配器究竟发布了什么

这是一次适配器发布，并不是新的 Grok 模型。

理解它最简单的方式，是先把各层拆开。模型负责生成响应；**编程执行框架（coding harness）**通过管理文件、工具、会话、权限以及推动任务持续运行的循环，把模型变成真正能干活的执行者。Agent Client Protocol（简称 ACP）是客户端与兼容执行框架之间的通用语言；适配器则把这套协议转换成应用已经熟悉的接口。

Vercel 推出的新包是 @ai-sdk/harness-grok-build。它通过 ACP 将 HarnessAgent 连接到 Grok Build CLI，底层使用的是更基础的 @ai-sdk/harness-acp 包。

整个调用链如下：

你的应用 → HarnessAgent → Grok Build 适配器 → 沙箱内的 Grok Build CLI

通用 ACP 层相当于底层管道；Grok Build 适配器则是已经装配完成的连接器，包、可执行文件、鉴权映射、启动命令和工具映射均已定义。如果想继续了解协议底层的工作方式，可以阅读 AI SDK ACP 执行框架适配器解析。本文只聚焦可以直接采用的 Grok Build 接入路径。

在此之前，要接入一个 ACP 运行时，就得自行定义对应的运行时配置。Grok Build 在8月13日发布官方适配器后，便可以像 Claude Code、Codex、Deep Agents、OpenCode 和 Pi 一样走 HarnessAgent 的会话流程；当时支持的执行框架总数也由此达到六种。

自2026年8月31日起，Vercel 新增 fx，支持名单扩展至九种执行框架：Claude Code、Cline、Codex、Cursor、Deep Agents、fx、Grok Build、OpenCode 和 Pi。fx 适配器只是扩大了可选范围，并不会改变 Grok Build 适配器的工作方式。

这里更值得关注的是“同一接口”，而不是“同一个代理”。应用层契约可以保持不变，但九种受支持执行框架的工具行为、权限、可观测性和模型输出并不会因此完全一致。

为什么这款 AI SDK 适配器值得关注

真正减少的是集成工作量。

HarnessAgent.generate() 和 HarnessAgent.stream() 会返回与 AI SDK 兼容的结果。如果产品已经采用 AI SDK 的聊天或任务接口，Grok Build 就能接入现有的结果流。服务器侧可以更换执行框架，前端却不必因为执行者变了就重新适配响应格式。

平台团队因此可以更清晰地对比不同运行时，或把不同任务路由给合适的执行框架：会话生命周期和流式数据结构保持统一，只需按任务选择执行框架。

这次发布不会让 Grok Build 变得更快、更便宜或更准确，它增加的只是一条官方支持的连接路径。只在 Grok Build 自带 CLI 中使用它的人也不会因此受益；真正的目标用户，是围绕 AI 编程代理开发产品或内部系统的团队。

哪些团队现在就能用上

想再增加一种运行时的开发者工具创业者

假设你在销售一款基于 AI SDK 的 AI 代码审查或仓库修复产品，现在可以把 Grok Build 加为另一种服务器侧执行框架，无须再为它单独设计会话 API 和流式传输契约。

实际改动并不大：安装适配器，接入同类沙箱，再在客户或任务需要时选择 Grok Build。这样就多了一种运行时选择，却不必再维护一套独立的产品界面。

需要比较九种执行框架的平台工程师

平台团队可以让 Grok Build 和另一种受支持的执行框架处理同一个边界明确的仓库任务，再通过统一的应用流程比较完成质量和失败表现。

但比较必须建立在真实条件上。ACP version 1 并不总能提供每一步的用量数据；当 Grok 不返回总量时，这个适配器也无法给出清晰的逐 token 成本对比。你可以比较结果和端到端表现，却不能假设每个可观测字段都同样完整。

负责修复代码仓库的内部工具团队

内部工具团队可以把测试失败修复任务送入隔离工作区，将代理输出的文本实时传回给操作人员，并在任务结束后销毁会话。沙箱边界负责保护宿主环境，明确的生命周期则能避免临时会话变成无人管理的遗留基础设施。

核心收益是运行控制权。修改代码的执行者始终处在有边界的环境中，而环境何时启动、何时结束，都由应用决定。

评估上线风险的安全或可靠性负责人

这类负责人需要做出切实的选择。直连鉴权使用 XAI_API_KEY，AI Gateway 鉴权使用 Gateway 凭据。默认的 auto 模式会在存在相应凭据时选择 AI Gateway，否则采用 xAI 直连鉴权。

权限也必须在真实的工具边界上测试。Grok Build 不会公布 ACP 会话模式，而且某些安全的内置操作可能不会触发 ACP 权限请求。为其他执行框架制定的策略，不能证明 Grok Build 也会表现一致。

按官方路径运行

最短的完整配置方案，是使用 Vercel Sandbox 和适配器的默认设置。

1. 1

   安装依赖包

   加入通用执行框架 API、Grok Build 适配器和 Vercel Sandbox 实现：

   pnpm add @ai-sdk/harness @ai-sdk/harness-grok-build @ai-sdk/sandbox-vercel

2. 2

   配置沙箱与模型凭据

   使用文档中的 Vercel Sandbox 路径时，需要提供 VERCEL_OIDC_TOKEN。若要直接通过 Grok 鉴权，则提供 XAI_API_KEY；若走 Gateway，则提供相应的 AI Gateway 凭据，需要覆盖基础 URL 时还可以使用 AI_GATEWAY_BASE_URL。适配器默认的 auth: 'auto' 会根据现有凭据选择可用路径。

3. 3

   创建、运行并销毁会话

   使用当前的 Grok Build 执行框架示例：

   import { HarnessAgent } from '@ai-sdk/harness/agent';
   import { grokBuild } from '@ai-sdk/harness-grok-build';
   import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
   
   const agent = new HarnessAgent({
     harness: grokBuild,
     model: 'grok-build-0.1',
     sandbox: createVercelSandbox({
       runtime: 'node24',
       ports: [4000],
     }),
   });
   
   const session = await agent.createSession();
   
   let exitCode = 0;
   try {
     const result = await agent.stream({
       session,
       prompt: 'Check the test failures and fix the production code.',
     });
   
     for await (const part of result.stream) {
       if (part.type === 'text-delta') {
         process.stdout.write(part.text);
       }
     }
   } catch (err) {
     exitCode = 1;
     console.error(err);
   } finally {
     await session.destroy();
     process.exit(exitCode);
   }

4. 4

   首次创建会话时需要联网安装

   首次会话必须允许访问外网，因为 ACP 执行框架会在沙箱内安装锁定版本的 @xai-official/grok@1.0.5 包。沙箱若无法访问外网，代理还没开始处理有效任务就会失败。

最容易遗漏的是端口。Grok Build 需要具备网络能力的沙箱，并至少开放一个端口供 ACP 桥接层使用。示例采用 Node 24 和 4000 端口；没有这条网络路径的沙箱对象，并不能算等价配置。

当前示例把 model: 'grok-build-0.1' 传给 HarnessAgent。如果需要控制适配器层，请用 createGrokBuild() 替换 grokBuild。你可以配置鉴权方式、凭据转发、推理强度、MCP 服务器、桥接端口、启动超时或自定义桥接 token 函数。如果省略 reasoningEffort，Grok Build 会采用自身的默认配置。

上生产前必须看清的限制

这款适配器继承了 ACP version 1 的限制，而这些限制在生产环境中不可忽视。

• 用量信息不完整。 ACP 不会暴露模型步骤边界或每一步的用量。适配器只能推断边界；当 Grok 不提供总量时，用量会被标记为未知。
• 无法用统一方式引导正在运行的轮次。 ACP 没有通用的轮次中途引导或手动上下文压缩 API。
• 内置工具过滤能力有限。 宿主工具可以过滤，但尝试过滤 Grok 的内置工具时会抛出“不支持该能力”的错误。
• 工具目录可能过期。 宿主工具列表发生变化后，Grok Build 必须刷新其 ACP MCP 列表；如果仍使用旧列表，该轮任务会明确失败。

版本管理同样存在风险。AI SDK 的执行框架包仍处于实验阶段，因此不同版本之间可能出现破坏性变更。Grok 适配器在内部锁定了 CLI 和 ACP 启动命令，createGrokBuild() 也不允许覆盖这些细节。官方路径因此更简单，但锁定的运行时何时更新，也由适配器包决定。

默认桥接凭据是随机生成的 32-byte token。如果替换 token 生成函数，新的实现必须返回符合密钥要求的值。这是一项安全控制，不应该为了开发时方便而改成易读字符串。

最后，这也不是一次定价调整。Grok 鉴权路径和网络沙箱仍会产生各自的运行成本。适配器减少的是自定义集成工作，并不会让底层基础设施消失。

现在该怎么做

如果已经在使用 AI SDK 7，并希望把 Grok Build 作为可选的编程运行时，本周就可以行动。先从边界明确的仓库任务开始，保留适配器默认设置，同时测试成功与失败路径，并确认会话会被正确清理。

如果产品需要接入多种执行框架，正式上线前先做一次短期评估。比较任务结果、权限行为、失败恢复和单次任务总成本。不要把每一步的用量作为决定性指标，因为 ACP 可能根本不会提供这些数据。

如果手动上下文压缩、轮次中途引导、精确的逐步计量或内置工具白名单属于硬性要求，暂时等待更合适。它们是协议层缺口，不是配置错误。

如果只是直接使用 Grok Build、调用不带编程执行框架的 Grok 模型，或者应用根本不需要切换代理运行时，那么这次发布与你无关。

如果还想阅读更多关于团队交付方式如何被新工具改变的实用解析，可以订阅 Newsletter。