メディアバイ仕様

​

概要

​

プロトコルの概要

• キャンペーンブリーフに基づく自然言語によるインベントリ発見
• パッケージレベルの予算とターゲティングを伴うキャンペーン作成
• クリエイティブアセットの管理と同期
• パフォーマンストラッキングと最適化フィードバック
• 人間参加型の承認ワークフロー

​

トランスポート要件

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/protocol/get-adcp-capabilities-response.json",
  "status": "completed",
  "adcp": {
    "major_versions": [2],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
  },
  "supported_protocols": ["media_buy"],
  "account": {
    "supported_billing": ["operator", "agent"]
  }
}

​

コアコンセプト

​

リクエストロール

• オーケストレーター: APIリクエストを行うプラットフォーム（例: DSP、トレーディングデスク）
• アカウント: 請求関係 — 誰に請求が行き、どのレートが適用されるか（account_id で識別）
• エージェント: バイを実行するエンティティ（認証トークンで識別）

​

セールスエージェントの種類

• セールスエージェントは販売を許可されたインベントリの商品のみを返さなければなりません
• セールスエージェントは該当する場合 adagents.json を通じて認可を検証しなければなりません

• セールスエージェントは各商品のソースパブリッシャーを明確に特定しなければなりません
• セールスエージェントはインベントリの出所を偽って伝えてはなりません

​

識別子

• media_buy_id: メディアバイの一意識別子。セールスエージェントは作成成功時にこれを返さなければなりません。オーケストレーターはメディアバイに対するすべての後続操作にこれを使用しなければなりません。media_buy_id は、認証済みアカウントが所有するセラーのアドサーバー上の任意のオーダーへの安定したハンドルです——元々 AdCP 経由で発注されたオーダーに限りません。
• package_id: メディアバイ内のパッケージの一意識別子。セールスエージェントは作成された各パッケージに対してこれを返さなければなりません。
• idempotency_key: 安全なリトライのためのクライアント生成の一意キー。同じアカウントに対して重複キーを受け取ったセールスエージェントは、再実行するのではなく元のレスポンスを返さなければなりません。

​

アカウントの所有権と作成サーフェス

• get_media_buys は、認証済みアカウントが所有するすべてのメディアバイを返さなければなりません（MUST）——create_media_buy 経由で作成されたか、セラーのネイティブ API や UI 経由か、手動トラフィッキング経由か、レガシー/サードパーティのシステム経由かを問いません。適用されるのは宣言された status_filter とページネーションのみです。
• get_media_buys が返す media_buy_id はすべて、get_media_buy_delivery の有効な引数であり、かつその valid_actions に列挙されたすべてのアクションについて update_media_buy の有効な引数でなければなりません（MUST）。
• セールスエージェントは、元々 AdCP を通じて発注されたものではないことを理由に、バイを読み取り専用としたり、隠したり、MEDIA_BUY_NOT_FOUND を返したりしてはなりません（MUST NOT）。
• 特定のアクションがビジネス上の理由（契約上の義務、プラットフォームの制約、ポリシー）で利用できない場合、セールスエージェントはそれを、アカウントスコープの一覧からバイを拒むのではなく、そのアクションを valid_actions から省略することで表現します。
• 作成サーフェスは決してビジネス上の理由になりません。 セールスエージェントは、バイが AdCP の外で作成されたという理由だけで、valid_actions からアクションを省略したり、それ以外は有効な更新に対して INVALID_STATE を返したりしてはなりません（MUST NOT）。valid_actions の省略が正当なのは、同じ状態にある AdCP 作成のバイにも等しく適用されるであろう、実際の契約上、プラットフォーム上、またはポリシー上の制約に根拠がある場合のみです。AdCP 外のバイを体系的に空の valid_actions で返すセラーは非準拠です。その振る舞いはバイを隠しているのと区別がつかず、上記のルールの規範的な意図を無効にするからです。

​

分離はアカウント境界で行う

• 隠すサブセットを、呼び出し元が参照する権限を持たない別のアカウント（またはサブアカウント）として公開します。
• 呼び出し元が権限を持つ任意のアカウント内では、上記のルールに従って、そのアカウントが所有するバイの完全な集合を返します。

​

