Agent Client Protocol：概念、原理、使用场景与生态现状

Agent Client Protocol 官方介绍

AI 参与说明（Agent：Codex）：本文由 Codex 基于 ACP 官方规范、官方项目仓库及相关产品文档协助调研、撰写与校验。整理日期为 2026-11-08，主要流程以 v1 为准，v2 Draft 单独说明。执行入口为 Codex Desktop 云端环境；完整模型标识与 reasoning effort 未取得任务级运行记录。

AI 编程工具正在形成更清楚的分工：编辑器负责代码浏览、修改审查和交互，Agent 负责理解任务、调用模型、执行工具和完成工作。两部分长期紧密绑定，开发者想使用另一个 Agent，往往也要适应它附带的编辑器、插件或终端界面。

Agent Client Protocol，简称 ACP，为编辑器与 Coding Agent 建立统一的交互接口。Agent 可以接入不同 Client，Client 也可以复用同一套消息、工具和权限交互组件支持不同 Agent。

理解 ACP，要看清它如何把一次“让 AI 修改代码”的请求，组织成可展示、可交互、可中断的执行过程。先认识几个会反复出现的名称：

ACP 为什么会出现

假设有 M 种编辑器、N 种 Agent。逐一适配时，理论上可能形成 M × N 组集成关系。每组都要解决类似问题：发送代码上下文、展示执行进度、呈现文件差异、处理权限请求，以及中断或恢复工作。

有了统一协议，集成可以围绕 M 个 Client 实现和 N 个 Agent 实现展开。具体产品仍需要处理能力差异，但能够复用共同的通信契约。这与 Language Server Protocol（LSP）的解耦思路相似：LSP 让语言服务接入多个编辑器，ACP 希望让 Coding Agent 获得类似的互操作能力。

ACP 由 Zed 发起，2025 年 8 月 27 日发布时与 Google 合作，将 Gemini CLI 作为最初的参考实现。Zed 当时需要比终端 ANSI 输出更结构化的通信方式，以便在编辑器里呈现 Agent 的回答和修改。同年 10 月，JetBrains 宣布共同开发 ACP，将它推进到更广泛的 IDE 生态。首发公告、JetBrains 加入公告

Client 与 Agent 怎样分工

ACP connects an interactive Client to a Coding Agent. The Agent owns the task execution loop, while the Client presents the interaction to the user. Architecture

Client 发送用户任务和上下文，展示消息、计划与改动，处理用户决定。Agent 管理模型调用、上下文组织、工具执行和重试等逻辑，并向 Client 报告进展。模型服务和 MCP Server 则是 Agent 可以使用的外部能力。

flowchart TD
    U["开发者"] <--> C["编辑器 / ACP Client"]
    C <-->|"ACP：任务、进展、改动、权限"| A["Coding Agent"]
    A <-->|"模型 API"| L["模型服务"]
    A <-->|"MCP"| M["MCP Server"]
    A --> E["执行环境：文件、命令、测试"]

这个划分允许两侧独立改进。Agent 可以调整检索、模型或工具策略；Client 可以优化代码导航、工具卡片和差异审查。同一个事件在不同 Client 中可以有不同呈现，因此协议兼容并不保证界面或模型效果完全相同。

一个连接可以支持多个独立 Session。Client 通常是编辑器，也可以是终端界面、桌面工作台或其他用户界面。Architecture

底层原理：JSON-RPC、stdio 与 Capabilities

双向 JSON-RPC 消息

ACP 使用 JSON-RPC 2.0，包含两种基本交互：带 id 的请求需要对应响应，不带 id 的通知用于单向推送事件。

Client 可以请求创建 Session、处理任务；Agent 也可以反向请求 Client 处理权限或访问 Client 提供的资源。用户决定可以成为执行过程中的暂停点，Agent 收到结果后继续工作。v1 Overview

本地子进程与传输格式

当前最明确的标准接入路径是 Client 启动本地 Agent 子进程，通过 stdio 通信：

Client 写入 ──→ Agent stdin
Client 读取 ←── Agent stdout
调试日志    ←── Agent stderr

Each stdio message is a single UTF-8 JSON-RPC message followed by a newline. Diagnostic output belongs on stderr. Transports

每条报文占一行，不能为排版而在 JSON 结构中换行；字符串内部的换行需要转义。stdout 只能包含合法 ACP 消息，随意打印启动横幅或调试日志可能破坏解析。

ACP 面向本地与远程场景，但目前传输规范正式定义的机制仍是 stdio，基于 Streamable HTTP 的远程传输还在制定中。自定义 HTTP 或 WebSocket 通道可以存在，互操作性需要额外确认。

另一个容易混淆的地方是：Agent 支持通过 HTTP 连接 MCP Server，与 ACP 本身支持 HTTP 传输，是两件不同的事。Transports

