a2a-cli

a2a CLI で A2A エージェントを操作する

a2a は A2A protocol 用のステートレスなクライアントです。 エージェントとメッセージを渡すと、エージェントカードからトランスポート（JSON-RPC、REST、または gRPC）を判定し、メッセージを送信して、エージェントからの応答を報告します。

基本概念

• やり取りは、エージェントに送信する Message から始まります。
• エージェントは、Message（直接の回答）または Task （追跡可能な、長時間かかる可能性のある作業）のいずれかで応答します。
• Task にはサーバーが割り当てる taskId と contextId があり、状態が遷移します。完了、失敗、キャンセルされるほか、続行にユーザーの入力や認証が必要な場合は interrupted になることがあります。
• 中断されたタスクを再開するには、--task-id を指定して Message を送信します。
• 関連する作業をまとめるには --context-id を使用します。これに対する応答として作成された Task は、そのコンテキストに追加されます。複数のタスクで同じコンテキストを共有できます。また、--task-id と --context-id を同時に渡す場合は、両者が一致している必要があります。
• サーバーはタスク（およびそれらに関連付けられたメッセージ）を保持します。タスクに関連付けられていない通常の Message は保存されないため、後から作業を再開できるよう、ユーザー自身が taskId／contextId を保持します。

セットアップ

このスキルは a2a バイナリを使用しますが、インストールは行いません。a2a version を実行して PATH 上にあることを確認してください。失敗する場合は、利用環境に合った方法でインストールします。

• Homebrew（macOS / Linux）：

  brew tap a2aproject/a2a-cli https://github.com/a2aproject/a2a-cli
  brew install a2a
  

• WinGet（Windows）： winget install a2aproject.a2acli

• ビルド済みバイナリ： 利用環境に合ったアーカイブを リリースページからダウンロードし、 展開して、a2a バイナリを PATH に配置します。

• ソースから（Go ツールチェーン。更新する際は再実行します）：

  go install github.com/a2aproject/a2a-cli@latest
  # go install names the binary a2a-cli; rename it to a2a to match the docs
  mv "$(command -v a2a-cli)" "$(dirname "$(command -v a2a-cli)")/a2a"
  

現在のコマンドとフラグの正確な情報は、a2a help と a2a <command> --help を参照してください。コマンドが不明として拒否された場合や、フラグが存在しなくなっている場合は、手元の SKILL.md が古くなっている可能性があります。a2a skill を実行し、その出力でローカルの SKILL.md を更新してください。

タスクのライフサイクル

-a <host|url|path> を使ってエージェントを指定すると、カードが解決され、トランスポートが選択されます。または、-e <url> --transport <rest|jsonrpc|grpc> を使って直接接続します。

1. エージェントを確認する — 接続可能であることと、対応機能を確認します。

   a2a card get https://agent.example.com
   

2. メッセージを送信する。 send は、タスクが終了状態または中断状態に達するまで処理をブロックします。機械可読な出力にするには -o json を追加し、応答に含まれる taskId と contextId を控えてください。続行する際に必要になります。

   a2a send -a https://agent.example.com "Summarize this repo"
   a2a send -a https://agent.example.com -o json "Summarize this repo"
   

3. 長時間かかるタスクをブロックせずにライブで追跡する、または後から再接続します。

   a2a send -a https://agent.example.com --stream "Run a long analysis"
   a2a task subscribe -a https://agent.example.com <task-id>
   

4. ステータスを確認し、完了までポーリングするか、結果を取得します。

   a2a task get -a https://agent.example.com <task-id>
   # Poll until completion or input/auth-required:
   a2a task get -a https://agent.example.com <task-id> --wait
   a2a task get -a https://agent.example.com <task-id> --wait --poll-interval 2s --timeout 60s
   

5. 中断されたタスクに応答する（INPUT_REQUIRED／AUTH_REQUIRED に達した場合）には、同じタスクに返信します。

   a2a send -a https://agent.example.com --task-id <task-id> "Yes, proceed"
   

6. 同じコンテキストで新しいタスクを作成し、会話を続けます。

   a2a send -a https://agent.example.com --context-id <context-id> "Follow-up question"
   

7. タスクを一覧表示またはキャンセルします。

   a2a task list -a https://agent.example.com
   a2a task cancel -a https://agent.example.com <task-id>
   

主要なフラグ

最新のフラグ一覧は a2a <command> --help を実行して確認してください。特に重要なものは次のとおりです。

フラグ	用途
-a, --agent-card <host|url|path>	エージェントのカードを解決します（使用するトランスポートを選択します）。
-e, --endpoint <url> + --transport <rest|jsonrpc|grpc>	カードの解決を省略し、インターフェースに直接接続します。
-o, --output json	機械可読形式で出力します。ライブイベントストリームを使用するには --stream を追加します。
--async	ブロックせずに識別子をすぐに返します。後で task get を使ってポーリングします。
--wait	終了状態または中断状態に達するまで、task get を繰り返しポーリングします。
--poll-interval <duration>	待機中のポーリング間隔です（デフォルトは 2s）。
--timeout <duration>	リクエストのタイムアウトと全体の待機時間の上限です（デフォルトは 30s）。
--task-id <id> / --context-id <id>	タスクを続行する／コンテキストに新しいタスクをまとめます。
--save-fileparts <dir>	レスポンス内の生のファイルパーツ（アーティファクトとメッセージ）を <dir> 配下にファイルとして保存します。出力では引き続き、名前、種類、サイズの要約が表示されます。
--auth "<creds>" / --svc-param <k=v>	認証情報またはトランスポートパラメーターを指定します（または A2ACLI_* 環境変数を設定します）。シークレットをコミットしないでください。

設定

すべての設定は、フラグ、A2ACLI_* 環境変数、.env ファイル（ローカルの .env または ~/.config/a2a-cli/.env）、永続的なユーザーレベルの ~/.config/a2a-cli/config.yaml のいずれかから指定できます。優先順位は、フラグ > 環境変数 > ローカルファイル > ユーザーの config.yaml > グローバル .env です。適用される値と、それぞれの値の取得元は a2a config show で確認できます（シークレットは伏せられます）。

コマンドプラグイン（PATH 上の a2a-<name> バイナリによってトップレベルコマンドを追加する機能）は、オプトイン方式であり、デフォルトでは無効です。検出を有効にするには a2a plugin set-enabled true を実行します。