非同期オペレーション

• 同期レスポンス: セールスエージェントは完了した結果を即座に返してもよい
• 非同期レスポンス: セールスエージェントはタスクリファレンスとともに status: "submitted" または status: "working" を返してもよい
• 人間参加型: セールスエージェントは、レビュアーが動くまでタスクを status: "submitted" に保つことで、内部の人によるレビュー（例: IO への署名）を要求してもよい（MAY）。セールスエージェントは、バイヤーが応答しなければならない場合（例: 予算の確認）に status: "input-required" を使ってもよい（MAY）。人による承認はタスクレイヤーでモデル化されます——pending_approval というメディアバイのステータスは存在しません（その値はアカウントのオンボーディングレビュー向けに Account.status にのみ存在します）
• 拒否: セールスエージェントは、プラットフォームのセットアップによってオーダーを履行できないことが判明した場合（例: インベントリの売り切れ、アドサーバーのセットアップ中に発見されたポリシー上の問題）、pending_creatives または pending_start ステータスのメディアバイを拒否してもよい（MAY）。オーケストレーターは rejected を終端状態として扱わなければなりません。セラーが作成時にオーダーを受け入れたくない場合は、rejected ステータスのメディアバイを作成するのではなく、create_media_buy をエラーで失敗させるべきです（SHOULD）。

​

メディアバイの状態遷移

create_media_buy ──┬──▶ pending_creatives ──▶ pending_start ──▶ active
                   ├──▶ active ──(pause)──▶ paused
                   └──▶ paused (when created with paused: true)

paused ──(resume)──▶ active
active ─────────────▶ completed (terminal)
paused ─────────────▶ completed (terminal)

pending_creatives ──▶ rejected (terminal)  — seller rejects during setup
pending_start ──────▶ rejected (terminal)  — seller rejects during setup

Any non-terminal ──── update(canceled: true) ──▶ canceled (terminal)