先协商版本，再判断可选能力

双方首先通过 initialize 交换协议版本、Capabilities、实现信息和认证方式。Client 可以声明文件读写或终端操作支持，Agent 可以声明图片输入、嵌入上下文或加载历史 Session 等能力。

The negotiated protocol version identifies the major wire contract. Optional features depend on the peer’s advertised capabilities. Initialization

因此，同为 v1 的两个 Agent，功能也可能不同。没有声明的可选能力不能默认视为支持。SDK 包版本、Schema 发布号与线上协商的 protocolVersion 也需要分开判断。

一次任务怎样执行

以“修复一个失败的测试”为例，v1 的交互顺序如下：

sequenceDiagram
    actor U as 开发者
    participant C as ACP Client
    participant A as Agent
    C->>A: initialize
    A-->>C: 版本、Capabilities、认证方式
    Note over C,A: 按需完成认证
    C->>A: session/new
    A-->>C: sessionId
    U->>C: 修复失败的测试
    C->>A: session/prompt
    A-->>C: session/update：计划、消息、工具状态
    opt 操作需要用户决定
        A->>C: session/request_permission
        C->>U: 展示操作与选项
        U->>C: 作出选择
        C-->>A: 返回选择结果
    end
    Note over A: 执行工具、修改代码、运行测试
    A-->>C: session/update：结果与差异
    A-->>C: prompt 响应：stopReason

初始化与认证

初始化必须先于 Session 创建。认证按 Agent 宣告的方式进行：有些由 Agent 处理，有些需要 Client 启动独立的交互式终端完成登录，再重新连接。终端认证方式不能直接当作普通 authenticate 请求处理。

ACP 规定认证方式如何发现和启动，具体账号、凭证与服务访问仍由相应实现管理。Authentication

创建和恢复 Session

Client 通过 session/new 提交绝对工作目录 cwd 和 mcpServers 配置，获得 sessionId。支持 loadSession 能力的 Agent，还可以通过 session/load 恢复之前的 Session，并使用 session/update 重放历史。

恢复依赖 Agent 的实现与数据。接入同一个协议，不会自动让不同 Agent 共享记忆，也不会自动迁移凭证和历史。Session Setup

Prompt Turn 与实时更新

Client 调用 session/prompt 后，Agent 可以在一个 Prompt Turn 中多次调用模型和工具，通过 session/update 报告消息、计划、Tool Call 和状态变化。

In v1, the session/prompt request remains pending until the Agent returns a stop reason. Prompt Turn

收到一段回答文本并不表示任务完成。Client 要继续处理通知与反向请求，直到原始请求结束。

下面是最小 v1 报文示意，假设不需要认证。每行是独立 JSON-RPC 消息，前五条为请求与响应，最后两条为 Agent 的通知和响应；它展示协议结构，并非完整 Agent 程序。

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{},"authMethods":[]}}
{"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/work/demo","mcpServers":[]}}
{"jsonrpc":"2.0","id":2,"result":{"sessionId":"s1"}}
{"jsonrpc":"2.0","id":3,"method":"session/prompt","params":{"sessionId":"s1","prompt":[{"type":"text","text":"Explain ACP in one sentence."}]}}
{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"s1","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ACP defines how interactive clients communicate with coding agents."}}}}
{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}

id 关联请求和响应，sessionId 标识 Session，二者承担不同职责。完整实现还需处理错误、取消和资源生命周期。v1 Schema

ACP 如何表达 Agent 的工作过程

Tool Call、进度与代码差异

Agent 可以报告 Tool Call 的标识、标题、类别、状态、输入和输出。状态包括 pending、in_progress、completed 和 failed，结果还可以包含代码差异及文件位置。

这些通知报告执行活动。Client 收到 tool_call，不代表应该自动执行一个同名工具。工具由 Agent 编排，必要时再使用 Client 提供的能力。结构化事件让界面能够准确更新工具卡片或定位改动，而不必从终端文本中猜测状态。Tool Calls

v1 的文件与终端接口

v1 提供可选的 fs/read_text_file 和 fs/write_text_file。读取内容可以包含编辑器里尚未保存的修改，这解决了磁盘文件与用户当前看到的内容不一致的问题。Client 代为写入，也便于跟踪变更。

终端能力覆盖创建命令、读取输出、等待退出、终止和释放资源。命令可以在创建后继续运行，Agent 按需查询输出并清理终端。File System、Terminals

这些接口需要能力协商。Agent 也可能使用自己的文件与命令工具，不能假设所有操作都会经过 Client。

内容、计划与会话配置

ACP 内容模型支持文本、图片、音频、资源链接与嵌入资源。图片、音频和嵌入上下文等输入需要相应能力支持。Client 可以把 Agent 无法直接访问的文件内容随任务发送，例如通过编辑器中的文件引用提供上下文。Content

