ACP(Agent Client Protocol)：智能体客户端协议架构及应用简介

一、为什么会出现 ACP？

——AI 编码时代的新“统一接口”问题

近两年，AI 编码助手爆发式增长：GitHub Copilot、Claude Code、Gemini CLI、OpenHands、Qwen Code、Kimi CLI、OpenCode……但开发体验却愈发割裂：

- 每个编辑器都要为每一个 AI 助手写一套插件：VS Code 一套、JetBrains 一套、Neovim/Emacs 再一套
- 每个 AI 助手也要为不同编辑器分别适配：维护成本高、功能还不统一
- 一旦后端 API 或交互模式升级，前端插件全部要跟着改

这和 **LSP 出现之前的“语言服务碎片化”** 极其相似：

在 LSP 之前，各 IDE 需要分别为每种语言写语法高亮、补全、跳转的实现。LSP 把“语言服务”抽象出来统一标准，极大降低了集成成本。

在 AI 编码时代，我们遇到的是类似但更复杂的问题：

> 如何让“任意编辑器”可以连接“任意 AI 编码代理”，而不是被某一家厂商的“编辑器+AI”捆绑？

**Agent Client Protocol（ACP）正是为此而生。**

二、ACP 是什么？和 IBM 的 ACP 有何不同？

2.1 定义：Agent Client Protocol（Zed 社区主推）

**Agent Client Protocol（ACP）** 是一个基于 **JSON-RPC 2.0** 的开放协议，用来标准化：

- 客户端（Client）：编辑器 / IDE / 终端 UI / 桌面应用
- 代理（Agent）：具备代码理解、生成、重构能力的 AI 编码代理（往往基于大模型 + 工具调用）

之间的通信方式与语义。

一句话概括它的目标：

> 让 任何编辑器 都可以无缝连接 任何 AI 编码代理，就像 LSP 统一语言服务那样，统一 AI 编码体验。[1][2]

2.2 注意不要和 IBM 的 ACP 混淆

当前“ACP”有两条主线，需要明确区分：

| 名称 | 全称 | 核心对象 | 典型场景 |
|---|---|---|---|
| Agent Client Protocol | Agent Client Protocol（Zed） | 编辑器 / IDE ↔ AI 编码代理 | Zed、JetBrains、Neovim、桌面应用连接 Gemini CLI、Claude Code、OpenHands 等 |
| Agent Communication Protocol | Agent Communication Protocol（IBM 等） | Agent ↔ Agent、应用 ↔ Agent | 多智能体之间通信、跨系统编排 |

本文中如不特别说明，**“ACP”均指 Zed 社区主导的 Agent Client Protocol。**

三、从 0 开始理解 ACP：架构与消息模型

3.1 整体架构：谁是 Client，谁是 Server？

在 ACP 中：

- Client = 编辑器 / UI 端

掌握本地文件系统、终端、权限确认 UI

**Server = AI 代理**

- 掌握大模型推理、代码生成、工具编排能力

典型架构如下：

+---------------------------+       JSON-RPC (stdio/pipe/TCP)       +------------------------+
|  Editor / IDE / GUI      |  <------------------------------->    |  Coding Agent (ACP)    |
|  (Zed / JetBrains /      |                                      |  (Gemini CLI /         |
|   AionUi / Open Cowork)  |                                      |   Claude Code / etc.)  |
+---------------------------+                                      +------------------------+
         ↑                                                                           ↑
         |  提供：文件系统、终端、权限 UI                                         |  执行：分析、规划、生成代码
         |                                                                           |
    人机交互 & 环境层                                                         智能决策 & 执行层

这种划分有两个关键好处：

1. 安全：代理不直接“裸奔”访问本地文件与终端，一切都走 Client 提供的受控接口 + 权限确认
2. 可组合：代理可以是本地 CLI 工具，也可以是远程服务，只要说“ACP 这门语言”就能挂载到各种编辑器 / 桌面 UI 上

3.2 消息模型：基于 JSON-RPC 2.0

ACP 严格遵守 JSON-RPC 2.0 标准，[3] 把所有交互规范化为两类消息：

1. Request / Response（请求-响应）
2. Notification（通知，无需响应）