• セールスエージェントは create_media_buy から active、paused、pending_creatives、pending_start を返してもよい（MAY）（プラットフォームのセットアップ時間とバイヤーの作成時の paused リクエストに基づくセラーの選択）
• セールスエージェントは、フライト日が到来したときにメディアバイを pending_start から active へ遷移させなければなりません（MUST）。セールスエージェントは、この遷移が起きたときにウェブフックでオーケストレーターに通知すべきです（SHOULD）。
• コミットされた create_media_buy の成功レスポンスはオーダーの確定を構成します。セールスエージェントは create/get のレスポンスに confirmed_at を含めなければなりません（MUST）。その値はセラーのコミットのタイムスタンプ、または、存在するもののまだセラーのコミットを待っている暫定的なバイの場合は null です。
• セールスエージェントは create、get、update のレスポンスに revision を含めなければなりません（MUST）。リビジョン番号は、状態を変更するあらゆる変更または更新のたびに増加しなければなりません（MUST）。
• active ↔ paused の遷移は、paused: true または paused: false を指定した update_media_buy を使います
• トップレベルの paused: true を指定した create_media_buy は、そうでなければ active になるはずのメディアバイを保留状態で作成します。セットアップのブロッカーは依然として優先されます: クリエイティブがなければ pending_creatives に、将来のフライトなら開始条件が満たされるまで pending_start になります。それらのブロッカーが見えている間、保留は潜在的な状態です。クリエイティブが揃いフライトが開始できるようになると、そのバイは active ではなく paused に入ります。
• paused: false を指定した update_media_buy は、現在 paused のバイを再開するか、可視状態がまだ pending_creatives または pending_start である間に、作成時の潜在的な保留を解除します。潜在的な保留の解除はセットアップのブロッカーを迂回しません。可視ステータスは、クリエイティブが提供されフライトが開始できるようになるまで pending のままです。
• フライトが終了、ゴールが達成、または予算が消化されたとき、active または paused → completed（セラー起点）
• バイヤー起点のキャンセルは、canceled: true と任意の cancellation_reason を指定した update_media_buy を使います
• セラー起点のキャンセル（例: ポリシー違反、インベントリの引き上げ）は、メディアバイを cancellation.canceled_by: "seller" とともに canceled へ遷移させます。セラー起点のキャンセルを行う場合、セラーはウェブフックでオーケストレーターに通知しなければなりません（MUST）。
• セラー起点の拒否（pending_creatives または pending_start から）も、push_notification_config を通じてオーケストレーターに通知しなければなりません（MUST）。ウェブフックのペイロードには media_buy_id、status: "rejected"、rejection_reason を含めなければなりません（MUST）。
• セールスエージェントは、メディアバイまたはパッケージを canceled へ遷移させるとき、canceled_at と canceled_by を持つ cancellation オブジェクトを含めなければなりません（MUST）
• セールスエージェントは、終端状態でないメディアバイのバイヤーによるキャンセルを、エラーコード NOT_CANCELLABLE で拒否してもよい（MAY）（例: セラーが契約上フライト途中のキャンセルを拒む場合）
• バイヤーが既に canceled のメディアバイをキャンセルしようとした場合（canceled のバイに対する canceled: true）、セールスエージェントは NOT_CANCELLABLE で拒否しなければなりません（MUST）
• 終端状態（completed、rejected、canceled）のメディアバイに対するその他すべての更新——completed または rejected のバイに対する canceled: true の試みを含む——は INVALID_STATE で拒否しなければなりません（MUST）
• 拒否（rejected ステータス）は pending_creatives または pending_start からのみ有効です。セールスエージェントは、既に active へ遷移したメディアバイを拒否してはなりません（MUST NOT）。
• セラー起点のキャンセル通知は、create_media_buy または update_media_buy の際にオーケストレーターが提供した push_notification_config のウェブフックを使わなければなりません（MUST）。ウェブフックのペイロードには media_buy_id、status: "canceled"、および canceled_at、canceled_by: "seller"、reason を持つ cancellation オブジェクトを含めなければなりません（MUST）。
• update リクエストの canceled フィールドは "const": true を使います——true のみが有効です。canceled: false を送るとスキーマバリデーションに失敗します。キャンセルは取り消し不可であり、「キャンセルの取り消し」操作はありません。
• クリエイティブの割り当てはバイの拒否またはキャンセルで解放されます。 メディアバイが rejected または canceled へ遷移すると、そのメディアバイ上のすべてのパッケージ・クリエイティブの割り当てが解放されます。creative.has_creative_library: true を表明しているセラーでは、割り当ての状態とクリエイティブの状態に従ってクリエイティブはクリエイティブライブラリに残り、後続の create_media_buy や sync_creatives の呼び出しで creative_id により参照してもかまいません（MAY）。クリエイティブライブラリなしで inline_creative_management を表明しているインライン専用のセラーは、送信されたクリエイティブをパッケージスコープに保ってもかまいません（MAY）。それらはバイをまたぐ再利用や list_creatives による読み戻しを表明しません。
• クリエイティブのレビューはバイの結果から独立しています。 セールスエージェントは、クリエイティブを含むバイが拒否されたことを理由に、そのクリエイティブを暗黙的に拒否してはなりません（MUST NOT）。クリエイティブの拒否は、それ自身の rejection_reason を持つ意図的なレビューの判断でなければなりません（MUST）。クリエイティブがコンテンツポリシーに違反したためにバイが拒否された場合、セールスエージェントはそのクリエイティブを拒否してもかまいませんが（MAY）、それは通常のレビュー経路を通じて、それ自身の rejection_reason とともに行う場合に限ります。バイの rejected ステータスはそれ自体では十分ではありません。
• 解放された割り当ての可観測性。 メディアバイレベルの canceled または rejected の遷移（バイの history と上記で必須とされるウェブフック通知で公開されます）が、解放されたすべての割り当てに対する監査記録そのものです。バイヤーは割り当てごとの差分の可観測性に依拠してはなりません（MUST NOT）。解放された割り当ては、そのバイの get_media_buys レスポンスにはもう現れません。ライブラリでの再利用可能性を確認するバイヤーは、クリエイティブがまだライブラリにあることを確認し現在のステータスを観測するために list_creatives を呼ぶべきです（SHOULD）。get_media_buys はパッケージレベルの承認状態を公開するのであってクリエイティブ本体の完全な取得ではないため、インライン専用のバイヤーは送信したクリエイティブ本体を保持しておくべきです。以前のパッケージ上のパッケージスコープの期限（creative_deadline）は、ライブラリのクリエイティブの新しいバイへの適格性には関係しません。
• 保持。 クリエイティブライブラリを持つセールスエージェントは、最後の割り当てが解放されてから少なくとも 90 日間、解放されたクリエイティブをライブラリに保持すべきです（SHOULD）。規範的な保持期間の下限は #2260 で追跡されているクリエイティブ保持の契約で規定されます。その契約が着地するまでの間、長期の再利用に依拠するバイヤーは、解放されたクリエイティブを新しいバイで参照する前に list_creatives で永続性を確認すべきです（SHOULD）。

