ACP 协议详解：让任何编辑器连任何 Agent 的"JSON-RPC 粘合层"，怎么用

MCP 解决"agent 连工具"，ACP 解决"agent 连人"——这两块拼图终于凑齐了。

AI coding agent 和编辑器的耦合问题，比你想象的更浪费：每个编辑器要为每个想支持的 agent 写定制集成，每个 agent 要实现各家编辑器的私有 API 才能触达用户。结果是 N×M 的集成矩阵、有限的兼容性、和"选了 agent 就被锁死在它的界面里"的锁定效应。

ACP（Agent Client Protocol） 由 Zed 发起，解法一句话：为编辑器和 agent 之间的通信立标准，就像 LSP 当年标准化了语言服务器集成。agent 实现了 ACP，就能接任何兼容编辑器；编辑器支持 ACP，就接入了整个 agent 生态。两边独立创新，开发者自由组合。

生态已经起来：协议仓库 4,359 stars，40+ 个 agent 宣布支持（Claude Code、Codex CLI、Gemini CLI、Cursor CLI、GitHub Copilot、Qwen Code、Kimi CLI、OpenCode……），客户端覆盖编辑器/CLI/桌面/移动/消息平台。这篇文章讲清楚 ACP 是什么、怎么工作、以及三种上手方式。

本文提纲

1. ACP 是什么：与 MCP 的关系
2. 架构：JSON-RPC over stdio
3. 核心流程：Prompt Turn 生命周期
4. 协议能力全景：v1 到 v2
5. 生态现状：40+ agents 与客户端
6. 三种上手方式

ACP 是什么：与 MCP 的关系

先摆正 ACP 在协议版图里的位置。

MCP（Model Context Protocol） 解决的是"模型/agent 如何连接工具和数据"——agent 到外部世界的通道。ACP 解决的是"用户如何连接 agent"——agent 到人的通道。两者是正交的拼图，而且 ACP 明确"在可能的地方复用 MCP 的 JSON 表示"。

ACP 的三条设计原则（官方 architecture 文档）：

1. MCP-friendly：协议基于 JSON-RPC，尽可能复用 MCP 类型，集成者不需要为常见数据类型再造一套表示。
2. UX-first：专为"与 AI agent 交互的 UX 挑战"设计——足够灵活以清晰渲染 agent 的意图（比如显示 diff），又不过度抽象。
3. Trusted：ACP 的场景是"你在编辑器里和信任的模型对话"——你仍然控制 agent 的工具调用，编辑器给 agent 访问本地文件和 MCP 服务器的能力。

文本格式上，用户可读内容默认用 Markdown——足够表达富格式，又不要求编辑器会渲染 HTML。

架构：JSON-RPC over stdio

ACP 的连接模型分两种：

• 本地 agent：作为编辑器的子进程运行，通过 stdio 上的 JSON-RPC 通信。这是当前的主流形态。
• 远程 agent：托管在云端或独立基础设施上，走 HTTP 或 WebSocket（官方注明：远程 agent 的完整支持仍在建设中）。

连接的要点：

• 按需启动：用户尝试连接 agent 时，编辑器按需启动 agent 子进程。
• 多会话：每条连接支持多个并发 session——可以同时有多个"思路列车"在跑。
• 双向请求：大量使用 JSON-RPC notification 让 agent 向 UI 实时流式更新；也用 JSON-RPC 的双向请求让 agent 反向请求编辑器做事——典型例子是请求工具调用的权限。
• MCP 联动：编辑器转发用户 prompt 时，把用户配置的 MCP 服务器信息一并传给 agent，agent 直连这些 MCP 服务器。编辑器自己想导出 MCP 工具时，走一个小代理把请求隧道回自己——MCP 和 ACP 不挤同一个 socket。

核心流程：Prompt Turn 生命周期

ACP 的核心概念是 prompt turn——从用户消息开始、到 agent 完成响应为止的完整交互周期（中间可能有多轮 LLM 交换和工具调用）。前置要求：先完成 initialization（初始化 + 认证）和 session setup（创建/加载会话）。

一轮 prompt turn 的流程（协议的时序语义）：

1. 客户端发 session/prompt（用户消息）。
2. Agent 处理过程中持续发 session/update 通知——这是协议的信息流主干，variant 覆盖：

3. 需要权限时，agent 发 session/request_permission，用户批准/拒绝后 agent 继续。
4. 用户可随时 session/cancel 中止本轮。
5. 完成时，session/prompt 的响应带 stopReason（正常结束/取消等）。

