ACP Server
始める
プロトコルガイド · v1 安定

ACP プロトコル: v1 は安定、v2 はドラフト

ACP は JSON-RPC 2.0 です。クライアントとエージェントは initialize でメジャーバージョンに合意しなければなりません。新機能は通常、バージョン上げではなく任意能力として入ります。v2 は v1 以降で初めて計画された破壊的メジャーです。

ACP v1 v2 migration
安定
本番では v1
protocolVersion 1 が現在の安定ワイヤです。session の list/resume/close/delete、logout、追加ワークスペースルート、使用量更新、message ID、モデル設定、boolean 設定、$/cancel_request、elicitation はこの安定面に入っています。
ドラフト
v2 はドラフトとして扱う
v2 schema はレビュー用に公開されています。prompt 完了は session/prompt 応答から外れ、更新は ID キーの upsert になり、クライアントの fs/terminal API は消え、いくつかのメソッドが改名されます。バージョン交渉と feature flag の後ろに置き、既定にしてはいけません。

v1 のメッセージフロー

典型的なローカル接続は次のとおりです。

1

Initialize

クライアントは最新の protocolVersion と clientCapabilities を initialize で送ります。エージェントは選んだ版、agentCapabilities、agentInfo、authMethods を返します。

2

Authenticate

authMethods が空でなければ、セッション作成前にクライアントが authenticate（v1）を呼びます。

3

セッションを開く

session/new。能力があるなら session/load や session/resume。

4

Prompt ターン

session/prompt でターン開始。エージェントは session/update を流します。ターンは stopReason 付きの session/prompt 結果で終わります。中断は session/cancel。

実際に実装するメソッド

以下は v1 の名前です。プロトコル上のファイルパスは絶対パス必須。行番号は 1 始まりです。

エージェントメソッド

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 です。リモートエージェント一式は作業中です。Transports WG は長寿命 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