Skip to main content
Agent Client Protocol 允许代理和客户端通过公开每一方可以调用的方法并发送通知来告知彼此事件，从而实现通信。

​
通信模型

该协议遵循 JSON-RPC 2.0 规范，包含两种类型的消息：
  • 方法：期望返回结果或错误的请求-响应对
  • 通知：单向消息，不期望响应

​
消息流

典型的流程遵循以下模式：
1

初始化阶段

  • 客户端 → 代理：initialize 建立连接
  • 客户端 → 代理：authenticate（如果代理需要）
2

会话设置 - 以下任一：

  • 客户端 → 代理：session/new 创建新会话
  • 客户端 → 代理：session/load 恢复现有会话（如果支持）
3

提示轮次

  • 客户端 → 代理：session/prompt 发送用户消息
  • 代理 → 客户端：session/update 通知进度更新
  • 代理 → 客户端：根据需要执行文件操作或权限请求
  • 客户端 → 代理：session/cancel 中断处理（如需要）
  • 轮次结束，代理发送包含停止原因的 session/prompt 响应

​
代理

代理是使用生成式 AI 自主修改代码的程序。它们通常作为客户端的子进程运行。

​
基线方法

​
initialize
协商版本并交换功能。
​
authenticate
与代理进行身份验证（如果需要）。
​
session/new
创建新的对话会话。
​
session/prompt
向代理发送用户提示。

​
可选方法

​
session/load
加载现有会话（需要 loadSession 功能）。
​
session/set_mode
在代理操作模式之间切换。

​
通知

​
session/cancel
取消正在进行的操作（不期望响应）。

​
客户端

客户端提供用户与代理之间的接口。它们通常是代码编辑器（IDE、文本编辑器），但也可以是用于与代理交互的其他 UI。客户端管理环境、处理用户交互并控制对资源的访问。

​
基线方法

​
session/request_permission
为工具调用请求用户授权。

​
可选方法

​
fs/read_text_file
读取文件内容（需要 fs.readTextFile 功能）。
​
fs/write_text_file
写入文件内容（需要 fs.writeTextFile 功能）。
​
terminal/create
创建新终端（需要 terminal 功能）。
​
terminal/output
获取终端输出和退出状态（需要 terminal 功能）。
​
terminal/release
释放终端（需要 terminal 功能）。
​
terminal/wait_for_exit
等待终端命令退出（需要 terminal 功能）。
​
terminal/kill
在不释放的情况下终止终端命令（需要 terminal 功能）。

​
通知

​
session/update
发送会话更新以通知客户端更改（不期望响应）。这包括： - 消息块（代理、用户、思考） - 工具调用和更新 - 计划 - 可用命令更新 - 模式更改

​
参数要求

  • 协议中的所有文件路径必须是绝对路径。
  • 行号从 1 开始

​
错误处理

所有方法都遵循标准 JSON-RPC 2.0 错误处理：
  • 成功响应包含 result 字段
  • 错误包含带有 code 和 message 的 error 对象
  • 通知永远不会收到响应（成功或错误）

​
可扩展性

协议提供了内置机制来添加自定义功能，同时保持兼容性：
  • 使用 _meta 字段添加自定义数据
  • 通过在名称前加下划线（_）创建自定义方法
  • 在初始化期间宣告自定义功能
了解协议可扩展性以了解如何使用这些机制。

​
下一步