メディアバイ仕様

​

概要

​

プロトコルの概要

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

​

トランスポート要件

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/protocol/get-adcp-capabilities-response.json",
  "adcp": { "major_versions": [2] },
  "supported_protocols": ["media_buy"]
}

​

コアコンセプト

​

リクエストロール

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

​

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

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

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

​

識別子

• media_buy_id: メディアバイの一意識別子。セールスエージェントは作成成功時にこれを返さなければなりません。オーケストレーターはメディアバイに対するすべての後続操作にこれを使用しなければなりません。
• package_id: メディアバイ内のパッケージの一意識別子。セールスエージェントは作成された各パッケージに対してこれを返さなければなりません。
• idempotency_key: 安全なリトライのためのクライアント生成の一意キー。同じアカウントに対して重複キーを受け取ったセールスエージェントは、再実行するのではなく元のレスポンスを返さなければなりません。

​

非同期オペレーション

• 同期レスポンス: セールスエージェントは完了した結果を即座に返してもよい
• 非同期レスポンス: セールスエージェントはタスクリファレンスとともに status: "submitted" または status: "working" を返してもよい
• 人間参加型: セールスエージェントは手動承認を要求してもよく、その場合 status: "pending_approval" で示します
• 拒否: セールスエージェントは作成後にメディアバイを拒否してもよく、その場合 status: "rejected" で示します。オーケストレーターは rejected を終端状態として扱わなければなりません。

​

タスク

​

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、id、action を提供しなければなりません
• オーケストレーターは単一の refine 配列に同一の商品IDまたはプロポーザルIDを持つ複数のエントリを含めてはなりません
• セールスエージェントはブリーフが提供された場合、ブリーフ条件に一致する商品を返さなければなりません
• セールスエージェントは各商品に product_id と pricing_options を含めなければなりません
• セールスエージェントは複数の商品が一致する場合、関連性スコアを含めるべきです

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

​

list_creative_formats

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

​

create_media_buy

• オーケストレーターは packages 配列または proposal_id のいずれかを含めなければなりません
• オーケストレーターはキャンペーンの start_time と end_time を含めなければなりません
• セールスエージェントは作成成功時に media_buy_id を返さなければなりません
• セールスエージェントはクリエイティブをアップロードしなければなりません期限を示す creative_deadline を返さなければなりません
• セールスエージェントは価格オプションに対して予算を検証しなければなりません
• 検証失敗時、セールスエージェントは errors 配列を返さなければなりません

​

update_media_buy

• オーケストレーターは media_buy_id を含めなければなりません
• セールスエージェントは PATCH セマンティクスを適用しなければなりません: 指定されたフィールドのみ更新され、省略されたフィールドは変更されない
• セールスエージェントはステータスが completed のメディアバイへの更新をエラーコード INVALID_STATE で拒否しなければなりません
• セールスエージェントは更新適用後（または承認保留中の場合は提案された状態）の直接変更された各パッケージの状態を含む 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）を使用すべきです
• セールスエージェントは一致した各メディアバイの現在のメディアバイステータスとパッケージレベルの運用状態を返さなければなりません
• セールスエージェントはメディアバイ通貨を含めなければならず、通貨フィールドを一貫して表示しなければなりません（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 を含めなければなりません
• セールスエージェントはパッケージレベルで配信指標を返さなければなりません
• セールスエージェントはリクエストされた場合、次元ごとの内訳を含めるべきです
• セールスエージェントはデータの鮮度を示す 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 ハッシュ化された識別子を受け入れなければなりません

​

エラーハンドリング

• MEDIA_BUY_NOT_FOUND: 参照されたメディアバイが存在しません
• PACKAGE_NOT_FOUND: 参照されたパッケージが存在しません
• PRODUCT_NOT_FOUND: 参照された商品が存在しません
• BUDGET_EXCEEDED: 操作が割り当て予算を超過します
• CREATIVE_REJECTED: クリエイティブが検証または承認に失敗しました
• INVALID_STATE: メディアバイの現在のステータスではその操作が許可されていない（例: 完了したメディアバイの更新）
• VALIDATION_ERROR: リクエストフォーマットまたはパラメータのエラー
• UNAUTHORIZED: 操作に対する権限が不足しています

​

セキュリティの考慮事項

​

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

​

認証

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

​

予算認可

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

​

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

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

​

適合性

​

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

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

​

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

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

​

実装ノート

​

レスポンスタイムの目安

​

冪等性

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

​

人間参加型

• セールスエージェントは status: "pending_approval" を返さなければなりません
• セールスエージェントは推定承認タイムラインを提供すべきです
• オーケストレーターはステータス更新のための Webhook ハンドラーを実装すべきです

​

スキーマリファレンス