​

リビジョンと確定のセマンティクス

• パッケージは creative_deadline を持ってもよい（MAY）——この期限の後、パッケージへのクリエイティブの変更は CREATIVE_DEADLINE_EXCEEDED で拒否されます。不在の場合、メディアバイの creative_deadline が適用されます。CREATIVE_REJECTED はコンテンツポリシー上の失敗のために予約されています。
• パッケージのキャンセル（パッケージ更新での canceled: true）は取り消し不可であり、メディアバイのステータスから独立しています——メディアバイが active のまま、単一のパッケージだけをキャンセルできます。キャンセルされたパッケージ上のクリエイティブの割り当ては、上記のメディアバイレベルのルールに従って解放されます。同じメディアバイ上の他のアクティブなパッケージに割り当てられたクリエイティブは影響を受けません。
• セールスエージェントはキャンセルされたパッケージの配信データを保持しなければなりません（MUST）。include_snapshot が true の場合、セールスエージェントはキャンセル時点の配信状態を反映した最終スナップショットを返すべきです（SHOULD）。
• メディアバイ内のすべてのパッケージがキャンセルされた場合、メディアバイ自体は現在のステータス（active または paused）のままです。フライト途中のパッケージ追加をサポートするセラーは valid_actions に add_packages を表明します——バイヤーは update_media_buy の new_packages を通じて新しいパッケージを追加できます。そうでない場合、バイヤーはメディアバイを明示的にキャンセルすべきです（SHOULD）。セールスエージェントは、最後のアクティブなパッケージがキャンセルされたときに（update レスポンスの context.notes を通じて）オーケストレーターに通知すべきです（SHOULD）。セールスエージェントは、新しい活動がなければ、セラーが定めた猶予期間の後にメディアバイを canceled へ自動遷移させてもかまいません（MAY）。

​

パッケージ上のクリエイティブ承認

1. get_media_buys のレスポンスで rejection_reason を確認する
2. クリエイティブを修正する（アセットの更新、マニフェストの調整）
3. ライブラリを持つセラーには sync_creatives で、インライン専用のセラーには update_media_buy の packages[].creatives で再送信する
4. 承認が pending_review にリセットされる

​

検証タグの強制

​

タスク

​

get_products

• オーケストレーターは buying_mode を "brief"、"wholesale"、または "refine" に設定しなければなりません
• オーケストレーターは buying_mode が "brief" の場合に brief を含めなければなりません
• オーケストレーターは buying_mode が "wholesale" または "refine" の場合に brief を含めてはなりません
• オーケストレーターは buying_mode が "refine" の場合に refine を含めなければなりません
• オーケストレーターは buying_mode が "brief" または "wholesale" の場合に refine を含めてはなりません
• オーケストレーターは refine 内の各商品エントリに scope と product_id を、各プロポーザルエントリに scope と proposal_id を提供しなければなりません
• オーケストレーターは商品エントリおよびプロポーザルエントリの action を省略してもよい（デフォルトは "include"）
• オーケストレーターは単一の refine 配列に同一の商品IDまたはプロポーザルIDを持つ複数のエントリを含めてはなりません
• セールスエージェントはブリーフが提供された場合、ブリーフ条件に一致する商品を返さなければなりません
• セールスエージェントは各商品に product_id と pricing_options を含めなければなりません
• セールスエージェントは複数の商品が一致する場合、関連性スコアを含めるべきです