**请求示例：initialize**

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "clientInfo": {
      "name": "Zed",
      "version": "0.202.0",
      "capabilities": {
        "fs": {
          "readTextFile": true,
          "writeTextFile": true
        },
        "terminal": true
      }
    }
  }
}

**响应示例：initializeResult**

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "agentInfo": {
      "name": "Gemini CLI",
      "version": "1.3.0"
    },
    "capabilities": {
      "loadSession": true,
      "modes": ["chat", "edit"]
    }
  }
}

**通知示例：session/update（流式输出）**

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "abc-123",
    "updates": [
      { "type": "messageChunk", "role": "assistant", "content": "正在分析你的项目结构…" }
    ]
  }
}

3.3 一次完整交互的“生命周期”

从编辑器视角看，一次使用 AI 的完整流程可以拆解为 4 步：

1. 初始化

- initialize：能力协商（双方是谁、都能干什么）
2. 会话建立

- session/new：新建会话
- session/load：加载旧会话（取决于代理是否声明支持）
3. 对话 & 操作过程

- session/prompt：发送用户请求（附上下文）
- 代理通过 session/update 持续推送计划、生成内容、进度
- 用户或编辑器可发送 session/cancel 终止
4. 工具调用 & 权限

- 当代理需要读写文件或执行命令时：

