概览
Agent Client Protocol 的工作原理
Agent Client Protocol 允许 Agent 和 客户端 通过暴露双方可调用的方法进行通信，并发送通知以告知对方相关事件。
通信模型
该协议遵循 JSON-RPC 2.0 规范，包含两种类型的消息：
- 方法（Methods）：请求-响应对，期望返回结果或错误
- 通知（Notifications）：单向消息，不期望收到响应
ACP 遵循 JSON-RPC 2.0 的批处理行为。有关批处理要求，请参阅 传输层。
消息流
典型的流程遵循以下模式：
初始化阶段
- 客户端 -> Agent：
initialize以建立连接 - 客户端 -> Agent：如果 Agent 要求，则执行
auth/login
会话设置 - 以下之一：
- 客户端 -> Agent：
session/new创建新会话 - 客户端 -> Agent：
session/resume恢复已有会话
提示生命周期
- 客户端 -> Agent：
session/prompt发送用户消息 - Agent -> 客户端：
session/prompt响应，确认提示已被接受 - Agent -> 客户端：
session/update通知，用于已接受的消息、状态更新和进度更新 - Agent -> 客户端：根据需要发送权限请求
- 客户端 -> Agent：
session/cancel在需要时中断处理 - Agent -> 客户端：当准备好接受新提示时发送空闲的
state_update，并在前台工作结束时附带停止原因
Agent
Agent 是使用生成式 AI 自主修改代码的程序。它们通常作为客户端的子进程运行。
基线方法
部分基线方法属于可选能力面。返回 authMethods 中一个或多个有效条目的 Agent 必须 同时实现 auth/login 和 auth/logout。如果 authMethods 被省略或为空，客户端 不得 调用这两个方法中的任何一个。
通知
客户端
客户端提供用户与 Agent 之间的接口。它们通常是代码编辑器（IDE、文本编辑器），但也可以是其他用于与 Agent 交互的 UI。客户端管理环境、处理用户交互，并控制对资源的访问。
基线方法
通知
session/updateSchema发送会话更新以通知客户端变更（不期望响应）。这包括消息更新和分块、工具调用、更新和内容分块、仅显示的终端状态和输出分块、计划、可用命令更新以及配置选项更新。
参数要求
- 协议中的所有文件路径 必须 为绝对路径。
- 行号从 1 开始计数
错误处理
所有方法遵循标准 JSON-RPC 2.0 错误处理：
- 成功响应包含
result字段 - 错误包含带有
code和message的error对象 - 通知永远不会收到响应（成功或错误）
约定
除非在 schema 中另有明确定义，ACP 定义的 JSON 对象属性键使用 camelCase。由判别字段承载的字符串值使用 snake_case。JSON-RPC 信封字段（jsonrpc、id、method、params、result 和 error）遵循 JSON-RPC 2.0 规范。部分选定的类枚举字段和标签联合可以定义自定义或未来回退值。对于这些字段，以 _ 为前缀的值保留给实现特定的扩展，而未知的非下划线值保留给未来的 ACP 变体。
可扩展性
协议提供了内置机制来添加自定义功能，同时保持兼容性：
- 使用
_meta字段添加自定义数据 - 通过在方法名前加下划线（
_）创建自定义方法 - 在初始化期间声明自定义能力
了解协议可扩展性以掌握如何使用这些机制。