ACP 协议详解：Vercel AI SDK 如何统一接入编程智能体

Vercel 到底发布了什么

先把几个经常被混为一谈的层次分清楚。

模型负责生成下一次响应。**执行框架（harness）**通过管理会话、工具、审批、沙箱、指令、上下文压缩和任务循环，把模型变成真正能干活的执行者。ACP 是 Agent Client Protocol 的缩写，它为客户端与执行框架规定了一套通用通信方式。

Vercel 的 HarnessAgent 已经为应用提供了统一的执行框架 API，缺的只是连接器。在这次发布之前，包括 Claude Code、Codex、Pi、Deep Agents 和 OpenCode 在内，每个运行时都需要 Vercel 单独开发适配器。

新的 ACP 执行框架适配器 不再绑定某个具体运行时，而是封装协议本身。调用 createACP 时，需要提供实现该执行框架 ACP 能力的 NPM 包、可执行文件、身份验证规则、指令映射和权限映射。通用适配器则负责桥接层、ACP 客户端、工具转发、事件、审批和会话生命周期。

这就是设计的核心：Vercel 维护共用桥接层，各个运行时配置文件只处理执行框架之间真正不同的部分。

该适配器目前支持 ACP version 1，并且只支持 version 1。它保证的是协议边界上的兼容性，并不承诺接入后所有执行框架的行为都一样。

Vercel 对选型说得很明确：Claude Code 和 Codex 应分别使用 @ai-sdk/harness-claude-code 与 @ai-sdk/harness-codex。只有当执行框架提供兼容包、但没有专用适配器时，才使用 @ai-sdk/harness-acp。

Vercel AI SDK 的 ACP 协议适配器为何重要

真正发生变化的是集成工作量。

开发者工具团队要把另一个 ACP 运行时接到 HarnessAgent 后面时，不必再重做会话管理、事件转换、审批链路、宿主工具转发和生命周期逻辑。团队只需编写运行时配置文件，应用的其余部分继续使用同一套执行框架 API。

产品层也因此更稳定。HarnessAgent.generate() 和 HarnessAgent.stream() 都会返回兼容 AI SDK 的结果。已经采用 useChat 的团队可以保留现有交互流程，只替换背后的执行者。

这次发布不会让执行框架变得更快、更便宜或更强，也不会让不同 ACP 实现自动拥有一致行为，更不能取代沙箱。每个 ACP 执行框架仍然需要一个至少开放一个端口的网络沙箱。

如果只是直接使用 Claude Code、Codex 或其他编程智能体，基本不会受这项功能影响。它服务的是围绕这些智能体构建产品的团队。

哪些团队现在就能用

想接入 AI SDK 的开发者工具创业团队

假设公司已经推出一套编程执行框架，也发布了兼容 ACP 的 NPM 包。现在只需定义一个 createACP 配置文件，就能为 AI SDK 用户提供正式接入该运行时的路径。

最大的收益是分发效率。团队负责维护该包特有的安装、身份验证、指令和权限逻辑，外围共用的连接工作交给 Vercel 适配器。

需要支持多个运行时的平台工程师

一家中型工程平台可能希望用一个智能体修复代码仓库，用另一个处理迁移任务，再用内部执行框架完成公司专属自动化。平台工程师可以统一会话与结果契约，再按任务选择不同的执行框架配置文件。

不同运行时的行为差异并不会消失，只是被收拢到命名清晰的配置文件里。与维护多套独立编排栈相比，这种方式更容易审查。

已有 AI SDK 界面的 SaaS 团队

产品团队无需重做聊天界面，就能在现有 AI SDK 应用背后加入由 ACP 驱动的编程执行者。实际改动发生在服务端：创建执行框架配置文件，挂载沙箱，启动会话，再向 UI 返回与原来相同类型的流式或一次性生成结果。

如果目前仍在选择智能体，而不是把某个智能体集成进产品，可以先看这份编程智能体对比。这款适配器是在完成产品选型之后才会派上用场。

负责划定边界的安全工程师

安全工程师会得到一组明确的控制点。凭据可以通过代理机制传递：沙箱中的 ACP 进程只看到占位符，真实值则在请求出站时才被写入。权限模式也可以映射到运行时真正支持的模式；不支持的选项设为 null，让请求直接失败，而不是悄悄扩大权限。

这并不代表系统会自动变得安全，但它提供了一个清晰的位置，用来编码和测试安全规则。

如何接入 ACP 执行框架

一份完整的官方示例

先安装执行框架、ACP 适配器和 Vercel Sandbox 包：

pnpm add @ai-sdk/harness @ai-sdk/harness-acp @ai-sdk/sandbox-vercel

最精简且不回避关键细节的演示，是 Vercel 给出的完整 Codex ACP 配置文件。它在同一个示例里展示了包安装、直接凭据、AI Gateway 配置、指令和权限。这只是接线示例，并不意味着 Codex 应优先选择 ACP；在真实 Codex 集成中，Vercel 更推荐专用适配器。

下面的代码是当前文档中的配置文件与调用流程。直接身份验证需要提供 CODEX_API_KEY 或 OPENAI_API_KEY。如果环境中存在 AI_GATEWAY_API_KEY 或 VERCEL_OIDC_TOKEN，默认的 auth: 'auto' 路径会改用 AI Gateway。

