A2A プロトコル

A2A とは

Agent2Agent (A2A) は、リモートエージェントを発見して呼び出すためのプロトコルです。エージェントは Agent Card を公開し、構造化メッセージを受け取り、タスク更新をストリーミングし、標準トランスポートを通じてキャンセルやタスク検索の操作を公開できます。

A2A サーバーとしての iac-code

iac-code は A2A 1.0 Server / Agent として実行できます。他の A2A 互換クライアントは iac-code を発見し、Infrastructure as Code のリクエストを送信し、実行更新をストリーミングし、アクティブなタスクをキャンセルできます。

別のエージェント、ワークフローエンジン、またはサービスが、相互運用可能な IaC スペシャリストとして iac-code を呼び出す必要がある場合は A2A を使用します。エディタースタイルのクライアントがセッション管理、権限プロンプト、ローカル開発統合を必要とする場合は ACP を使用します。

ユースケース

• エージェントオーケストレーション — プランナーエージェントは Alibaba Cloud ROS または Terraform の作業を iac-code に委任できます。
• ワークフロー自動化 — 内部ツールは IaC の生成、レビュー、変換タスクを HTTP 経由で送信できます。
• サービスディスカバリー — クライアントは Agent Card を取得し、IaC 生成やテンプレートレビューなどの機能を選択できます。
• ストリーミング統合 — chatops やダッシュボードクライアントは、ターンの実行中にモデルテキスト、ツールアクティビティ、使用量メタデータ、最終タスク状態を表示できます。

インタラクションモードの比較

モード	コマンド	最適な用途
Interactive REPL	iac-code	手元での探索と反復的なテンプレート作成
Non-interactive CLI	iac-code --prompt "..." or --headless	1 回限りのスクリプト実行と CI ジョブ
ACP Server	iac-code acp	IDE/エディター統合と複数セッションのクライアント制御
A2A Server	iac-code a2a	A2A トランスポート上のエージェント間相互運用
A2A Client	iac-code a2a-client call	iac-code からリモート A2A エージェントを呼び出す

中核機能

• Agent Card ディスカバリー — /.well-known/agent-card.json を公開し、プロトコルバインディング、バージョン、スキル、入出力モード、任意の認証メタデータを含めます。
• HTTP JSON-RPC and REST — A2A JSON-RPC リクエストを / で提供し、SDK REST ルートを登録します。
• ストリーミング応答 — 増分タスク更新のために SendStreamingMessage をサポートします。
• タスク管理 — タスク検索、カーソルページネーション付きの認証済みタスク一覧、アクティブタスクのキャンセル、アクティブタスクの購読をサポートします。
• コンテキスト再利用 — 同じ A2A contextId 内のフォローアップメッセージで iac-code ランタイムを再利用します。
• ワークスペーススコープ — メッセージメタデータの iac_code.cwd からプロジェクトディレクトリを読み取ります。
• ツールメタデータ — ツール開始、入力差分、完了したツール結果、権限判断、トークン使用量について、iac-code 固有のメタデータを出力します。
• 入力パーツ — テキスト風パーツ、JSON データパーツ、生の UTF-8 テキスト、ローカルワークスペースの file:// テキストファイル、プロンプトマニフェストとして表現された制限付きマルチモーダル添付を受け付けます。
• クライアント呼び出し — リモート Agent Card を発見し、設定されている場合は署名を検証し、テキストプロンプトをリモートエージェントへ送信します。
• ルーティング — 明示的な名前、スキル、またはプロンプト/タグの一致により、設定済みリモートエージェントを選択します。
• 永続化メタデータ — プロセスをまたぐ復元メタデータのために、ローカル A2A タスク/コンテキストスナップショットを JSON ファイルへミラーします。
• アーティファクト — サポートされるローカルテキストアーティファクトペイロードをストリーミングイベント本文の外に保存し、標準の TaskArtifactUpdateEvent イベントを出力し、タスクの artifacts を記録します。
• 拡張とキャッシュ — 任意の iac-code アーティファクトメタデータ拡張を広告し、必須 A2A-Extensions を検証し、キャッシュヘッダー付きで Agent Card を提供します。
• プッシュ通知 — push-notifications: true が設定されている場合、ローカルファイルまたは Redis ベースの配信キューを使って、A2A タスクプッシュ通知設定メソッドをサポートします。
• Agent Card 署名 — Agent Card に任意の A2A SDK JWS 署名を追加し、設定済みキー、ローカル octet JWKS データ、またはリモート JWKS URL による kid ベースの検証をサポートします。
• 複数トランスポート — HTTP、stdio、Unix ソケット、WebSocket、公式 gRPC、カスタム gRPC JSON-RPC、Redis Streams トランスポートで実行します。
• CLI 操作 — ディスカバリー、メッセージ送信、タスク検索/一覧/キャンセル/購読、プッシュ設定 CRUD、拡張カード、ルートプレビューのコマンドを提供します。

Phase 1 のサポート

iac-code は HTTP JSON-RPC/REST と複数の任意トランスポート上の A2A サーバーモードに加え、リモート A2A エージェントを呼び出す Phase 1 クライアントモードをサポートします。リモート Agent Card の発見、広告されたエンドポイントの選択、A2A 1.0 プロンプトの送信、タスクの照会/一覧/キャンセル/購読、設定済みエージェントへのルーティング、ローカルタスク/コンテキスト復元メタデータの永続化、ローカルアーティファクトペイロードの標準タスクアーティファクトとしての保存、必須拡張の検証、プッシュ通知設定の管理、HMAC または JWKS メタデータによる Agent Card の署名または検証ができます。

Phase 1 で未サポート

• stdio、Unix ソケット、WebSocket、gRPC JSON-RPC エンベロープ、Redis Streams は実験的なカスタム JSON-RPC トランスポートです。
• 公式 gRPC には任意依存関係が必要で、デフォルトでは安全でないローカルサーバーバインディングを使用します。
• 分散または共有タスクストアはありません。永続化は iac-code ランタイム設定領域配下のローカルファイルストレージです。
• プロセス再起動後、実行中の asyncio タスクは復元されません。
• 中断されたリモートタスクの自動バックグラウンド継続はありません。
• OSS、S3、データベース、外部オブジェクトストアのアーティファクトバックエンドはありません。
• リモート HTTP URL 取り込み、大きなバイナリのチャンク化、再開可能アップロードプロトコルはありません。ローカルファイル URL パーツは許可されたワークスペースルート内に留まる必要があります。
• 署名されていない Agent Card に対するデフォルトのハード失敗はありません。
• サーバーからの非対称 Agent Card 署名と、自動署名キーローテーションはありません。
• 自律プランナー DAG や複雑なマルチエージェントオーケストレーションはありません。
• Redis ベースのキューではプッシュ配信は at-least-once です。コールバック受信側は重複を処理し、エンドポイント側の認可ポリシーを自分で適用する必要があります。

A2A サーバーモードでは、ツール権限リクエストは自動的に拒否されます。認証なしの A2A モードは信頼できるローカル環境でのみ実行するか、Bearer token、Basic auth、または API key 認証で保護してください。