他社や別部署のエージェントに仕事を依頼すると、結果が返るまで数分から数時間かかることがあります。HTTPリクエストを開いたまま待つ設計は、タイムアウトと接続断で簡単に壊れます。A2A v1.0 は、この「待ち方」を3つの経路として仕様に定めています。どれを選ぶかで、実装の手間も、外部に開ける攻撃面も変わります。
タスク状態の全体像はA2Aプロトコルの解説で扱いました。本稿は、長時間タスクの受け取り方と、Push通知の受信側で最低限必要な検証に絞ります。用語はA2Aプロトコルも参照してください。
A2Aで長時間タスクを受け取る方法は何通りあるか
A2A v1.0 は結果の受け取り方として、ブロッキング、ストリーミング(SSE)、Push通知の3経路を用意しています。待ち時間と接続の維持可否で選びます。
3経路の違いは、クライアントが接続を保てるかどうかで決まります。
- ブロッキング:
SendMessageのSendMessageConfiguration.return_immediatelyが既定の false のとき、呼び出しはタスクが終端状態または中断状態になるまで待ち、最新の状態と成果物を返します - 非ブロッキング:
return_immediatelyを true にすると、タスク作成直後に返ります。通常は working か input-required の状態です。以降はGetTaskでのポーリング、購読、Push通知のいずれかで結果を取ります - ストリーミング:
SendStreamingMessageは最初に Task を返し、その後に状態更新や成果物の更新イベントを流します。終端状態でストリームが閉じます。利用には AgentCard のcapabilities.streamingが必要で、無い相手にはUnsupportedOperationErrorが返ります
return_immediately は、返り値が Message の場合、ストリーミング操作、Push通知の設定には効果がありません。非同期に切り替えたいときは、どの操作に指定しているかを確認してください。
ストリーミングとPush通知はどう使い分けるのか
接続を保てる間はストリーミング、数分から数日かかる処理や接続を保てない環境ではPush通知を使います。切断時は SubscribeToTask で購読を再開できます。
公式のストリーミング・非同期ガイドは、使い分けを次のように示しています。
- ストリーミングは、進捗のリアルタイム表示や、大きな成果物を少しずつ受け取りたい場合に向きます
- Push通知は、数分から数日かかるタスクや、モバイルアプリ、サーバーレス関数のように持続接続を張れない呼び出し元に向きます。終端状態や input-required といった重要な状態変化でWebhookが呼ばれます
- ストリームが途中で切れたときは
SubscribeToTaskで再購読します。Push通知を受けた後はGetTaskで完全な最新状態を取得します
中小企業の実装では、まずストリーミングだけで始める判断が現実的です。Webhook受信口を公開すると、検証すべき項目が一気に増えるためです。社内の定型処理がほぼ数十秒で終わるなら、ブロッキングで足ります。Push通知は、承認待ちのように人間を挟んで半日以上止まるタスクが出てから導入します。
Push通知の受信側で何を検証すべきか
Push通知の受信側は、仕様上「通知元の真正性を厳密に検証」する責任があります。JWTの署名、iss・aud・exp・jtiの確認と、タスクIDの照合が最小構成です。
Push通知は、エージェント側が TaskPushNotificationConfig で登録されたURLに、StreamResponse を含むHTTP POSTを送る仕組みです。登録時には url、token、authentication を指定できます。
仕様が定める受信側の要件は次のとおりです。
- 成功時は HTTP 2xx を返す
- 重複配信が起こりうるため、冪等に処理する
- 通知に含まれるタスクIDが、自分が待っているタスクと一致することを検証する
- 通知元を確認する手段を実装する
公式ガイドのJWT例では、受信側が次の手順を踏みます。
- Authorization ヘッダーから JWT を取り出す
- ヘッダーの
kidに対応する公開鍵を、送信元の JWKS エンドポイントから取得する(可能ならキャッシュする) - 署名を検証し、
iss、aud、iat、exp、jtiを確認する TaskPushNotificationConfig.tokenを指定した場合は、その値も照合する
古い通知は iat や exp で弾き、jti を記録して重複を除きます。署名鍵は定期的にローテーションし、JWKS で配布する運用が推奨されています。
def verify_push(headers, body, expected_task_ids, jwks, seen_jti):
claims = verify_jwt(headers["Authorization"], jwks,
audience="https://my.example/a2a/webhook")
if claims["jti"] in seen_jti:
return 200 # 重複配信は成功扱いで捨てる
if body_task_id(body) not in expected_task_ids:
return 400 # 待っていないタスクIDは拒否
seen_jti.add(claims["jti"])
enqueue_for_processing(body) # 重い処理は非同期に回す
return 200
上記は構成を示す擬似コードです。verify_jwt などは自社の実装に置き換えてください。
Webhook登録を受ける側は何を警戒すべきか
公式ガイドは「クライアントが指定した任意のURLにサーバーが盲目的にPOSTすべきでない」としています。ドメイン許可リスト、所有権確認、外向き通信の制限で対処します。
自社がエージェント(サーバー)側としてPush通知を提供する場合、逆の問題が起きます。クライアントが登録したURLに自社のサーバーがPOSTするため、内部ネットワークのアドレスを指定されると、SSRFの踏み台になります。
- 登録できるURLを、許可ドメインに限定する
- URLの所有権確認を挟む
- 送信元のネットワークに外向き通信の制限をかける
- 配信には10〜30秒程度のタイムアウトを設定し、失敗が続く場合は指数バックオフや配信停止を実装する
仕様では、エージェントは設定された各Webhookに最低1回は配信を試みる必要があり、設定は終端状態になるか削除されるまで保持されます。削除操作は冪等でなければなりません。
外向きURLの制御はA2Aに限らない課題です。Web Fetchツールの外向き通信制御の考え方がそのまま使えます。
長時間タスクの運用で見落としやすい点
長時間タスクの運用では、一覧取得・キャンセル・上限設定を最初から用意します。ListTasksは1ページ最大100件、CancelTaskは成功が保証されません。
- 一覧:
ListTasksはcontextId、status、statusTimestampAfterで絞り込めます。1ページの既定は50件、最大100件で、includeArtifactsが false の場合は成果物が省略されます。呼び出し元が見えるタスクだけが返ります - キャンセル:
CancelTaskは冪等ですが成功は保証されません。取り消せない状態ではTaskNotCancelableErrorが返ります。画面には「取り消し要求中」の状態を持たせてください - 終端状態の判定:
COMPLETED、FAILED、CANCELED、REJECTEDが終端です。INPUT_REQUIREDとAUTH_REQUIREDは中断状態で、人間や認証の対応を待っています。ここで停止したタスクに期限を設けないと、放置が積み上がります - 失効後の問い合わせ: 取り消し後に消去されたタスクへの再要求は
TaskNotFoundErrorになりえます。エラーの種類で再試行の可否を分けてください
人間の承認を挟むフローとの組み合わせは、承認フローの非同期コールバック設計も参考になります。
規模別の導入手順の目安
導入は、ブロッキングで接続を確認し、ストリーミングで進捗を出し、必要になった時点でPush通知を足す順が安全です。公開する受信口は最後に増やします。
- ブロッキングで動作確認する。AgentCardの
capabilitiesを読み、相手が何に対応しているか確認する - 数十秒を超える処理はストリーミングに切り替え、切断時の
SubscribeToTaskを実装する - 半日以上止まるタスクが出たら、Push通知を導入する。受信口にはJWT検証、
jtiの重複排除、タスクIDの照合を実装する - 自社がサーバー側になる場合は、Webhook登録URLの許可リストを先に決める
自社だけで設計を固める余力がない場合は、AI導入の伴走支援で通信方式の選定から検証まで支援しています。
参考
まとめ
A2Aの長時間タスクは、接続を保てるならストリーミング、保てないか長時間ならPush通知です。受け取る側にも渡す側にも、検証の責務があります。
要点は次の4つです。
- 受け取り経路はブロッキング、ストリーミング、Push通知の3つ。
return_immediatelyで非同期に切り替えられる - Push通知の受信側は、JWT検証、
jtiによる重複排除、タスクID照合を最低限実装する - 提供側は、登録URLを盲目的に信頼しない
- 中断状態のタスクに期限を設け、取り消しは「要求」として扱う
A2Aを使った他社エージェント連携の設計や、Webhook受信口のセキュリティ確認は、Kuu株式会社へのお問い合わせからご相談ください。