通过 session/request_permission 请求授权
- 由 Client 通过 UI 询问用户是否允许
5. 通过 fs/*、terminal/* 调用具体能力

这个生命周期在多个实际产品中被一再验证，例如 Gemini CLI、Claude Code、OpenHands 与 JetBrains / Zed / AionUi 的集成。

3.4 扩展机制：既要“统一”，也要“生长”

为了避免重蹈“一上新功能就得改协议核心”的覆辙，ACP 提供了类似 LSP 的扩展能力：

- 自定义方法：以 _ 前缀区分实验 / 私有扩展，例如 _symmacp/pipeline
- 扩展元数据：统一放在 _meta 中，避免污染主结构
- 能力声明：所有扩展在 initialize 里通过 capabilities 广而告之

这保证了：

- 主协议稳定，可长期演化
- 厂商 & 社区可以在不破坏兼容性的前提下进行创新

四、开发者视角：如何把自己的工具“接上 ACP 总线”？

4.1 生态中的官方 SDK

为了降低接入门槛，ACP 提供了多语言 SDK，封装了：

- 面向协议的 Pydantic / struct 类型模型（防止字段乱写）
- 基于 asyncio / async 的传输和消息收发
- Agent / Client 抽象基类，简化实现过程

目前主流语言支持包括[2][4]：

| 语言 | SDK 包名 |
|---|---|
| Python | agent-client-protocol |
| Rust | agent-client-protocol |
| Kotlin | acp-kotlin |
| TypeScript | @agentclientprotocol/sdk |

4.2 用 Python 写一个最简 ACP Agent 的思路

下面是一个抽象化的示例（简化版，帮助你快速建立直觉）：

from acp import Agent, schema
import asyncio

class SimpleAgent(Agent):
    async def initialize(self, params: schema.InitializeParams) -> schema.InitializeResult:
        """处理初始化请求"""
        return schema.InitializeResult(
            agentInfo={"name": "simple-agent", "version": "0.1"},
            capabilities={"loadSession": False}
        )

    async def session_new(self, params: schema.SessionNewParams) -> schema.SessionNewResult:
        """创建新会话"""
        return schema.SessionNewResult(sessionId="session-1")

    async def session_prompt(self, params: schema.SessionPromptParams) -> schema.SessionPromptResult:
        """处理用户请求"""
        await self.send_session_update(
            schema.SessionUpdateParams(
                sessionId=params.sessionId,
                updates=[schema.MessageChunk(type="messageChunk", content="思考中…")]
            )
        )

        return schema.SessionPromptResult(
            stopReason="completed",
            response=f"Echo: {params.prompt}"
        )

if __name__ == "__main__":
    agent = SimpleAgent()
    asyncio.run(agent.serve_stdio())  # 通过 stdio 与 ACP 客户端通讯

然后你只需在 Zed / JetBrains / AionUi 的配置里，写上类似：

{
  "agent_servers": {
    "My Simple Agent": {
      "command": "python",
      "args": ["-m", "my_simple_agent_module"]
    }
  }
}

即可把你的 Agent 挂到对应 IDE 里使用。

4.3 如果你是“编辑器 / UI”开发者，该做什么？

你需要实现一个 **ACP Client** 层，其职责包括：

1. 启动 Agent 进程：按用户配置执行 command + args
2. 维护 JSON-RPC 连接：通过 stdio / socket 读写 NDJSON 流
3. 协议调度：

- 框架层统一处理 initialize、session/new、session/prompt 等
- 将 session/update 映射到 UI：流式输出、Patch 展示、权限弹窗
4. 能力适配：

- 把 IDE 的文件 API 映射为 ACP 的 fs/* 方法
- 把内置终端映射为 terminal/* 方法

JetBrains 在 2025 年底发布的 ACP 支持，就是经典示例：整个 IDE 家族（IntelliJ、GoLand、PyCharm 等）只需实现一次 ACP Client，就可以同时接入 Gemini CLI、Claude Code、OpenHands 等多种 Agent。[5]

五、从“能用”到“好用”：实际应用实践和案例

这一部分我们按照“使用者角度”来拆解，从桌面应用、IDE 编辑器、CLI Agent 三个维度看 ACP 的实战落地。

5.1 桌面端“多 Agent 工作台”：AionUi

**AionUi 是什么？**

- 一个免费、开源的跨平台桌面 GUI，最初是 Gemini CLI 的本地 UI
- 后来加入了 Multi-Agent 模式，通过 ACP 把各种 CLI Agent 接在一起，变成一个本地“Cowork 工作台”[6]

**和 ACP 的关系**

- AionUi 自身实现的是 ACP Client
- 它可以识别并连接本机上任何 ACP 兼容的 Agent CLI，例如：

Claude Code (claude)
- Qwen Code (qwen --acp)
- OpenCode (opencode acp)
- Goose (goose acp)
- Augment Code (auggie --acp)
- Kimi CLI (kimi --acp)
- 以及后续持续增加的社区 Agent

**用户体验上，你能获得什么？**

- 在一个统一的 GUI 里：

用 Gemini 跑分析
- 用 Qwen Code 改代码
- 用 OpenCode 做大规模重构

当 Agent 需要读写文件、运行命令时，AionUi 会按 ACP 协议弹出权限确认窗口
所有对话、任务状态都持久化到本地，重启后可恢复

对于想要“本地版本 Claude Cowork / Copilot Workspace”体验，但又不想被单一厂商锁死的人来说，**AionUi + ACP** 是一个非常现实可行的路径。

5.2 基于 Electron + React 的 Open Claude Cowork

社区中有多个“Open Claude Cowork / Open Cowork”项目，其中有一支路线明确是 **以 ACP 为底层协议**，用 Electron + React 做桌面端多 Agent 协作工具。[7]

其核心设计可以概括为四个类：

- AcpDetector：扫描本地可用 CLI（如 claude, qwen, opencode acp 等）
- AcpAgentManager：管理多个 Agent 实例、连接复用
- AcpAgent：封装会话级逻辑（initialize → newSession → prompt），支持 @file 语法引用文件
- AcpConnection：与具体 Agent 的 JSON-RPC 底层连接，基于 NDJSON 流

**关键能力：**

- 多 Agent 并行，在一个 UI 中管理多个“项目任务”
- 使用 SQLite 做任务 / 会话的持久化存储，重启后可继续协作
- 对 ACP 中的权限请求进行 UI 弹窗拦截，增加超时和取消机制

可以把它理解为：

> 用 ACP 把一堆不同厂家的“Claude Code 类工具”挂载到一个本地桌面端，统一操作、统一审计、统一安全策略。

5.3 IDE 编辑器：Zed & JetBrains & Neovim & Emacs

**Zed** 作为 ACP 的发起方，[1][2] 是最早一批内置 ACP Client 的编辑器：

- 在 settings.json 中配置 agents 和命令，即可连接任意本地 ACP Agent
- 支持多个 Agent 并行挂载：如 “Gemini CLI + Claude Code + OpenHands” 同时在线

**JetBrains** 则在 2025 年底正式宣布与 Zed 联合推动 ACP，并在其全家桶 IDE 中上线支持[5]：

- 在 AI 设置中，除了官方 AI Assistant 外，还多了 “ACP Agent” 选项
- 用户可以选择本地命令作为后端，例如：

opencode acp
- kimi --acp
- qwen --acp

**Neovim / Emacs / Obsidian / Marimo 等** 通过各自的插件，也实现了 ACP Client 能力：

- Neovim：如 codecompanion.nvim，通过 <leader>a 触发 ACP 会话
- Emacs：agent-shell，以子进程方式挂载 ACP Agent
- Obsidian：在笔记中选中代码块直接交给 ACP Agent 处理
- Marimo：将 ACP Agent 的输出映射为 Notebook 单元

这些集成的共同点是：

1. 一次实现 ACP Client → 后续可“插拔”任意 ACP Agent
2. 对 Agent 的交互能力高度一致：

- Chat 面板、内联编辑、带解释的重构操作
- 执行测试 / 命令、展示文件改动 diff

5.4 Agent / CLI 侧的 ACP 实现

目前已经宣布支持 ACP 的 Agent / CLI 工具有：

- Gemini CLI：官方参考实现（Zed 首批集成对象）
- Claude Code：通过 claude-code-acp（TS 实现）或社区的 Rust 版本[8]
- OpenHands：openhands acp，可将复杂的多步骤开发任务抽象为一个 ACP Agent
- clawdbot(Moltbot): 一款开源的、本地优先（Local-First）的个人 AI 助手。其核心理念是让 AI 真正“驻留”在你的设备或私有服务器上，并通过你日常使用的通讯软件（如 WhatsApp, Telegram, Discord, Slack 等）为你提供服务。
- Goose、Augment Code（Auggie）、Qwen Code、Kimi CLI、OpenCode 等

典型用法往往类似：

# 启动一个 ACP server
qwen --acp
opencode acp
kimi --acp
goose acp
clawdbot acp

然后在任何 ACP 客户端（Zed / JetBrains / AionUi / Open Cowork / Toad）中把对应命令填进去即可。

六、如何在团队中落地 ACP？实战建议

假设你所在团队有两个诉求：

1. 想在公司主力 IDE 中统一引入各种 AI 编码助手
2. 想把自研的代码 Agent 提供给团队成员使用

我们可以按照“编辑器团队”和“Agent 团队”两侧来规划。

6.1 如果你负责“编辑器 / 内部开发工具”

**短期目标（1–2 个月）：做一个最小可用的 ACP Client 集成**

- 选一个编辑器或内部 Web IDE 作为试点
- 引入 TypeScript / Kotlin ACP SDK
- 实现最基本的：

initialize / session/new / session/prompt
- 接入 session/update → 将文本流显示到一个简单的 Chat 面板

配置 1–2 个现成 Agent（如 gemini acp、opencode acp）验证全链路

**中期目标（3–6 个月）：扩展到“生产可用”**

- 接入文件能力：实现 fs/read_text_file / fs/write_text_file 映射到项目文件树
- 接入终端能力：实现 terminal/* 映射到 IDE 内置终端
- 实现权限模型：

所有写文件 / 执行命令必须弹窗确认
- 提供“一次性允许 / 本会话允许 / 永久允许”选项

引入多 Agent 支持：有选择地接入 Claude Code、Qwen Code、OpenHands 等

**长期目标：内部 AI 平台对接**

- 在 IDE 侧只负责 ACP Client
- 把企业内部的 AI 编码平台封装成一个或多个 ACP Agent Server，对内统一暴露
- 通过组织级策略控制：

哪些项目可用哪些 Agent
- 哪些目录可被 Agent 读写

6.2 如果你负责“Agent / 智能体平台”

**第一步：把现有 Agent 封装成 ACP Server**

- 选用合适的 SDK（Python / Rust）
- 在现有业务逻辑外包一层：

实现 initialize，声明你的能力（是否支持 loadSession、支持哪些模式）
- 实现 session/new / session/prompt，将用户意图映射到你的内部工作流

如果 Agent 需要访问文件 / 终端：

- 改为通过 ACP 的 fs/*、terminal/* 间接访问，而不是直接用 os / subprocess

**第二步：写好文档和示例配置**

- 提供针对 Zed / JetBrains / AionUi / Neovim 的示例配置片段
- 明确说明：

启动命令
- 需要的环境变量（如 API Key、代理配置）
- 支持的模式（chat / edit / refactor / test 等）

**第三步：企业内推广**

- 把 ACP 集成纳入内部 IDE / Web IDE 的“官方支持列表”
- 从一个“高价值用例”切入（例如：安全审计 Agent 或重构 Agent），而不是泛泛聊天

七、小结：ACP 在整个智能体协议版图中的位置

如果我们把当前 Agent 相关协议做一个“分层”梳理，大致如下：

+---------------------------------+
| 应用层（IDE、桌面端、业务系统 UI） |
+---------------------------------+
| Agent Client Protocol (ACP)     | ← 本文主角：UI ↔ 编码 Agent
+---------------------------------+
| MCP / 其它 Tool 协议           | ← Agent ↔ 工具 / 数据源
+---------------------------------+
| A2A / IBM ACP / 自定义协议      | ← Agent ↔ Agent
+---------------------------------+
| HTTP / TCP / stdio / NDJSON     |
+---------------------------------+

- MCP 解决“模型如何安全、统一地调用工具和数据源”
- A2A / IBM ACP 解决“Agent 与 Agent 之间如何协作”
- 而 ACP（Agent Client Protocol） 聚焦在一个非常垂直但极其重要的领域：

编辑器 / 开发环境 与 AI 编码 Agent 的通信

在“AI 原生开发体验”这条路径上，ACP 与 LSP 一样，很可能会成为一种 **长期存在的基础设施标准**：

- LSP：统一语言服务
- MCP：统一模型与工具
- ACP：统一 AI 编码 Agent 与编辑器

八、行动建议

如果你是个人开发者 / 工程师

- 尝试至少一个 ACP 客户端：

Zed / JetBrains 最新版本 / AionUi / Open Claude Cowork / Neovim + ACP 插件

尝试接入两个以上不同厂商的 Agent：

- 例如：Qwen Code（国产）+ OpenCode（开源）+ Gemini CLI（国际云厂商）

在实际项目中用 ACP Agent 做几件具体事情：

- 迁移一个模块的架构
- 改造测试体系
- 做一次安全审计或性能分析

如果你是工具 / 平台开发者

- 评估把自研 Agent 封装成 ACP Server 的工作量（通常以周为单位）
- 优先选择一个场景做 MVP：例如“重构 Agent”或“CI 修复失败用例 Agent”
- 发布后主动适配：

写出 Zed / JetBrains / AionUi 的配置示例
- 在文档中标明 “ACP-compatible Agent”

如果你是架构师 / 技术负责人

- 将 ACP 视作“企业内 AI 开发体验标准化”的一个选项：

它不会取代 MCP / A2A，但在 IDE/开发工具这一层是最佳人选之一

从安全视角审查 ACP 的使用：

- 明确哪些目录可被 ACP Agent 访问
- 明确命令执行白名单 / 黑名单策略

鼓励团队用一个小范围试点（单个业务组 + 单一 IDE）验证收益，再逐步推广。

九、相关参考

- Agent Client Protocol. https://zed.dev/acp
- Overview – Agent Client Protocol. https://agentclientprotocol.com/protocol/overview
- JSON-RPC 2.0 Specification. https://www.jsonrpc.org/specification
- Agent Client Protocol - Python SDK. https://agentclientprotocol.github.io/python-sdk/
- Bring your own AI agent to JetBrains IDEs. https://blog.jetbrains.com/ai/2025/12/bring-your-own-ai-agent-to-jetbrains-ides/
- ACP Setup · iOfficeAI/AionUi Wiki. https://github.com/iOfficeAI/AionUi/wiki/ACP-Setup
- 基于Electron + React + ACP 的本地多Agent 协作桌面应用. https://juejin.cn/post/7599581687357571122
- Xuanwo/acp-claude-code. https://github.com/Xuanwo/acp-claude-code