ACP(Agent Client Protocol)：AI 智能体与客户端/编辑器通信协议架构及应用简介

一、为什么会出现 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 询问用户是否允许
   • 通过 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）验证收益，再逐步推广。

九、相关参考

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