注意这个设计的信息对称性：agent 不只是给最终答案，思考块、计划、每次工具调用的状态流转、token 用量全部作为结构化事件流给客户端——编辑器拿到的是完整的"agent 在干什么"的实时画像，而不是一段黑盒文本。这也是 UX-first 原则的落点。

协议能力全景：v1 到 v2

协议已迭代到 v2（v1 文档并行保留，官方提供了完整的 v1→v2 迁移指南）。能力面覆盖：

• 初始化与认证：连接建立、认证方式协商、登出。
• 会话管理：创建/加载/列举/删除会话（会话可持久化）。
• Prompt 生命周期（v2 将 prompt turn 拆成独立文档）。
• 内容块：文本/图像/资源等类型。
• 工具调用：创建、状态流转、权限请求。
• Elicitation：agent 请求用户提供结构化信息。
• 文件系统：client 端文件系统访问方法。
• 终端：执行和管理终端命令。
• Agent Plan：agent 向客户端同步执行计划。
• Session Modes / Config Options：会话模式切换（如"规划/执行"模式）与配置选择器。
• Slash Commands：agent 向客户端广播可用的斜杠命令。
• Extensibility：自定义数据和能力的扩展机制。
• Transports：stdio / HTTP / WebSocket 传输层。
• Schema：完整 schema 定义。

生态现状：40+ agents 与客户端

ACP 的生态是它最有说服力的部分。协议规格由 agentclientprotocol/agent-client-protocol 维护（4,359 stars，Rust SDK），官方的多语言库覆盖 Python、Kotlin、Java、TypeScript。

Agent 侧（宣布支持的 40+），名字几乎覆盖全部主流：Claude Code（经 Zed 的 SDK 适配器 claude-agent-acp）、Codex CLI（经官方 codex-acp 适配器）、Gemini CLI、Cursor CLI、GitHub Copilot CLI（公测）、Qwen Code、Kimi CLI、OpenCode、Goose、Cline、OpenHands、Factory Droid、Kiro CLI、Mistral Vibe、Hermes Agent……

Client 侧分八类：编辑器与 IDE（Zed 打头）、CLI/TUI（acpx——3,308 stars 的 headless CLI client）、桌面与 Web（ACP UI，跨 Windows/macOS/Linux/iOS/Android）、笔记本数据工具、移动客户端、消息平台、框架、连接器。还有 ACP Registry——查找和安装 ACP 兼容 agent 的注册中心。

一句话：agent 侧已经卷起来了——因为接上 ACP 意味着一次集成、全编辑器可达。

三种上手方式

方式一：作为用户——在编辑器里接一个 agent

以 Zed 为例：配置里指定 agent 命令（如 Gemini CLI 或经 claude-code-acp 适配的 Claude Code），编辑器自动启动子进程、走 ACP 通信。你不是 Zed 用户也没关系——acpx 这类 headless CLI 可以在终端里跑 ACP 会话，或选任何已支持 ACP 的客户端。

方式二：作为 agent 开发者——让你的 agent 说 ACP

两条路：直接实现协议（JSON-RPC over stdio，按 schema 实现 initialize/session/prompt 各方法）；或用官方 SDK（Python/Kotlin/Java/TypeScript）省掉协议细节。已有 agent 的最快路径是适配器模式——Codex CLI 和 Claude Code 都是通过官方适配器（codex-acp、claude-code-acp）接的 ACP，没有改自家核心。

方式三：作为编辑器/客户端开发者——接入 agent 生态

用 Rust/TypeScript SDK 实现客户端侧：按需启动 agent 子进程、转发 MCP 配置、处理 session/update 事件流渲染 UI、实现权限请求的交互。Zed 的实现是现成参考。

参考链接

• ACP 官网 - 协议文档站（含 llms.txt 索引）
• GitHub: agentclientprotocol/agent-client-protocol - 协议规格与 Rust SDK，4,359 stars
• 架构文档 - 设计原则与 MCP 联动
• Prompt Turn 文档 - 核心交互流程
• GitHub: zed-industries/claude-code-acp - Claude Code 的 ACP 适配器，2,601 stars
• GitHub: openclaw/acpx - headless CLI client，3,308 stars
• ACP Agents 列表 - 40+ 兼容 agent
• 我的 MCP 设计最佳实践 - MCP 侧的配套设计方法

你的编辑器和 agent 锁死了吗？会考虑走 ACP 这条路吗？评论区聊聊你的组合，觉得有用点个赞让更多开发者看到这个协议。

作者: itech001 来源: 公众号：AI人工智能时代(the-ai-era) 网站: https://www.theaiera.top/ 关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

本文首发于 AI人工智能时代，转载请注明出处。