• セールスエージェントは、商品エントリおよびプロポーザルのリファインエントリで action が欠けている場合、action: "include" として扱わなければなりません
• セールスエージェントは action: "omit" を持つ商品をレスポンスから除外しなければなりません
• セールスエージェントは action: "omit" を持つプロポーザルをレスポンスから除外しなければなりません
• セールスエージェントは action: "include" を持つ商品を更新された価格とともに返さなければなりません
• セールスエージェントは action: "include" を持つ商品エントリの ask を満たすべきです
• セールスエージェントは action: "more_like_this" を持つ商品に類似した追加商品を元の商品とともに返すべきです
• セールスエージェントはレスポンスを構成する際にリクエストレベルの ask（scope: "request"）を考慮すべきだ — これにより明示的に参照された商品以外の追加商品が含まれる場合があります。商品ごとのアクションはリクエストレベルの指示より優先されます。
• セールスエージェントは action: "include" を持つプロポーザルエントリの ask を満たすべきです
• セールスエージェントはレスポンスに refinement_applied を含めるべきで、位置でマッチした各変更リクエストに1エントリを持ちます
• refinement_applied を返すセールスエージェントは、オーケストレーターが整合性を相互検証できるよう、各エントリで scope をエコーしなければならず、商品スコープとプロポーザルスコープについては product_id / proposal_id をエコーしなければなりません
• セールスエージェントはオーケストレーターがプロポーザルエントリを含めていない場合でも、リファインモードで商品と並んでプロポーザルを返してもよい

​

list_creative_formats

• セールスエージェントはサポートするすべてのクリエイティブフォーマットを返さなければなりません
• セールスエージェントは各フォーマットの技術仕様を含めなければなりません
• セールスエージェントは該当する場合、クリエイティブプロトコルの標準フォーマットIDを参照すべきです

​

create_media_buy

• オーケストレーターは packages 配列または proposal_id のいずれかを含めなければなりません
• オーケストレーターはキャンペーンの start_time と end_time を含めなければなりません
• セールスエージェントは作成成功時に media_buy_id を返さなければなりません
• セールスエージェントは作成成功時に confirmed_at を返さなければなりません。その値はセラーのコミットのタイムスタンプ、またはレスポンスがまだコミットされていない暫定的なバイを作成する場合は null です。
• セールスエージェントは作成成功時に revision を返さなければなりません
• セールスエージェントは、クリエイティブをアップロードすべき期限を示す creative_deadline を返さなければなりません
• セールスエージェントは価格オプションに対して予算を検証しなければなりません
• 検証失敗時、セールスエージェントは errors 配列を返さなければなりません

​

update_media_buy

• オーケストレーターは media_buy_id を含めなければなりません
• セールスエージェントは、認証済みアカウントについて get_media_buys が返した任意の media_buy_id を受け入れなければならず、バイが元々 AdCP の外で作成されたことを理由に更新を拒否してはなりません。特定の操作に対するビジネス上の制約は、それらを valid_actions から省略することで表現します。アカウントの所有権と作成サーフェスを参照。
• セールスエージェントは PATCH セマンティクスを適用しなければなりません: 指定されたフィールドのみ更新され、省略されたフィールドは変更されない
• バイヤーが既に canceled のメディアバイをキャンセルしようとした場合（canceled のバイに対する canceled: true）、セールスエージェントは NOT_CANCELLABLE で拒否しなければなりません
• 終端状態（completed、rejected、canceled）のメディアバイに対するその他すべての更新——completed または rejected のバイに対する canceled: true の試みを含む——は INVALID_STATE で拒否しなければなりません
• オーケストレーターは canceled: true と任意の cancellation_reason を設定してメディアバイをキャンセルしてもよい
• セールスエージェントはキャンセルを受理した際、メディアバイを canceled ステータスへ遷移させなければなりません
• セールスエージェントは、終端状態でないメディアバイのキャンセルをエラーコード NOT_CANCELLABLE で拒否してもよい
• オーケストレーターはパッケージ更新で canceled: true を設定して個別のパッケージをキャンセルしてもよい
• セールスエージェントは、creative_deadline を過ぎたパッケージへのクリエイティブの変更をエラーコード CREATIVE_DEADLINE_EXCEEDED で拒否しなければなりません
• オーケストレーターは new_packages を通じて既存のメディアバイに新しいパッケージを追加してもよい。これをサポートするセールスエージェントは valid_actions に add_packages を表明しなければなりません。パッケージの追加をサポートしないセールスエージェントは UNSUPPORTED_FEATURE で拒否しなければなりません。
• update リクエストで canceled: true が他のフィールドと同時に存在する場合、セールスエージェントはキャンセルを適用しなければならず、cancellation_reason を除く他のすべてのフィールドを無視しなければなりません。キャンセルは並行する変更よりも優先されます。セールスエージェントは、キャンセル以外のフィールドが存在し無視された場合、レスポンスの context に警告を含めるべきです。
• セールスエージェントは更新適用後（または承認保留中の場合は提案された状態）の直接変更された各パッケージの状態を含む affected_packages を返さなければなりません。キャンペーンレベルのフィールド（例: paused、start_time）のみが更新される場合は空の配列も有効です
• 手動承認が必要な場合、セールスエージェントは保留中の更新リクエストを永続化しなければならず、implementation_date: null を返さなければならず、空の affected_packages を返してはなりません
• セールスエージェントは更新されたメディアバイの状態を返すべきです

