メインコンテンツにスキップ

プロトコルリファレンス

このドキュメントでは、iac-code サーバーが公開する ACP（Agent Client Protocol）のメソッドとストリーミングイベントの完全なリファレンスを提供します。

ライフサイクル概要​

典型的な ACP セッションは以下のフローに従います：

initialize → new_session → prompt (loop) → close_session
                ↑                              │
                └── load_session / resume ──────┘
  1. initialize — ハンドシェイク。プロトコルバージョンのネゴシエーションとサーバー機能の検出。
  2. session/new — 独立したエージェントランタイムで新しいセッションを作成。
  3. session/prompt — ユーザー入力を送信し、最終レスポンスまでストリーミングイベントを受信。
  4. session/close — セッションとそのリソースを解放。

新規作成の代わりに、履歴からセッションを読み込む（session/load）か再開する（session/resume）こともできます。

メソッド​

initialize​

プロトコルハンドシェイク。すべての接続で最初の呼び出しである必要があります。

リクエストパラメータ

フィールド型必須説明
protocolVersionintegerはい要求するプロトコルバージョン（現在 1）
clientInfoobjectいいえクライアント名とバージョン
clientCapabilitiesobjectいいえクライアントがサポートする機能

レスポンスフィールド

フィールド型説明
protocolVersionintegerネゴシエートされたプロトコルバージョン
agentCapabilitiesobjectサーバー機能（下記参照）
agentInfoobjectサーバー名とバージョン
authMethodsarray利用可能な認証方法（組み込み認証情報を使用する場合は空）

エージェント機能

機能値意味
loadSessiontrue履歴からのセッション復元をサポート
promptCapabilities.embeddedContexttrueプロンプトに埋め込みリソースコンテンツを受け入れ
promptCapabilities.imagefalse画像入力は未サポート（テキストマーカーにフォールバック）
promptCapabilities.audiofalse音声入力は未サポート（テキストマーカーにフォールバック）
sessionCapabilities.list{}セッション一覧をサポート
sessionCapabilities.close{}セッションのクローズをサポート

session/new​

独立したエージェントランタイム、ツールレジストリ、LLM コンテキストを持つ新しいセッションを作成します。

リクエストパラメータ

フィールド型必須説明
cwdstringはい作業ディレクトリの絶対パス
mcpServersobjectいいえMCP サーバー設定（受け入れられますがまだ機能しません）

レスポンスフィールド

フィールド型説明
sessionIdstring以降の呼び出しで使用する一意のセッション識別子
modesobject利用可能なモードと現在のモード
modelsobject利用可能なモデルと現在のモデル
備考

各セッションは独立した AgentLoop を作成します。複数のセッションを同時に実行できますが、それぞれが LLM 接続を消費します。

session/load​

以前に永続化されたセッションをディスクから読み込み、メッセージ履歴を復元します。

リクエストパラメータ

フィールド型必須説明
cwdstringはい作業ディレクトリのパス
sessionIdstringはい読み込むセッションの ID

レスポンスフィールド

フィールド型説明
modelsobject利用可能なモデルと現在のモデル状態
modesobject利用可能なモードと現在のモード状態
備考

セッションの読み込みは ~/.iac-code/sessions/ から履歴を読み取り、中断されたメッセージを自動修復し、新しい AgentLoop に履歴を注入します。

session/fork​

既存のセッションをフォークして、同じ履歴を持つ独立したブランチを作成します。

リクエストパラメータ

フィールド型必須説明
cwdstringはい作業ディレクトリのパス
sessionIdstringはいフォークするセッションの ID

レスポンスフィールド

フィールド型説明
sessionIdstringフォークされたブランチの新しいセッション ID
modelsobject利用可能なモデルと現在のモデル状態
modesobject利用可能なモードと現在のモード状態

session/resume​

既存のセッションを再開または再接続します。必要に応じて自動的に履歴を読み込みます。

リクエストパラメータ

フィールド型必須説明
cwdstringはい作業ディレクトリのパス
sessionIdstringはい再開するセッションの ID

レスポンスフィールド

フィールド型説明
modelsobject利用可能なモデルと現在のモデル状態（任意）
modesobject利用可能なモードと現在のモード状態（任意）
備考

session/new とは異なり、クライアントはリクエストからセッション ID を既に知っているため、レスポンスに sessionId フィールドは含まれません。

session/prompt​

ユーザー入力を送信し、ストリーミングエージェントレスポンスをトリガーします。

リクエストパラメータ

フィールド型必須説明
sessionIdstringはいターゲットセッション ID
promptarrayはいコンテンツブロックの配列（下記のコンテンツブロックタイプを参照）

コンテンツブロックタイプ

タイプ説明
TextContentBlockプレーンテキストのユーザー入力
EmbeddedResourceContentBlockインラインに埋め込まれたファイルコンテンツ
ResourceContentBlockリソースリンク参照
ImageContentBlock画像（[image: mime/type] テキストマーカーにフォールバック）
AudioContentBlock音声（[audio: mime/type] テキストマーカーにフォールバック）

