Skip to main content
AdCP のオペレーションは秒から日までかかることがあります。サーバーは、オペレーションにどれだけ時間がかかるか、何がブロックしているかに基づいて応答方法を決定します。

30 秒ルール

任意の AdCP タスクは次のいずれかのステータスを返せます。サーバーは、関与する作業について知っていることに基づいて選択します: working は非同期ではありません。 これはサーバーが処理を続けながら帯域外(MCP ステータス通知または SSE 経由)で送る進捗シグナルです。呼び出し元は接続を保持し、準備できたら結果を受け取ります — ポーリングも Webhook もありません。「少し時間がかかっていますが、対応中です」と考えてください。 submitted は非同期です。 オペレーションはサーバーの制御外の何か — パブリッシャー承認、人間のレビュー、サードパーティ処理 — でブロックされています。呼び出し元は常に task_id で AdCP タスクステータス面をポーリングできます。設定された Webhook は、バックグラウンドワークフロー向けの追加の通知チャネルであり、ポーリングの置き換えではありません。 :::tip submitted オペレーションの Webhook Webhook はバックグラウンドの submitted オペレーションに推奨されます — 任意のトランスポート(MCP、A2A、REST)で動作し、単一セッションより長く続くオペレーションを扱えます。MCP/REST では、Webhook チャネルはタスクリクエストの push_notification_config で要求します。A2A では、snake_case のスキルパラメーターではなく configuration.pushNotificationConfig のトランスポート設定のままです。リクエストが Webhook チャネルを含み、サーバーが submitted を返してタスクを受け入れた場合、サーバーは少なくとも終端の完了または失敗の通知をそのチャネルに配信しなければなりません(MUST)。中間の進捗通知は、別のオペレーション固有の契約が要求しない限り任意です。サーバーが要求された Webhook チャネルを尊重できない場合、配信を黙って格下げするのではなく、構造化エラーでリクエストを拒否しなければなりません(MUST)。Push Notifications を参照してください。 ポーリングは AdCP タスクポーリング面を介して submitted タスクに常に有効です。3.x では、その面はレガシーの tasks/get で、セラーがエイリアスを宣伝する場合は任意で get_task_status を使用します。どちらの名前も同じペイロード形状を受け入れます。マルチアカウントの呼び出し元は、セラーがタスクの可視性を認証済みアカウント + プリンシパルのペアにスコープできるよう account を含めるべきです(SHOULD)。下記のポーリングパターンを参照してください。 トランスポートネイティブなタスクは AdCP ライフサイクルではありません。 MCP Tasks や A2A タスク更新は AdCP レスポンスを運んだりストリーミングしたりできますが、耐久性のあるタスク状態は AdCP ペイロード(task_idstatus、Webhook ペイロード、AdCP ポーリング/リコンシリエーション)です。MCP ガイドを参照してください。 :::

オペレーションの例

同期(即時)

人の入力が必要な場合がある

非同期(submitted)になる場合がある

これらのオペレーションは外部システムと連携するか人の承認を必要とします。ホールセールのフィード読み取りは例外です。get_products buying_mode: "wholesale"get_signals discovery_mode: "wholesale" は同期的な修復/リコンシリエーション読み取りのままで、submitted ではなく incomplete[] で部分完了を報告します。

タイムアウト設定

ステータスに応じて妥当なタイムアウトを設定します:
working はポーリング間隔ではなく接続タイムアウト(どれだけ開いたまま保持するか)を使います。サーバーは進捗を帯域外で送り、同じ接続で結果を配信します。submitted はポーリングまたは Webhook 配信のウィンドウを使います。Webhook を主要な通知パスとして設定していても、30 秒のポーリング間隔は妥当なデフォルトです。

Human-in-the-Loop ワークフロー

設計原則

  1. デフォルトは任意 - 承認は実装ごとに設定
  2. 明確なメッセージ - 何を承認するかを明示
  3. 適切なタイムアウト - 人の入力で無期限にブロックしません
  4. 監査証跡 - 誰が何をいつ承認したか記録
非同期オペレーションにおける Human-in-the-Loop パターンは Embedded Human Judgment フレームワークを体現しています — 人間の判断は後付けではなく、システム設計に組み込まれます。

承認パターン

よくある承認トリガー

  • 予算閾値: $100K 超のキャンペーン
  • 新規広告主: 初回の購入者
  • センシティブコンテンツ: 特定業界や話題
  • 手動インベントリ: パブリッシャー承認が必要なプレミアム枠

進捗トラッキング

進捗更新

長時間処理では進捗情報が提供されることがあります:

進捗表示

プロトコル非依存パターン

これらのパターンは MCP/A2A どちらでも機能します。

確認フローを含む商品探索

承認フローを含むキャンペーン作成

submitted オペレーションのポーリング

ポーリングは submitted オペレーションに常に有効です。設定されていれば Webhook も完了を配信し得ますが、呼び出し元はタスクポーリング面を通じてリコンサイルできます。working はポーリングしないでください — サーバーは開いた接続で結果を配信します。

非同期前提の設計

状態を永続化します

非同期処理でメモリ状態に依存しない:

再起動に耐える

オーケストレーター再起動後に追跡を再開:

ベストプラクティス

  1. 非同期前提で設計 - どの操作も時間がかかる前提
  2. 状態を永続化 - メモリだけに依存しません
  3. 再起動を考慮 - 起動時に追跡を再開
  4. タイムアウトを実装 - 無限に待たない
  5. 進捗を表示 - ユーザーに状況を伝える
  6. キャンセル対応 - 長時間処理をキャンセル可能に
  7. 監査証跡 - ステータス遷移をログ

次のステップ

  • Webhooks: ポーリングの代わりにプッシュ通知を使う場合は Webhooks
  • Task Lifecycle: ステータス処理の詳細は Task Lifecycle
  • Orchestrator Design: 本番パターンは Orchestrator Design