A2A クライアントのセットアップ
1. A2A クライアントを初期化
2. エージェントカードを確認
3. 最初のタスクを送る
メッセージ構造(A2A 固有)
マルチパートメッセージ
A2A の強みは、テキスト・データ・ファイルを組み合わせたマルチパートメッセージです:スキル呼び出し方法
自然言語(柔軟)
明示的スキル(決定的)
ハイブリッド(推奨)
A2A レスポンス形式
AdCP 1.6.0 の新機能: すべてのレスポンスに統一ステータスフィールドが含まれます。標準レスポンス構造
A2A 上の AdCP レスポンスは、タスクレスポンスを含むDataPart(kind: ‘data’)を少なくとも 1 つ含める 必要があります。人間向けメッセージの TextPart(kind: ‘text’)は 推奨 ですが任意です。
A2A 固有フィールド
- taskId: ストリーミング更新のための A2A タスク ID
- contextId: A2A プロトコルが自動管理
- artifacts: テキスト・データを含むマルチパート成果物
- status: 一貫性のため MCP と同じ値(A2A TaskState enum)
アーティファクトの処理
DataPart が複数ある場合(ストリーミングなど)は 最後の DataPart を正とします:
プッシュ通知(A2A 固有)
A2A ではPushNotificationConfig によりプッシュ通知が標準で定義されています。Webhook URL を設定すると、ポーリング不要でサーバーがタスク更新を直接 POST します。
ベストプラクティス: URL ベースのルーティング
推奨: ルーティング情報(task_type, operation_id)はペイロードではなく Webhook URL に含める。
理由:
- ✅ 業界標準パターン - 多くの API で採用
- ✅ 関心の分離 - ルーティングは URL、データはペイロード
- ✅ プロトコル非依存 - MCP/A2A/REST などで共通に使える
- ✅ ハンドラー簡潔化 - ペイロード解析ではなく URL でルーティング
SSE ストリーミング(A2A 固有)
A2A の強みは Server-Sent Events によるリアルタイム更新です:タスク監視
リアルタイム更新の例
A2A Webhook ペイロード例
例 1: 完了時のTask ペイロード
タスク完了時、サーバーは タスク結果を .artifacts に含む 完全な Task オブジェクトを送信します:
completed または failed ステータスでは、AdCP タスク結果は status.message.parts[] ではなく .artifacts[0].parts[] に必ず入れる必要があります。
例 2: 進捗更新用 TaskStatusUpdateEvent
実行中の中間ステータス更新では、status.message.parts[] に任意データを含められます:
async-response-data.json に参照がある対応スキーマを持ちます。中間ステータスのスキーマは策定中で将来変更される可能性があるため、実装者は緩めに扱う選択も可能です。
A2A Webhook のペイロード種別
Per the A2A specification, the server sends different payload types based on the situation:| Payload Type | When Used | What It Contains |
|---|---|---|
Task | 最終状態(completed, failed, canceled)や完全なコンテキストが必要な場合 | 履歴とアーティファクトデータを含む完全なタスクオブジェクト |
TaskStatusUpdateEvent | 実行中のステータス遷移(working, input-required) | メッセージパートを含む軽量ステータス更新 |
TaskArtifactUpdateEvent | ストリーミングによるアーティファクト更新 | 利用可能になったアーティファクトデータ |
Task: 最終結果(completed,failed)TaskStatusUpdateEvent: 進捗更新(working,input-required)
Webhook が送信される条件
Webhooks are sent when all of these conditions are met:- Task type supports async (e.g.,
create_media_buy,sync_creatives,get_products) pushNotificationConfigis provided in the request- Task runs asynchronously — initial response is
workingorsubmitted
completed, failed, rejected)なら Webhook は送信されません。結果はその場で得られます。
Webhook を送るステータス変化:
working→ 進捗更新(処理中)input-required→ 人による入力が必要completed→ 最終結果failed→ エラー詳細canceled→ キャンセル確定
データスキーマのバリデーション
A2A Webhook のstatus.message.parts[].data フィールドはステータス別スキーマを使用します:
| Status | Schema | Contents |
|---|---|---|
completed | [task]-response.json | Full task response (success branch) |
failed | [task]-response.json | Full task response (error branch) |
working | [task]-async-response-working.json | Progress info (percentage, step) |
input-required | [task]-async-response-input-required.json | Requirements, approval data |
submitted | [task]-async-response-submitted.json | Acknowledgment (usually minimal) |
async-response-data.json
Webhook ハンドラーの例
コンテキスト管理(A2A 固有)
主要な利点: A2A はコンテキストを自動管理するため、context_id を手動で扱う必要はありません。
自動コンテキスト
明示的コンテキスト(任意)
マルチモーダルメッセージ(A2A 固有)
A2A の特徴は、1 つのメッセージ内にテキスト・データ・ファイルを組み合わせられることです:コンテキスト付きクリエイティブアップロード
キャンペーンブリーフ + アセット
利用可能なスキル
すべての AdCP タスクは A2A スキルとして利用できます。確実な実行には明示的な呼び出しを使用してください: タスク管理: 全ドメインにわたる非同期追跡、ポーリングパターン、Webhook 連携の詳細は Webhooks を参照。スキルの構造
利用可能なスキル
- Protocol:
get_adcp_capabilities(start here to discover agent capabilities) - Media Buy:
get_products,list_creative_formats,create_media_buy,update_media_buy,sync_creatives,get_media_buy_delivery,provide_performance_feedback - Signals:
get_signals,activate_signal
エージェントカード
A2A エージェントは.well-known/agent.json の Agent Card で機能を公開します:
Agent Card の取得
Agent Card の例
AdCP 拡張
推奨: 実行時の機能発見には
get_adcp_capabilities を使用してください。エージェントカードの拡張は、レジストリやディスカバリーサービス向けの静的メタデータを提供します。extensions 配列に AdCP 拡張を含めることで、プログラム的に AdCP 対応を宣言できます。
A2A プロトコルでは extensions 配列に以下を持つ拡張を列挙します:
uri: 拡張の識別子(https://adcontextprotocol.org/extensions/adcpを使用)description: AdCP をどう使うかの説明required: クライアントがこの拡張を必須とするか(AdCP は通常false)params: AdCP 固有の設定(下記スキーマ参照)
adcp-extension.json スキーマが使われていましたが、v3 で廃止されました。v3 以降のエージェントでは get_adcp_capabilities タスクで実行時に機能を発見してください。上記の params オブジェクトは典型的な構造です。
メリット:
- テストコールなしで AdCP 対応状況を発見できる
- 実装しているプロトコルドメイン(media_buy, creative, signals)を宣言できる
- バージョンに基づく互換性チェックが可能
統合の例
A2A 固有の考慮点
エラーハンドリング
クリエイティブアップロードのエラーハンドリング
For uploading creative assets and handling validation errors, use thesync_creatives task. See sync_creatives Task Reference for complete testable examples.
@adcp/client ライブラリは A2A アーティファクトの抽出を自動で処理するため、レスポンス構造を手動で解析する必要はありません。
ベストプラクティス
- ハイブリッドメッセージ(テキスト + データ + 必要に応じてファイル)を活用
- アーティファクト処理前に status フィールド を確認
- 長時間処理には SSE ストリーミング でリアルタイム更新
- ステータス処理パターンは Core Concepts を参照
- 利用可能なスキルと例は エージェントカード で確認
次のステップ
- Core Concepts: ステータス処理とワークフローは Task Lifecycle を参照
- Task Reference: Media Buy Tasks と Signals
- Protocol Comparison: MCP integration と比較
- Examples: 完全なワークフロー例は Core Concepts に掲載