​

sync_catalogs

• オーケストレーターは account_id を含めなければなりません
• catalogs が提供される場合、少なくとも1つのカタログを含めなければなりません
• catalogs が省略された場合、そのコールは発見のみを目的とし、変更なしに既存のカタログを返す
• セールスエージェントはカタログごとの結果を返さなければならず、取られたアクションとアイテムレベルの問題を含めます
• セールスエージェントは変更を適用せずに検証するための dry_run をサポートすべきです

​

list_creatives

​

sync_creatives

​

get_media_buys

• オーケストレーターは account_id、media_buy_ids、status_filter でフィルタリングしてもよい
• オーケストレーターは広範なスコープのクエリに対してカーソルページネーション（pagination.max_results / pagination.cursor）を使用すべきです
• セールスエージェントは、認証済みアカウントが所有し宣言されたフィルターの集合に一致するすべてのメディアバイを、そのバイがどのように作成されたか（AdCP、セラーのネイティブ API/UI、手動トラフィッキング、レガシーシステム）に関わらず返さなければなりません。アカウントの所有権と作成サーフェスを参照。
• セールスエージェントは一致した各メディアバイの現在のメディアバイステータスとパッケージレベルの運用状態を返さなければなりません
• セールスエージェントは、返されるメディアバイレベルの status がキャッシュから提供される場合、または上流のレグからロールアップされたステータスとして計算される場合、status_as_of を含めるべきです。ロールアップされたステータスの場合、status_as_of は、返されるロールアップに影響しうる上流ステータス観測のうち最も古いものより後であってはなりません。そうすることで鮮度を過大に主張することがなくなります。鮮度について何も主張しない場合は省略するか null を返します。バイヤーは、省略または null の値がステータスがライブであることを意味すると推論してはなりません。バイヤーは一覧のステータスの鮮度を解釈するために status_as_of を使います。updated_at は引き続きメディアバイの最終更新時刻です。
• セールスエージェントは各メディアバイについて、現在の状態でバイヤーが実行できるアクションを列挙した valid_actions を含めるべきです。これにより、エージェントが状態機械を内部に取り込む必要がなくなります。期待されるマッピング:

• オーケストレーターは、include_history に希望する直近のエントリ数を設定してリビジョン履歴をリクエストしてもよい。セールスエージェントは、include_history > 0 のとき、リビジョン番号、タイムスタンプ、サーバーが導出したアクターの識別情報、アクションの種類、任意のサマリーを含む history 配列をメディアバイごとに返すべきです。履歴エントリは新しい順に並べなければなりません。
• セールスエージェントはメディアバイ通貨を含めなければならず、通貨フィールドを一貫して表示しなければなりません（snapshot.currency -> package.currency -> media_buy.currency）
• セールスエージェントは利用可能な場合、クリエイティブ承認結果と保留中のフォーマット要件を含めるべきです
• include_snapshot が true でパッケージのスナップショットデータが省略される場合、セールスエージェントは snapshot_unavailable_reason を返さなければなりません
• include_snapshot が true でスナップショットが返される場合、各スナップショットは as_of と staleness_seconds を含めなければなりません
• デフォルトの status_filter: ["active"] は media_buy_ids が省略された場合のみ適用されます

