他のAIエージェントと対話するAIエージェントを構築していると、すぐに「エージェント間で実際に何が送受信されているのか」を確認しづらい問題にぶつかります。コンソールログは断片的で、ブラウザのネットワークタブでは構造化フィールドを追いにくく、専用テストスクリプトは仕様変更ですぐ古くなります。ApidogのA2Aデバッガーを使うと、Agent2Agent（A2A）プロトコルのエージェントカードURLを貼り付け、接続し、メッセージを送信し、応答を3つのビューで確認できます。
このガイドでは、A2Aデバッガーでできること、最初のエージェントへの接続手順、リクエストとレスポンスの確認方法、そしてApidogの既存のMCPサーバーテストツールとの使い分けを実装目線で説明します。A2AとMCPの全体像を先に確認したい場合は、ApidogのMCPとA2Aに関する詳細な記事も参考になります。
A2Aとは何か（要約）
A2A（Agent2Agent）は、エージェント間通信のためのオープンプロトコルです。主に次の内容を定義します。
- エージェントが自身の能力をエージェントカードとして公開する方法
- 別のエージェントがそのカードを使って接続する方法
- メッセージやファイル添付を交換する方法
- タスクのステータスを報告する方法
HTTPがWeb上の通信の共通レイヤーであるように、A2Aはエージェント間トラフィックの共通レイヤーとして機能します。たとえば、データパイプライン内のLangGraphエージェントが、別チームのCrewAIエージェントに内部実装を知らずにリクエストを送る、といった構成を実現できます。
MCP（Model Context Protocol）は、単一のエージェントにツールやリソースへのアクセスを提供するためのプロトコルです。一方、A2Aはエージェント同士の通信に焦点を当てます。違いを詳しく確認したい場合は、MCPとA2Aの違いの解説を参照してください。
A2Aデバッガーでできること
A2AデバッガーはApidog内で利用できる、A2Aエンドポイント用のビジュアルデバッグ環境です。本番ワークフローに組み込む前に、接続、認証、メッセージ送信、応答構造を確認できます。
主な機能は次のとおりです。
エージェントカード接続
URLを貼り付けて「接続」をクリックすると、エージェント名、説明、機能、宣言されたスキル、プロトコルバージョンを確認できます。カード形式が不正な場合は接続エラーとして検出できます。メッセージ送信
プレーンテキストを送信し、必要に応じてファイル添付やカスタムメタデータを追加できます。3つの応答ビュー
プレビュー、コンテンツ、生データの3種類で同じ応答を確認できます。認証設定
ベアラートークン、基本認証、カスタムヘッダー経由のAPIキーをUIから設定できます。カスタムヘッダー
ゲートウェイ認証、テナントID、トレースID、ビジネスパラメータなどをHTTPヘッダーとして追加できます。セッション履歴
送信したメッセージと応答がセッション内に残るため、同じ接続で複数のケースを比較できます。
curlコマンドを手書きする必要はありません。ApidogがJSON-RPCエンベロープ、SSEストリーミング（エージェントがサポートしている場合）、応答の解析を処理します。
ステップ1：最初のA2Aエージェントに接続する
デバッガーを開く前に、次の3つを準備します。
最新のApidogクライアント
A2Aデバッガーを使うには、対応バージョンのApidogが必要です。未インストールの場合は、Apidogをダウンロードしてください。エージェントカードのURL
A2A準拠エージェントの標準的なエントリポイントです。ローカル開発では、たとえば次のようなURLになります。
http://localhost:3000/.well-known/agent.json
- 認証情報（必要な場合） ベアラートークン、APIキー、基本認証情報などを用意します。
接続手順は次のとおりです。
- Apidogを開く
- A2Aデバッガーページに移動する
- 上部の入力欄にエージェントカードURLを貼り付ける
- 必要に応じて認証情報やヘッダーを設定する
- 接続をクリックする
有効なエージェントカードが返ると、ステータスが接続済みになり、パネルに次のようなメタデータが表示されます。
- エージェント名
- 説明
- 機能
- 宣言されたスキル
- プロトコルバージョン
接続に失敗した場合は、次を確認してください。
- URLが正しいか
- エージェントプロセスが起動しているか
- ブラウザでURLにアクセスするとJSONが返るか
- エージェントカードに必須フィールドがあるか
- GitHubのA2Aプロトコル仕様とカード構造が一致しているか
- ディスカバリーエンドポイントで認証が必要な場合、Apidog側に資格情報を設定しているか
ステップ2：テストメッセージを送信する
接続できたら、メッセージタブを開きます。チャットUIと同じ感覚でプロンプトを入力します。
例：
共有ナレッジベースにある最新の3つの顧客フィードバックを要約し、サポートチーム向けに1段落の返信を作成してください。
送信前に、必要に応じて次を追加します。
ファイル添付
クリップアイコンからファイルを選択します。デバッガーはエージェントが宣言している入力タイプを確認し、サポートされていないファイルタイプを事前に拒否します。これにより、不要な415エラーの往復を減らせます。
カスタムメタデータ
メッセージごとのコンテキストをキーと値で追加できます。
例：
priority: high
tenant: acme-corp
locale: ja-JP
これらはA2Aリクエストエンベロープに含まれ、エージェント側のハンドラーが読み取れる場合に利用されます。
準備できたら、送信をクリックします。Apidogは入力内容をA2Aメッセージ構造にラップし、エージェントへ送信して応答を待ちます。
ステップ3：3つのビューで応答を確認する
A2Aの応答は、プレーンテキスト、構造化JSON、ファイル参照、またはそれらの組み合わせで返ることがあります。Apidogでは、同じペイロードを3つのビューで確認できます。
プレビュー
構造化フィールドをツリー形式で表示します。次のようなネストされた情報を追うときに便利です。
- タスクID
- ステータス
- 成果物
- 履歴
- エラー詳細
コンテンツ
人間が読む本文を表示します。エージェントがテキストを返した場合、実際にユーザーへ表示する内容に近いビューです。
生データ
完全なJSON-RPCペイロードを表示します。仕様準拠の確認、バグレポート、フィールド名やエスケープ文字の確認に使います。
デバッグ時は、まず生データを確認するのがおすすめです。たとえば次のように切り分けられます。
プレビューは正しいがコンテンツが空
→ エージェントがApidogでレンダリング可能だが、テキストとして平坦化できない型のアーティファクトを返している可能性があります。生データに
error.messageがある
→ エージェント側がリクエストを拒否しています。エラーコードとメッセージを確認します。応答構造は正しいが内容が期待と違う
→ トランスポートではなく、プロンプト、モデル、エージェントロジック側の問題として切り分けられます。
セッション履歴は左側のパネルに表示されます。古い文脈が次のテストに影響しないようにしたい場合は、クリアをクリックして履歴をリセットします。
認証：3つの一般的なパターン
本番環境のA2Aエンドポイントは、多くの場合、認証の背後にあります。Apidogでは、よく使われる3つのパターンをUIから設定できます。
ベアラートークン
ホスト型エージェントでよく使われる形式です。認証パネルでベアラートークンを選択し、トークンを貼り付けます。
Apidogは各リクエストに次のヘッダーを追加します。
Authorization: Bearer sk-agent-7f3e9a...
基本認証
ユーザー名とパスワードで保護された内部システムやレガシーシステムで使われます。基本認証を選択し、ユーザー名とパスワードを入力すると、ApidogがBase64エンコード済みのAuthorization: Basic ...ヘッダーを生成します。
カスタムヘッダー経由のAPIキー
エージェントが非標準のヘッダー名を期待する場合は、ヘッダーセクションに手動で追加します。
例：
X-Agent-Key: your-api-key
X-Tenant-Id: acme-corp
X-Request-Id: debug-001
CSRFトークン、テナントID、リクエスト署名など、ゲートウェイ固有のヘッダーも同じ方法で追加できます。
エージェント資格情報の管理については、Apidog AIエージェント資格情報ガイドで、ローテーション、スコープ、コミットしてはいけない情報について説明しています。
カスタムヘッダーとメタデータ：どちらをいつ使うか
A2Aリクエストには、追加データを置ける場所が2つあります。どちらもキーと値を扱えますが、属するレイヤーが異なります。
| チャネル | 場所 | 用途 |
|---|---|---|
| カスタムヘッダー | HTTPリクエストヘッダー | ゲートウェイ認証、可観測性（X-Request-Id）、機能フラグ |
| メタデータ | A2Aメッセージペイロード | エージェントが読むメッセージごとのコンテキスト（優先度、テナント、ロケール） |
判断基準はシンプルです。
リバースプロキシ、APIゲートウェイ、監視基盤が使う値
→ ヘッダーに置くエージェントのタスクハンドラーが使う値
→ メタデータに置く
この2つを混同すると、「ヘッダーに入れたのにエージェントが読めない」「メタデータに入れたのにゲートウェイが認識しない」といった問題が起きます。
ApidogにおけるA2AデバッガーとMCPサーバーテストの比較
ApidogはA2AデバッガーとMCPテストフローの両方を提供しています。ただし、対象とするプロトコルとテスト内容は異なります。
| ツール | プロトコル | テスト項目 | 使用する状況 |
|---|---|---|---|
| A2Aデバッガー | Agent2Agent | 接続性、メッセージ交換、タスクステータス | エージェントが他のエージェントを呼び出すマルチエージェントシステムを構築する場合 |
| MCPサーバーテスト | Model Context Protocol | ツール呼び出し、リソースアクセス、プロンプトテンプレート | エージェントにツールやリソースを公開するMCPサーバーを構築する場合 |
どちらを使うべきか迷った場合は、MCPとA2Aのガイドを確認してください。
短くまとめると、次のようになります。
- MCP：エージェントが外部システム、ツール、リソースへアクセスするためのプロトコル
- A2A：エージェントが他のエージェントと通信するためのプロトコル
MCP側のワークフローについては、MCPサーバーテストプレイブックで、Apidogにおける手動および自動テストの流れを説明しています。現実のエージェントシステムでは、A2Aによるエージェント間連携と、MCPによるツールアクセスを組み合わせるケースが多くなります。
一般的なデバッグパターン：タスクの往復を切り分ける
「エージェントが期待通りに応答しない」ときは、次のループで確認します。
- A2Aデバッガーを開く
- エージェントカードURLで接続する
- エージェントカードに期待するスキルが表示されているか確認する
- そのスキルをトリガーする最小限のメッセージを送る
- 最初はファイルやメタデータを付けず、プレーンテキストだけで試す
- 応答の生データを確認する
- 期待するフィールドが欠落している場合は、エージェントコード側を確認する
- 応答構造は正しいが内容が違う場合は、プロンプトやモデル出力を確認する
この流れにより、問題を次のどちらかに分離できます。
- 通信、認証、A2Aエンベロープの問題
- エージェントのロジック、プロンプト、モデル応答の問題
これは、APIを呼び出すAIエージェントをテストする方法で説明している「非難する前に分離する」デバッグループと同じ考え方です。まず通信を確認し、その後でロジックをデバッグします。
AIワークフローにおける位置付け
マルチエージェントシステムでは、エージェント同士の通信を通常のAPIトラフィックと同じように観測、検証、デバッグできる必要があります。AIエージェントは新しいAPIコンシューマーであるという記事では、エージェントトラフィックを第一級のAPI利用者として扱う理由を説明しています。
また、AIエージェント向けAPIの設計では、APIの利用者が人間の開発者ではなくLLM駆動型エージェントになる場合に、API契約やエラーメッセージ設計をどう変えるべきかを解説しています。
A2Aデバッガーは、ApidogのMCPクライアントビジュアルデバッガーと同じく、SDK内部に隠れがちなエージェント通信を可視化するためのツールです。
エージェントを接続し、送受信されるデータを確認し、本番環境に到達する前にバグを修正できます。
Apidogは無料でダウンロードでき、A2Aデバッガーは標準クライアントに含まれています。別途ライセンスやプランは不要です。
よくある質問
A2Aデバッガーは無料ですか？
はい。標準のApidogクライアントにバンドルされています。Apidogをダウンロードし、対応バージョンを使用していれば、A2Aデバッガーがサイドパネルに表示されます。
あらゆるフレームワークで書かれたエージェントに対応していますか？
有効なA2Aエージェントカードを公開しているエージェントであれば利用できます。A2Aはフレームワークに依存しないため、LangGraph、CrewAI、AutoGen、カスタムのPythonまたはGoエージェントでも、A2A仕様に準拠していれば動作します。
セッションを保存して後で再生できますか？
セッションはデバッガーを開いている間は保持されます。長期保存したい場合は、生データの出力をコピーしてテスト成果物として保存してください。完全なセッションエクスポートはロードマップにあります。
ストリーミング応答はどのように処理されますか？
エージェントがA2A仕様に基づくSSEストリーミングをサポートしている場合、デバッガーはチャンクが到着するたびに読み取り、プレビューとコンテンツをリアルタイムで更新します。ストリームが閉じると、生データに組み立てられた応答が表示されます。
メタデータフィールドとヘッダーセクションの違いは何ですか？
ヘッダーはHTTPレイヤー、メタデータはA2Aメッセージレイヤーです。ヘッダーはゲートウェイやリバースプロキシに届き、メタデータはエージェントのタスクハンドラーに届きます。判断に迷った場合は、前述の比較表を参照してください。
Apidogはエージェントの応答をApidogのサーバーにログ記録しますか？
いいえ。Apidogはローカルクライアントとして動作します。お使いのマシンとエージェント間のトラフィックは、Apidogのインフラストラクチャを通過しません。
A2Aデバッガーで、異なるネットワーク上のホスト型エージェントをテストできますか？
はい。ネットワークパスが開いていれば可能です。デバッガーは通常のHTTPクライアントと同じようにアウトバウンドHTTPSリクエストを送信します。エージェントがVPNの背後にある場合は、そのVPNに接続してからテストしてください。
バグ報告や機能リクエストはどこに送ればよいですか？
Apidogに関するフィードバックは、Apidogのフィードバックチャネルに送ってください。A2A仕様そのものに関するリクエストは、A2AプロトコルのGitHubリポジトリに提出してください。
今すぐ試す
まず、アクセスできる最もシンプルなA2Aエージェントを用意します。まだエージェントがない場合は、A2Aリファレンス実装に含まれるサンプルサーバーをローカルで実行できます。
最小の確認手順は次のとおりです。
- サンプルまたは既存のA2Aエージェントを起動する
- エージェントカードURLを確認する
- ApidogのA2AデバッガーにURLを貼り付ける
- 接続をクリックする
-
helloのような短いメッセージを送る - プレビュー、コンテンツ、生データの3つのビューを確認する
これが最小限のエンドツーエンドループです。ここから、実際のプロンプト、ファイル添付、メタデータ、マルチエージェントワークフローへ段階的に広げていけます。
A2AデバッガーをApidogのAPIおよびMCP機能と組み合わせることで、HTTP、MCP、A2Aというエージェントシステムの主要な通信レイヤーを1つのインターフェースで確認できます。
Top comments (0)