ACP Server
开始使用
协议指南 · v1 稳定

ACP 协议：v1 稳定，v2 草案

ACP 使用 JSON-RPC 2.0。客户端和 Agent 必须在 initialize 时对上主版本。新功能通常以可选能力出现，而不是升版本。v2 是 v1 之后第一个计划中的破坏性主版本。

ACP v1 v2 migration
稳定
生产环境用 v1
protocolVersion 1 是当前稳定线上格式。session 的 list/resume/close/delete、logout、额外工作区根、用量更新、message ID、模型配置、布尔配置项、$/cancel_request 和 elicitation 都已进入这块稳定表面。
草案
把 v2 当草案
v2 schema 已发布供评审。prompt 完成不再放在 session/prompt 响应里，更新变成按 ID 的 upsert，客户端 fs/terminal API 去掉，若干方法改名。必须靠版本协商和 feature flag 打开，不能当默认。

v1 消息流

一次典型的本地连接是这样。

1

Initialize

客户端发送 initialize，带上它支持的最新 protocolVersion 和 clientCapabilities。Agent 回所选版本、agentCapabilities、agentInfo 和 authMethods。

2

Authenticate

如果 authMethods 非空，客户端在创建 session 前调用 authenticate（v1）。

3

打开 session

session/new；若 Agent 声明了相应能力，也可用 session/load 或 session/resume。

4

Prompt turn

session/prompt 开始一轮。Agent 流式发送 session/update。该轮以带 stopReason 的 session/prompt 结果结束。session/cancel 用于中断。

你真正会实现的方法

下列名称是 v1。协议里的文件路径必须是绝对路径。行号从 1 开始。

Agent 方法

initialize必需Negotiate version, capabilities, and auth methods
authenticate可选Authenticate when the agent advertises auth methods
logout可选End the current authenticated state
session/new必需Create a conversation session
session/load可选Load an existing session when loadSession is advertised
session/resume可选Resume a session (stabilized; capability-gated in v1)
session/list可选Discover existing sessions
session/close可选Close an active session without deleting history
session/delete可选Remove a session from history
session/prompt必需Send a user turn; response includes stopReason
session/cancel通知Interrupt the current turn
session/set_mode可选Switch agent operating modes
session/set_config_option可选Set model and other session config selectors
$/cancel_request通知Cancel any outstanding JSON-RPC request by id

客户端方法

session/request_permission必需Ask the user to authorize a tool call
fs/read_text_file可选Read workspace files
fs/write_text_file可选Write workspace files
terminal/create可选Create a client-hosted terminal
elicitation/create可选Collect structured form or URL-mode input
session/update通知Stream chunks, tool calls, plans, usage, and commands

v2 的关键变化

官方迁移指南里只要记住这几条：

  • auth/login + auth/logout

    Renamed from authenticate / logout

  • session/resume

    Required; session/load is removed

  • session/list + session/close

    Required baseline session methods

  • session/prompt

    Acknowledges acceptance; completion moves to state_update

  • fs/* and terminal/*

    Removed from the client surface

  • session/set_mode

    Removed; use session/set_config_option

距本站上次更新后已稳定的能力

ACP 通过 RFD 往稳定 v1 里加功能，不必等大版本。

2026-07-22

Elicitation

2026-07-20

ACP v2 draft

2026-07-06

Boolean config options

2026-06-29

Request cancellation

2026-06-25

Rust and TypeScript SDKs 1.0

2026-03-09

ACP Registry

传输

生产环境的 ACP 仍然是对本地子进程的 stdio JSON-RPC。完整远程 Agent 支持还在推进。Transports 工作组正在起草长连接 GET 流 + POST，并可在同一端点升级 WebSocket。在该 RFD 稳定前，HTTP 层都是各家自己的。

initialize（v1）

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "fs": {
        "readTextFile": true,
        "writeTextFile": true
      },
      "terminal": true
    },
    "clientInfo": {
      "name": "my-client",
      "title": "My Client",
      "version": "1.0.0"
    }
  }
}
官方文档

协议 FAQ