协议还支持执行计划、可用斜杠命令和 Session 配置。当前 v1 推荐通过 configOptions 暴露模型、模式、推理级别等选项，Client 据此生成选择界面；旧 modes 接口用于向后兼容。Session Config Options

取消与资源清理

用户取消任务时，v1 Client 发送 session/cancel 通知。Agent 随后仍需结束原始 prompt 请求并报告取消结果，Client 也要结束待决的权限交互。

取消涉及模型请求、工具执行和资源清理。取消通知不会撤销已经发生的文件修改或外部操作；通用请求取消及其向嵌套活动的传播，也需要按规范和实现支持分别处理。Prompt Turn、Cancellation

ACP 与 MCP、LSP、A2A 怎样配合

这些协议的设计重心不同，可以出现在同一套系统中。

这里列的是设计重心，不是绝对互斥的边界。MCP 也包含向用户请求信息的机制，A2A Client 也可以是普通应用。LSP、MCP Architecture、A2A Core Concepts

ACP 与 MCP 尤其适合组合：

开发者 → 编辑器 / ACP Client
              │ ACP：任务、进展、权限
              ▼
          Coding Agent
              │ MCP：工具、资源、上下文
              ▼
          MCP Server

Client 可以把 MCP Server 配置传给 Agent，由 Agent 直接连接；编辑器也可以把自身工具暴露为 MCP Server。

ACP 尽量复用 MCP 内容类型，但类型复用不意味着两种协议可以直接互换，也不意味着实现 ACP 就自动支持所有 MCP 服务。MCP 的连接与工具调用仍需要 Agent 自身实现。ACP Architecture

哪些场景适合 ACP

在熟悉的编辑器里切换 Agent

开发者可以围绕任务选择 Agent，同时保留已有快捷键、代码导航与审查流程。这适合尝试不同 Coding Agent，也适合团队保留多种工具选择。实际功能取决于 Client、Agent 和适配器共同支持的能力。

为自研 Agent 提供成熟界面

团队开发内部 Agent 时，可以通过 ACP 接入现有编辑器，把工作集中在代码检索、领域工具与执行策略上。例如，一个针对大型 Java 仓库的迁移 Agent，可以实现自己的分析和修改能力，由 Client 展示进度、差异与权限交互。

构建多 Agent 工作台

统一接口便于工作台管理多个 Agent 的 Session，复用消息、工具和差异组件。任务拆分、协作策略、共享文件冲突及失败恢复，仍需要工作台或 Agent 系统实现，ACP 提供共同的接入基础。

扩展到其他交互应用

Client 可以是终端界面、桌面工作台或其他应用。官方列表已经包含 Obsidian 等知识管理工具的插件，表明生态正在向代码编辑器以外扩展。Clients

生态现状：Client、Agent、Registry 与 SDK

Client 的接入形态

官网名单同时包含直接实现、连接器及相关工具，不是一份功能完全一致的兼容性认证。选择组合时应检查具体项目的支持范围。官方 Clients 列表

原生模式与适配器

Gemini CLI、OpenCode 等提供自身的 ACP 运行模式。例如，当前官方文档给出的命令分别是 gemini --acp 和 opencode acp。Gemini CLI ACP mode、OpenCode ACP

另一些 Agent 通过适配器接入：适配器把 ACP 请求转换为底层调用，再将执行事件转换回来。当前生态提供 Claude Agent 与 Codex 的 ACP 适配器。使用时需要同时检查底层 Agent 和适配器对权限、取消、历史恢复及事件转换的支持。Agents、Claude Agent adapter、Codex adapter

Registry 解决发现与安装

ACP Registry 于 2026 年 1 月上线，为 Client 提供 Agent 元数据和分发信息，支持发现与自动安装。协议规定怎样通信，Registry 帮助用户找到并启动实现。

Registry 是经过筛选、包含支持认证 Agent 的目录。收录本身不能证明所有 Agent 的能力或安全属性一致。Registry、Registry 发布公告

SDK 与扩展机制

官方目前提供 TypeScript、Python、Rust、Kotlin 和 Java 库。TypeScript SDK 当前推荐 agent() 和 client() 入口，早期示例常用的 AgentSideConnection、ClientSideConnection 已标记弃用。新集成应以所用版本的官方示例为准。TypeScript SDK

实现特有的数据可以放进允许的 _meta，自定义方法以 _ 开头，并通过扩展能力声明支持范围。规范对象的根字段保留给后续标准演进，不能随意插入私有字段。工程上应让基础功能不依赖私有扩展，否则会重新形成只能特定组合互通的关系。Extensibility

实践：把 OpenCode 接入 Zed

下面采用当前 OpenCode 官方接入示例。前提是已经安装 OpenCode 与 Zed，并具备可用的模型服务账号或配置。先在终端完成提供商认证：