​

get_media_buy_delivery

• オーケストレーターは media_buy_id を含めなければなりません
• セールスエージェントは、認証済みアカウントについて get_media_buys が返した任意の media_buy_id を、その作成サーフェスに関わらず受け入れなければなりません。アカウントの所有権と作成サーフェスを参照。
• セールスエージェントはパッケージレベルで配信指標を返さなければなりません
• セールスエージェントはリクエストされた場合、次元ごとの内訳を含めるべきです
• セールスエージェントはデータの鮮度を示す as_of タイムスタンプを含めなければなりません

​

provide_performance_feedback

• オーケストレーターは media_buy_id とパフォーマンス指標を含めなければなりません
• セールスエージェントはフィードバックの受信を確認しなければなりません
• セールスエージェントはキャンペーン制約内での配信最適化にフィードバックを使用すべきです

​

sync_event_sources

• オーケストレーターは account_id を含めなければなりません
• event_sources が提供される場合、少なくとも1つのイベントソースを含めなければなりません
• event_sources が省略された場合、そのコールは発見のみを目的とし、変更なしにアカウントのすべてのイベントソースを返す
• セールスエージェントは何が起きたかを示す action を含むソースごとの結果を返さなければなりません
• セールスエージェントは存在する場合、セラー管理のイベントソースをレスポンスに含めなければなりません
• セールスエージェントは新しく作成されたイベントソースの setup 手順を返すべきです
• セールスエージェントはセラーのプラットフォームでのクロスリファレンス用に seller_id を含めてもよい

​

log_event

• オーケストレーターは設定済みのイベントソースを参照する event_source_id を含めなければなりません
• オーケストレーターは event_id、event_type、event_time を持つ少なくとも1つのイベントを含めなければなりません
• セールスエージェントは events_received と events_processed のカウントを返さなければなりません
• セールスエージェントは event_id + event_type + event_source_id でイベントを重複排除しなければなりません
• セールスエージェントは個別に失敗したイベントの partial_failures を報告すべきです
• セールスエージェントはユーザーマッチングが試みられた場合、match_quality スコアを返すべきです

​

sync_audiences

• オーケストレーターは account_id を含めなければなりません
• オーケストレーターはハッシュ化されたメンバーデータを持つ少なくとも1つのオーディエンスを含めなければなりません
• セールスエージェントはマッチングステータスを含むオーディエンスごとの結果を返さなければなりません
• セールスエージェントは非同期マッチング完了のための push_notification_config をサポートすべきです
• セールスエージェントは SHA-256 ハッシュ化された識別子を受け入れなければならず、hashed_email/hashed_phone フィールドの平文のメールアドレス/電話番号を拒否しなければなりません（トランスポート境界での PII の最小化。ハッシュ化では満たされない保持と同意の義務についてはプライバシーに関する考慮事項を参照）

​

エラーハンドリング