レスポンスフィールド

フィールド型説明
stopReasonstringプロンプトが完了した理由（停止理由を参照）
usageobjectトークン使用量：inputTokens、outputTokens、totalTokens

停止理由

値意味
end_turnモデルが正常に完了
max_turn_requestsツール呼び出しループの最大制限に到達
max_tokens出力トークン制限に到達
cancelledクライアントがプロンプトをキャンセル
refusalモデルが回答を拒否
備考

実行中、サーバーは最終レスポンスを返す前にストリーミングイベントを含む session/update 通知をプッシュします。

session/cancel​

実行中のプロンプトタスクをキャンセルします。

リクエストパラメータ

フィールド型必須説明
sessionIdstringはい実行中のプロンプトがあるセッション

動作

  • ストリームイベントの消費を停止します
  • 実行中のツールは強制終了されませんが、結果は破棄されます
  • 保留中の prompt 呼び出しは stopReason: "cancelled" で返されます

session/close​

セッションを閉じてリソースを解放します。

リクエストパラメータ

フィールド型必須説明
sessionIdstringはい閉じるセッション

動作

  • セッションがメモリから削除されます
  • 永続化された履歴はディスクに残ります
  • このセッションへの以降の prompt 呼び出しはエラーを返します

sessions/list​

指定された作業ディレクトリのすべての永続化されたセッションを一覧表示します。

リクエストパラメータ

フィールド型必須説明
cwdstringはい一覧のスコープとなる作業ディレクトリ

レスポンスフィールド

フィールド型説明
sessionsarraysessionId とメタデータを持つセッションオブジェクトのリスト

config/set​

セッションの設定オプションを動的に設定します。

リクエストパラメータ

フィールド型必須説明
sessionIdstringはいターゲットセッション
configIdstringはい設定するコンフィグキー
valueanyはい新しい値

ストリーミングイベント​

session/prompt の実行中、サーバーはストリーミングイベントデータを含む session/update 通知をプッシュします。

イベント形式​

各 session/update 通知は特定のタイプを持つ更新オブジェクトを運びます：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "abc123",
    "update": { "type": "agent_message_chunk", "text": "..." }
  }
}

イベントタイプマッピング​

内部イベントACP 更新タイプ説明
TextDeltaEventAgentMessageChunkエージェントテキストの増分出力
ThinkingDeltaEventAgentThoughtChunkモデルの推論/思考コンテンツ
ToolUseStartEventToolCallStartツール呼び出しの開始
ToolResultEventToolCallProgressツール結果（完了または失敗）
CompactionEventAgentMessageChunkコンテキストコンパクション通知
ErrorEventAgentMessageChunkエラー情報

ツール呼び出しのライフサイクル​

ToolCallStart (status=in_progress)
    │
    ├── ToolCallProgress (status=in_progress, raw_input=tool input)
    │
    ├── ToolCallProgress (status=completed, raw_output=result)   ← success
    │
    └── ToolCallProgress (status=failed, raw_output=error)       ← failure

ツール種別マッピング

ツールACP ToolKind
read_file, list_filesread
glob, grepsearch
write_file, edit_fileedit
bash, agentexecute
web_fetchfetch
その他other

権限リクエスト​

高リスクのツールを実行する前に、iac-code はクライアントに request_permission コールバックを送信します。

ツール権限カテゴリ​

カテゴリツール自動許可
読み取り専用read_file, list_files, glob, grep, web_fetchはい
書き込みwrite_file, edit_fileいいえ — 承認が必要
実行bash, agentいいえ — 承認が必要

request_permission イベント​

サーバーは以下を含む request_permission コールバックを送信します：

フィールド型説明
optionsarray利用可能な権限選択肢
sessionIdstring権限を要求するセッション
toolCallobjectツール呼び出しの詳細（タイトル、種別、入力）

権限オプション​

オプション ID意味
allow_onceこの特定の呼び出しを許可
allow_alwaysこのセッション内でこのツールの今後のすべての呼び出しを許可
reject_onceこの特定の呼び出しを拒否
reject_alwaysこのセッション内でこのツールの今後のすべての呼び出しを拒否

レスポンス形式​

{
  "outcome": "allowed",
  "option_id": "allow_once"
}

拒否する場合：

{
  "outcome": "denied"
}
クライアントレスポンスツールの動作
AllowedOutcomeツールは正常に実行されます
DeniedOutcomeツールはスキップされ、モデルは "Permission denied." エラーを受け取ります

エラー処理​

RequestError 形式​

エラーは JSON-RPC 2.0 エラー形式に従います：

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {"session_id": "Session not found"}
  }
}

一般的なエラーコード​

コード名前説明
-32700Parse error無効な JSON
-32600Invalid request不正な JSON-RPC
-32601Method not found不明なメソッド
-32602Invalid paramsパラメータの欠落または無効（例：不明なセッション ID）
-32603Internal errorサーバー側の障害