opencode auth login

在 Zed 的 ~/.config/zed/settings.json 中合并以下配置，保留其他已有设置：

{
  "agent_servers": {
    "OpenCode": {
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

在 Zed 的 Agent 界面选择 OpenCode 并创建对话后，Zed 会启动 opencode acp 子进程。OpenCode 官方文档当前将这一路径描述为 v1、stdio 实现，协议连接不额外打开 ACP 网络端口。OpenCode ACP

如果图形 Client 找不到命令，把 command 改为 which opencode 返回的绝对路径。直接在终端运行 opencode acp 时，它会等待标准输入上的协议消息，看起来没有响应并不表示故障。需要调试时，可用 opencode --print-logs acp 将日志输出到 stderr。排障说明

接入后可以用一个小任务检查实际行为：发送带文件上下文的提问，观察消息和工具状态；允许一次受控修改并检查差异；在执行过程中取消，确认界面结束等待且没有遗留权限请求。本次核对了官方配置和命令，未使用真实账号进行端到端实测。

安全模型：权限交互怎样落实为约束

ACP does not sandbox an Agent. The Agent’s effective authority comes from its process and execution environment. Security Considerations

session/request_permission 让 Agent 向用户询问是否允许操作。对于 Agent 自己执行的工具，这种许可机制依赖 Agent 尊重用户决定；拥有文件访问权限的恶意进程，不会仅因界面上的拒绝按钮自动失去操作系统权限。

由 Client 执行文件或终端操作时，也必须校验路径、访问范围和权限。Agent 发来的许可请求不能替代这些检查。

此外，Agent 输出的 Markdown、路径、URI、工具结果和重放历史都应按不可信输入处理。Client 渲染内容时需要清理或禁用原始 HTML，不自动执行主动内容；agentInfo 等自报信息也不能作为安全身份凭据。适配器位于通信链路中，能够接触协议消息，同样属于信任边界。官方安全规范

企业部署可以用 ACP 统一权限交互，但真正的隔离仍需结合容器、受限文件系统、网络策略和凭证管理落实。

当前成熟度与 v2 Draft

截至整理日期，官网明确区分 v1 Latest 和 v2 Draft。已有 Client、Agent、Registry 和多语言 SDK，说明 ACP 已经具备现实中的本地集成基础。工程落地仍需要关注可选能力、适配器差异、版本兼容和远程部署边界。当前文档入口

v2 正在调整执行模型

v2 涉及核心生命周期变化，不能只把初始化版本号从 1 改成 2。

v2 还强化了对未知枚举值和变体的前向兼容。Agent 自己的终端输出可以作为展示能力存在，与被移除的 Client 终端执行接口需要区分。

v2 整体仍是 Draft；迁移文档提到的 baseline schema 也不表示整个版本已稳定。官方建议保留 v1，对每个连接明确协商版本，在稳定前用功能开关控制 v2 的启用。Migrating from v1

远程场景还在推进

远程部署需要处理认证、断连恢复、工作区和执行环境等问题。官方已介绍远程方向，但完整支持仍在推进。评估云端 Agent 时，应核对所用传输的具体规范与实现，不能从“可自定义传输”推导出所有 Client 已能互通。Introduction、Transports

兼容性需要实际检查

除了正常对话，还应检查初始化、能力缺省、错误、取消、断连与历史重放。官方提供 acp-tck，可以驱动 stdio Agent 检查部分协议行为，但它仍是实验性工具，覆盖范围不完整，通过也不构成官方兼容性认证。Testing

怎样判断是否值得接入

如果目标是让 Coding Agent 进入多个交互 Client，或者让一个 Client 支持多个 Agent，ACP 值得优先评估。若只是调用一次模型 API，或主要处理服务之间的任务委派，则应先明确需求位于哪一层，再选择相应接口。

可以围绕一条真实工作流评估：创建 Session，发送带代码上下文的任务，执行工具，处理权限，展示差异，中途取消，再恢复历史。这能够检查双方是否在关键行为上形成一致，而不仅是交换合法 JSON。

对 Agent 开发者，ACP 提供复用 Client 体验的机会；对 Client 开发者，它提供连接不同 Agent 的共同接口；对使用者，直接收益是保留工具选择的空间。后续价值取决于这些接口能否在更多实现之间保持可靠的一致性：换一个 Agent 后，仍然能够理解进度、审查改动并控制任务执行。

关联阅读

• Agents 栏目导航：查找相关 Agent、工作流和协议研究。
• Pi Agent 框架架构：包边界、Agent Loop 与接入选择：进一步区分模型接口、执行循环与不同接入层。
• OpenUI：概念、使用方式与 Generative UI 方案比较：从界面生成角度对照交互与协议的职责。