跳转至

Agent Client Protocol (ACP)

概述

Agent Client Protocol（ACP，智能体客户端协议）是一项开放标准，最初由 Zed Industries 于 2025 年 8 月发布，用于规范代码编辑器（查看与编辑源代码的交互式程序）与编码智能体（使用生成式 AI 自主修改代码的程序）之间的通信。在 ACP 出现之前，每个编辑器要支持某个智能体，都得为它单独做一套定制集成，导致整个生态反复造同样的轮子。ACP 用单一接口取代这些一次性集成：任何兼容 ACP 的智能体都能在任何兼容 ACP 的编辑器中运行，无需定制胶水代码。

来源：Agent Client Protocol、agentclientprotocol/agent-client-protocol（GitHub）

核心概念 / 架构

传输与消息格式

  • 传输：通过 stdin/stdout 交换 JSON-RPC 2.0 消息（按行分隔的 JSON），通常由编辑器把智能体作为子进程启动。
  • 消息类型：请求（request）、响应（response）与通知（notification），遵循标准 JSON-RPC 语义。
  • 角色：Client（客户端）（即代码编辑器/IDE）与 Agent（智能体）（即编码智能体进程）。始终由 Client 启动并驱动连接；会话建立后，双方均可发送请求与通知。
  • 版本控制：线协议兼容性由初始化阶段协商的 protocolVersion 决定，而非由 SDK 或 crate 的发布版本号决定。当前稳定线协议为版本 1，各版本均发布 schema 产物（schema/v1、schema/v2 等），并作为 JSON Schema 文件附在 GitHub 发布中。

会话生命周期

  1. initialize —— Client 启动时发送，用于协商 protocolVersion 并交换能力声明（例如 Client 的 fileSystem 与 terminal 支持；Agent 的 modelSelector 与 loadSession 支持）。
  2. session/new —— 为一次交互（单个编辑/对话上下文）创建新会话。
  3. session/load —— 若 Agent 支持，则恢复先前创建的会话；Agent 会以一系列 session/update 通知把完整对话历史回放给 Client。
  4. session/prompt —— Client 在某会话内把一轮用户输入（提示）转发给 Agent。
  5. session/update —— Agent 在处理过程中流式回传给 Client 的通知，承载增量输出、工具调用状态，以及用于实时展示的推理/"思考"内容。

内容与工具调用

  • 内容块（Content Blocks）：以 Markdown 为主的富文本，支持图片、音频与资源引用。
  • 工具调用通过 session/update 通知上报给 Client，使编辑器能实时呈现进度。工具调用分为以下类别：read、edit、delete、move、search、execute、think、fetch。
  • 权限请求：当 Agent 想执行敏感操作（如编辑文件、运行命令）时，可通过 session/request_permission 经由 Client 向用户请求授权，而非自行放行——让人在回路把关高风险操作。
  • Client 提供的能力：Client 可暴露供 Agent 调用的原语，包括文件系统访问（fs/read_text_file、fs/write_text_file）与终端控制（terminal/create、terminal/output、terminal/wait_for_exit、terminal/kill、terminal/release）。这样文件与命令执行都留在用户的编辑器受控环境内，而无需 Agent 自管沙箱，由编辑器充当权限把关者。

与 MCP 的关系

ACP 与 模型上下文协议（MCP） 处理智能体技术栈的不同层面，二者互补而非竞争：

方面 ACP MCP
主要关系 编辑器（Client）↔ 编码智能体 LLM 应用（Host）↔ 工具/数据服务
标准化的内容 编辑器如何启动、驱动并呈现编码智能体的会话（提示、流式更新、工具调用展示、权限、文件/终端访问） LLM 应用如何发现并调用外部工具/资源
控制方向 Client（编辑器）是集成面，Agent 接入其中 Agent/Host 是客户端，MCP 服务向其暴露能力
典型用途 让编码智能体（Claude Code、Gemini CLI、Goose 等）无需为每个编辑器写胶水代码即可在任意 IDE 中使用 不论由哪个编辑器或运行时承载，都让智能体能访问外部工具与数据

实践中，同一个编码智能体可以一边用 ACP 与宿主编辑器通信，一边单独用 MCP 调用外部工具——两个协议作用于同一管线的不同环节。

生态与采用

  • 许可 / 治理：Apache License 2.0，无需 CLA（贡献自动按 Apache 2.0 授权）；治理与贡献流程见项目的 GOVERNANCE.md 与 CONTRIBUTING.md。
  • 官方 SDK：TypeScript（npm 上的 @agentclientprotocol/sdk）、Python（PyPI 上的 agent-client-protocol，Pydantic 模型，基于 asyncio）、Rust（crates.io 上的 agent-client-protocol / agent-client-protocol-schema）、Kotlin（acp-kotlin，JVM）与 Java。
  • 原生 Agent 实现（直接讲 ACP）：Gemini CLI（Google）、GitHub Copilot CLI（公开预览）、Goose、Cline、OpenHands、Mistral 的 Vibe、Auggie 与 Blackbox AI。
  • 基于适配器的实现：Claude Code 与 OpenAI 的 Codex CLI 通过适配器（而非原生支持）接入兼容 ACP 的编辑器。
  • 编辑器采用：起源于 Zed。2025 年 10 月，JetBrains 宣布与 Zed 合作共同开发 ACP，并为 IntelliJ IDEA、PyCharm 与 WebStorm 带来原生支持；随后 JetBrains 与 Zed 推出共享的 ACP Agent Registry——一个可在支持的 IDE 内发现并连接兼容 ACP 编码智能体的目录。
  • Google 构建了兼容 ACP 的 Gemini CLI，作为用于验证协议设计的首个外部集成。

最佳实践

挑战 / 领域 说明 方案 / 建议
逐个编辑器的智能体集成 传统上每新增一对"编辑器/智能体"都要写定制胶水代码 只需按 ACP 线协议实现一次，即可在任何兼容 ACP 的编辑器或智能体间复用
信任由智能体发起的文件/命令操作 智能体在用户不知情下执行编辑或命令存在安全风险 要求 Agent 把敏感操作（写文件、执行命令）经 session/request_permission 及 Client 暴露的 fs/* / terminal/* 能力路由，使编辑器始终是把关者
SDK 与线协议的版本漂移 crate/包的发布号与协议兼容性并非一一对应 依据 initialize 返回的 protocolVersion 协商并校验兼容性，而非靠 SDK 版本号判断
支持不原生支持 ACP 的智能体 一些流行编码智能体（如 Claude Code、Codex CLI）早于 ACP 使用或构建适配器，把智能体原生的 CLI/API 接口转译为 ACP 的 session/* 调用

参见

参考资料