概览

Agent Client Protocol 如何工作

Agent Client Protocol 允许 Agent 和客户端通过暴露双方可调用的方法以及发送通知来告知对方事件的方式进行通信。

通信模型

本协议遵循 JSON-RPC 2.0 规范，包含两类消息：

  • 方法（Methods）：请求-响应对，期望返回结果或错误
  • 通知（Notifications）：单向消息，不期望返回响应

消息流

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

初始化阶段

  • Client -> Agent：initialize 以建立连接
  • Client -> Agent：如果 Agent 要求，则调用 authenticate

会话设置 - 以下二者之一：

  • Client -> Agent：session/new 创建新会话
  • Client -> Agent：如果支持，则调用 session/load 恢复已有会话

提示回合

  • Client -> Agent：session/prompt 发送用户消息
  • Agent -> Client：session/update 通知用于进度更新
  • Agent -> Client：根据需要发送文件操作或权限请求
  • Client -> Agent：根据需要调用 session/cancel 中断处理
  • 回合结束，Agent 发送 session/prompt 响应并附带停止原因

Agent

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

基线方法

initializeSchema

协商版本并交换能力。

authenticateSchema

向 Agent 进行认证（如果需要）。

session/newSchema

创建新的对话会话。

session/promptSchema

向 Agent 发送用户提示。

可选方法

session/loadSchema

加载已有会话（需要 loadSession 能力）。

logoutSchema

结束当前认证状态（需要 agentCapabilities.auth.logout 能力）。

session/set_modeSchema

在 Agent 操作模式之间切换。

通知

session/cancelSchema

取消进行中的操作（不期望响应）。

客户端

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

基线方法

session/request_permissionSchema

为工具调用请求用户授权。

可选方法

fs/read_text_fileSchema

读取文件内容（需要 fs.readTextFile 能力）。

fs/write_text_fileSchema

写入文件内容（需要 fs.writeTextFile 能力）。

terminal/createSchema

创建新终端（需要 terminal 能力）。

terminal/outputSchema

获取终端输出和退出状态（需要 terminal 能力）。

terminal/releaseSchema

释放终端（需要 terminal 能力）。

terminal/wait_for_exitSchema

等待终端命令退出（需要 terminal 能力）。

terminal/killSchema

终止终端命令但不释放（需要 terminal 能力）。

通知

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 规范。

可扩展性

协议提供了内置机制以在保持兼容性的同时添加自定义功能：

  • 使用 _meta 字段添加自定义数据
  • 通过在名称前加下划线（_）创建自定义方法
  • 在初始化期间宣告自定义能力

了解协议可扩展性以学习如何使用这些机制。

后续步骤