• MEDIA_BUY_NOT_FOUND: 参照されたメディアバイが存在しません
• PACKAGE_NOT_FOUND: 参照されたパッケージが存在しません
• PRODUCT_NOT_FOUND: 参照された商品が存在しません
• BUDGET_EXCEEDED: 操作が割り当て予算を超過します
• CREATIVE_REJECTED: クリエイティブがコンテンツポリシーのレビューに失敗しました
• CREATIVE_DEADLINE_EXCEEDED: パッケージの creative_deadline の後にクリエイティブの変更が送信されました
• INVALID_STATE: リソースの現在のステータスではその操作が許可されていない（例: 完了またはキャンセルされたメディアバイの更新）
• NOT_CANCELLABLE: メディアバイまたはパッケージを現在の状態でキャンセルできません
• GOVERNANCE_DENIED: 登録されたガバナンスエージェントがトランザクションを拒否しました。バイヤーはバイを組み直すか、人の支出権限にエスカレーションするか、ガバナンスエージェントに連絡できます。
• TERMS_REJECTED: バイヤーが提案した measurement_terms がセラーに拒否されました。エラーの詳細は、どの条件が失敗したか、およびセラーの許容範囲またはサポートするベンダーを特定すべきです。復旧方法: 提案した条件を調整してリトライするか、measurement_terms を省略してプロダクトのデフォルトを受け入れます。
• REQUOTE_REQUIRED: update_media_buy リクエストが、元の見積もりが価格付けの前提としたパラメータのエンベロープ（予算、フライト日、ボリューム、ターゲティング）を変更しています。pricing_option はロックされたままです。セラーはその価格でリクエストされた形を断っています。TERMS_REJECTED（計測）や POLICY_VIOLATION（コンテンツ）とは異なります。3.1 での復旧方法は、現在の見積もりに収まるよう更新を調整する、プロダクト/条件を再発見する、add_packages が利用可能なときにパッケージを追加する、または別のメディアバイを作成することです。AdCP 3.1 は update_media_buy に添付できる修正見積もりのアーティファクトを定義していません。セラーは、バイヤーのエージェントが自律的に再発見できるよう、エンベロープに違反したフィールドのパス（例: packages[0].budget、end_time）を error.details.envelope_field に設定すべきです。
• VALIDATION_ERROR: リクエストフォーマットまたはパラメータのエラー
• AUTH_MISSING: 認証情報が提示されませんでした。復旧: 訂正可能。
• AUTH_INVALID: 認証情報は提示されたが拒否されました（期限切れ/失効/不正な形式）。復旧: 終端。

​

セキュリティの考慮事項

​

トランスポートセキュリティ

​

認証

• オーケストレーターは有効な認証情報を使用してセールスエージェントに対して認証しなければなりません
• セールスエージェントはリクエストを処理する前に認証情報を検証しなければなりません
• セールスエージェントはインベントリアクセスを決定するためにアカウントコンテキストを使用しなければなりません

​

予算認可

• セールスエージェントはアカウントが要求された予算レベルに対して認可されているかを検証しなければなりません
• セールスエージェントは明示的な承認なしに認可された予算上限を超えてはなりません

​

クリエイティブセキュリティ

• セールスエージェントはポリシー準拠のためにクリエイティブコンテンツを検証しなければなりません
• セールスエージェントはクリエイティブのマルウェアおよび悪意のあるコンテンツをスキャンすべきです
• セールスエージェントはセキュリティ検証に失敗したクリエイティブを配信してはなりません

​

適合性

​

セールスエージェントの適合性

1. 指定されたトランスポート（MCP または A2A）のうち少なくとも1つをサポートします
2. スキーマに従ってすべてのタスクを実装します
3. レスポンススキーマで定義された必須フィールドを返す
4. 指定されたエラーコードを使用します
5. 非同期オペレーションを適切に処理します
6. 認証と認可を強制します

​

オーケストレーターの適合性

1. セールスエージェントに対して認証します
2. リクエストスキーマで定義された必須フィールドを含めます
3. 完了アーティファクトのウェブフック配信を含め、タスクレベルの非同期レスポンス（submitted、working、input-required）を処理します
4. 後続の操作でメディアバイを参照するために media_buy_id を使用します
5. クリエイティブアップロードの creative_deadline を遵守します

​

実装ノート

​

レスポンスタイムの目安

​

冪等性

• 同じアカウントに対して idempotency_key が以前に見られた場合、セールスエージェントは既存のリソースを返すべきです
• これにより重複作成なしに安全なリトライが可能になります

​

人間参加型

• セラーが内部の人（例: IO への署名、トラフィックマネージャーのレビュー）を待っている場合、セールスエージェントはレビュアーが動くまでタスクを status: "submitted" に保たなければなりません。完了すると、タスクは completed へ遷移し、最終アーティファクトが media_buy_id と完全な成功ペイロードを運びます。
• セラーがバイヤーの応答を必要とする場合（例: 事前承認された上限を超える予算の確認）、セールスエージェントは何が必要かを説明するメッセージとともに status: "input-required" を返さなければなりません。バイヤーは同じ A2A コンテキスト内で応答します。
• セールスエージェントはタスクのメッセージで推定承認タイムラインを提供すべきです。
• オーケストレーターはポーリングではなく、完了通知のためのウェブフックハンドラー（push_notification_config 経由）を実装すべきです。

​

スキーマリファレンス