import { createACP, type ACPPermissionModeMapping } from '@ai-sdk/harness-acp';
import { createCredentialRequestTransformation } from '@ai-sdk/harness/utils';
import { secureJsonParse } from '@ai-sdk/provider-utils';

export const codexACPHarness = createACP({
  harnessId: 'acp-codex',
  // Define the runtime's built-in tool names and input schemas to expose
  // provider-executed calls as typed HarnessAgent tools.
  // builtinTools: { ... },
  source: {
    type: 'npm-simple',
    packageName: '@agentclientprotocol/codex-acp',
    packageVersion: '1.1.4',
  },
  executable: 'codex-acp',
  forwardEnv: ['CODEX_CONFIG'],
  credentialEnv: ['CODEX_API_KEY', 'OPENAI_API_KEY'],
  credentialBrokering: ({ env }) => {
    const credential = env.CODEX_API_KEY ?? env.OPENAI_API_KEY;
    if (!credential) return [];
    const config =
      env.CODEX_CONFIG == null
        ? undefined
        : (secureJsonParse(env.CODEX_CONFIG) as {
            model_provider?: string;
            model_providers?: Record<string, { base_url?: string }>;
          });
    const baseUrl =
      config?.model_providers?.[config.model_provider ?? '']?.base_url ??
      'https://api.openai.com/v1';
    return [
      createCredentialRequestTransformation({
        baseUrl,
        headers: { Authorization: `Bearer ${credential}` },
      }),
    ];
  },
  instructionMapping: {
    type: 'launch-env-json',
    variable: 'CODEX_CONFIG',
    path: ['developer_instructions'],
  },
  permissionModeMapping: {
    'allow-reads': null,
    'allow-edits': null,
    'allow-all': { type: 'session-mode', modeId: 'agent-full-access' },
  } as const satisfies ACPPermissionModeMapping,
  authentication: {
    methodId: 'api-key',
  },
  providerAuthentication: {
    gateway: {
      env: {
        CODEX_API_KEY: { $source: 'gateway-api-key' },
        CODEX_CONFIG: {
          model: 'openai/gpt-5.6-sol',
          model_provider: 'ai_gateway',
          model_providers: {
            ai_gateway: {
              name: 'AI Gateway',
              base_url: {
                $source: 'gateway-base-url',
                ensureSuffix: '/v1',
              },
              env_key: 'CODEX_API_KEY',
              wire_api: 'responses',
              supports_websockets: false,
              http_headers: {
                'User-Agent': { $source: 'client-app' },
                'x-client-app': { $source: 'client-app' },
              },
            },
          },
          model_supports_reasoning_summaries: true,
          preferred_auth_method: 'apikey',
        },
      },
    },
  },
});

最容易被忽略的一点，是把运行时配置文件误以为只有包名和 API 密钥。权限映射、指令映射、沙箱端口、凭据边界和会话清理，同样属于集成的一部分。

必须正视的限制

这些执行框架包仍处于实验阶段，版本升级可能带来破坏性变更，因此不适合在生产环境中不加控制地自动更新依赖。

锁定包版本时需要做出明确选择。简单来源可以固定到精确版本，就像示例把 @agentclientprotocol/codex-acp 锁定为 1.1.4。如果省略版本，沙箱会安装该包的 latest 标签，而且这个版本不会计入执行框架身份。如需可复现构建，应使用包含 package.json 和 pnpm-lock.yaml 的锁定来源；Vercel 会通过 pnpm install --frozen-lockfile 安装。

ACP version 1 还存在几项实质性缺口：

• 它不会暴露模型步骤边界或逐步用量。适配器只能推断步骤边界，逐步用量仍然未知。
• 它没有可移植的手动上下文压缩或回合中途引导 API。
• 它无法以可移植方式筛选执行框架的内置工具。宿主工具仍可筛选，但尝试筛选 ACP 内置工具会抛出错误。
• 如果宿主工具目录发生变化，ACP 实现必须刷新 MCP 工具列表。工具列表陈旧的实现会明确报错。

本文查阅的 Vercel 发布页面没有列出 @ai-sdk/harness-acp 的单独价格，但这不等于“免费智能体”。这套架构仍包含模型身份验证路径和必需的网络沙箱，现有运行成本与控制措施依然适用。

更深层的限制在于还原度。ACP 提供通用连接方式，专用适配器却能更贴近执行框架的原生行为。标准化可以减少集成工作，但不会抹平底层运行时的差异。

现在应该怎么选

我的判断标准很简单。

如果团队拥有一个兼容 ACP、但没有 AI SDK 专用适配器的执行框架，或者平台团队需要把多个这类运行时放到同一套应用契约背后，本周就可以开始行动：编写轻量配置文件、锁定包版本，并测试每一种权限和失败路径。

如果生产策略无法接受实验性软件包，或者业务必须获得准确的逐步用量，又或者手动上下文压缩与回合中途引导属于核心控制能力，那就先等一等。

如果使用 Claude Code 或 Codex，应继续采用专用适配器。这是 Vercel 已经推荐的路径，也能避免协议层压缩掉更多运行时行为。

如果只是直接调用模型、作为终端用户使用编程智能体，或根本不需要在自有应用中运行执行框架，则无需关注这项变化。

如果希望继续看到这种不绕弯的技术拆解，欢迎订阅邮件通讯。