> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# メディアバイ仕様

> AdCP メディアバイ仕様 — エージェント間広告のトランスポート層、タスク定義、JSONスキーマ、認証、およびコンプライアンス要件。

<Info>
  **AdCP 3.0 提案** - この仕様は AdCP 3.0 向けに開発中です。フィードバックは [GitHub Discussions](https://github.com/adcontextprotocol/adcp/discussions) から歓迎します。
</Info>

**ステータス**: コメント募集中
**最終更新**: 2026年2月

本ドキュメントにおけるキーワード「MUST」「MUST NOT」「REQUIRED」「SHALL」「SHALL NOT」「SHOULD」「SHOULD NOT」「RECOMMENDED」「MAY」「OPTIONAL」は、[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) に記載された定義に従って解釈されます。

## 概要

メディアバイプロトコルは、AI による広告自動化のための標準インターフェースを定義します。このプロトコルにより、AIエージェントは広告インベントリの発見、キャンペーンの作成・管理、クリエイティブアセットの同期、自然言語インタラクションを通じたパフォーマンストラッキングを行えるようになります。

## プロトコルの概要

メディアバイプロトコルが提供する機能:

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

## トランスポート要件

セールスエージェントは以下のトランスポートのうち少なくとも1つをサポートしなければなりません。

| トランスポート | プロトコル                  | 説明                          |
| ------- | ---------------------- | --------------------------- |
| MCP     | Model Context Protocol | JSON-RPC によるツールベースのインタラクション |
| A2A     | Agent-to-Agent         | メッセージベースのインタラクション           |

セールスエージェントは優先トランスポートとして MCP をサポートすべきです。

セールスエージェントは `get_adcp_capabilities` を通じてメディアバイプロトコルのサポートを宣言しなければなりません。

```json theme={null}
{
  "$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"]
  }
}
```

## コアコンセプト

### リクエストロール

すべてのメディアバイリクエストには3つのエンティティが関与します。

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

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

**パブリッシャーセールスエージェント** — 単一パブリッシャーのインベントリを代表する:

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

**アグリゲーターセールスエージェント** — 複数のパブリッシャーを代表する:

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

### 識別子

* **`media_buy_id`**: メディアバイの一意識別子。セールスエージェントは作成成功時にこれを返さなければなりません。オーケストレーターはメディアバイに対するすべての後続操作にこれを使用しなければなりません。`media_buy_id` は、認証済みアカウントが所有するセラーのアドサーバー上の任意のオーダーへの安定したハンドルです——元々 AdCP 経由で発注されたオーダーに限りません。

* **`package_id`**: メディアバイ内のパッケージの一意識別子。セールスエージェントは作成された各パッケージに対してこれを返さなければなりません。

* **`idempotency_key`**: 安全なリトライのためのクライアント生成の一意キー。同じアカウントに対して重複キーを受け取ったセールスエージェントは、再実行するのではなく元のレスポンスを返さなければなりません。

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

AdCP はセラーの広告オペレーションに対するプロトコルであり、その傍らに置かれる影の台帳ではありません。アカウントスコープのタスク（`get_media_buys`、`get_media_buy_delivery`、`update_media_buy`、該当する場合はクリエイティブの同期）は、リソースがどのサーフェスを通じて作成されたかではなく、**アカウントの所有権**によってスコープされます。セールスエージェントは、これらのタスクのために自身のインベントリを「AdCP 管理」と「AdCP 外」のサブセットに分割してはなりません（MUST NOT）。

具体的には:

* `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` で返すセラーは非準拠です。その振る舞いはバイを隠しているのと区別がつかず、上記のルールの規範的な意図を無効にするからです。

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

セラーが、あるバイの集合を呼び出し元の運用上の到達範囲の外に置く正当な理由を持つ場合——子セラーのモデル、NDA スコープの PMP ディール、サンドボックスと本番の分離、テナントレベルのプライバシー分割——正しいメカニズムはアカウント内でのフィルタリングではなく、**アカウントの分割**です:

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

アカウント境界は、アクセス分割のための AdCP のプリミティブです。`get_agent_capabilities` は、あるアカウントに対して付与されたスコープを調べるためのサーフェスです。呼び出し元は自分が見られるものを見られます。見られないものは、彼らが持たないアカウント参照の背後にあります。アカウント内でのフィルタリング——あるアカウントに権限を持つ呼び出し元に対して、そのアカウントのバイの一部しか返さないこと——は、このルールが禁じる影の台帳の問題を再導入します。

### 非同期オペレーション

メディアバイプロトコルは設計上非同期です。オペレーションは即座に返ってくる場合も、延長された処理が必要な場合もある:

* **同期レスポンス**: セールスエージェントは完了した結果を即座に返してもよい
* **非同期レスポンス**: セールスエージェントはタスクリファレンスとともに `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）。

オーケストレーターはすべてのレスポンスタイプを処理しなければならず、同期完了を前提としてはなりません。

### メディアバイの状態遷移

メディアバイは定義された状態の集合を進みます。終端状態（`completed`、`rejected`、`canceled`）からのそれ以上の遷移はありません。

```
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` を表明しているセラーでは、[割り当ての状態とクリエイティブの状態](/docs/creative/creative-libraries#creative-state-and-assignment-state-are-separate)に従ってクリエイティブはクリエイティブライブラリに残り、後続の `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](https://github.com/adcontextprotocol/adcp/issues/2260) で追跡されているクリエイティブ保持の契約で規定されます。その契約が着地するまでの間、長期の再利用に依拠するバイヤーは、解放されたクリエイティブを新しいバイで参照する前に `list_creatives` で永続性を確認すべきです（SHOULD）。

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

`revision` はメディアバイの楽観的並行性制御のトークンです。`update_media_buy` のワイヤーフィールド名は `revision` です。実装が内部的に `expected_revision` と呼んでもかまいませんが、セマンティクスは同じです: 呼び出し元は「現在保存されているメディアバイのリビジョンがまだこの値と等しい場合にのみ、この更新を適用せよ」と言っているのです。

セラーは、状態を変更するすべての更新について、永続化の境界でリビジョンのチェックをアトミックに強制しなければなりません（MUST）。アプリケーションのメモリ内での read-compare-write のシーケンスは、別のライターと競合して更新の喪失を許してしまう可能性があります。更新と比較は、一つのデータベーストランザクション、条件付き更新、または同等のアトミックなプリミティブの中に属します。不一致の場合は `CONFLICT` を返し、メディアバイは変更しないままにします。

状態を変更する更新は `revision` を増加させ、新しい値を返します。これには予算、フライト日、ターゲティング、ステータス、パッケージ、クリエイティブの割り当て、レポーティングのウェブフック、請求書送付先、コミット済みメトリクスの変更が含まれます。バリデーションのみのリクエスト、既に適用された操作の完全な冪等の再実行、`get_media_buys` による読み取りでは、リビジョンは増えません。

バイヤーは、状態変更を意図したすべての `update_media_buy` 呼び出しで、最後に観測した `revision` を渡すべきです（SHOULD）。リクエストフィールドは後方互換性のために任意のままです。`revision` が存在する場合、セラーは書き込みとアトミックにそれを比較し、古い値を `CONFLICT` で拒否しなければなりません（MUST）。`CONFLICT` の場合は、`get_media_buys` でメディアバイを再読み込みし、現在の状態と突き合わせてから、新しい `revision` と新鮮な `idempotency_key` でリトライします。

`confirmed_at` はセラーのコミットのタイムスタンプであり、配信ステータスのタイムスタンプではありません。一度値が入ると、その後の一時停止、再開、キャンセル、完了、レポーティングの遷移を通じて安定したままです。バイヤーに `media_buy_id` を返さない場合は `submitted` のレスポンス分岐を使います。セラーは代わりに、暫定的なバイに対して `media_buy_id`、`packages`、`confirmed_at: null` を伴う同期的な成功を返してもかまいません（MAY）。そのようなバイは `get_media_buys` で取得可能でなければならず（MUST）、コミット時に `confirmed_at` をちょうど一度設定することで遷移しなければなりません（MUST）。`confirmed_at: null` の暫定的なバイは `active` であってはならず（MUST NOT）、`packages[].committed_metrics` を含んでもなりません（MUST NOT）。

**パッケージレベルのライフサイクル:**

パッケージはメディアバイと同じ一時停止/キャンセルのパターンに従います。加えて:

* パッケージは `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）。

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

**スキーマ**: [`enums/creative-approval-status.json`](https://adcontextprotocol.org/schemas/v3/enums/creative-approval-status.json)

各パッケージは、クリエイティブのライブラリレベルのステータスとは別に、クリエイティブごとの承認ステータスを追跡します。クリエイティブがライブラリでは `approved` でありながら、特定のパッケージでは `rejected` であることもあります（例: そのプレースメントに対してフォーマットが誤っている）。

| ステータス            | 説明                                              |
| ---------------- | ----------------------------------------------- |
| `pending_review` | クリエイティブが送信され、プラットフォームのレビュー待ち                    |
| `approved`       | このパッケージでの配信についてクリエイティブが承認済み                     |
| `rejected`       | このパッケージについてクリエイティブが拒否された。`rejection_reason` を参照 |

拒否は終端ではありません——バイヤーはクリエイティブを修正し、セラーが表明しているクリエイティブの経路を通じて再送信します。これにより承認は `pending_review` にリセットされます。再送信の経路:

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

**`creative_deadline` との相互作用:** クリエイティブがパッケージの `creative_deadline` の後に拒否された場合、バイヤーはそれでも再送信してもかまいません（MAY）——バイヤーはセラーが特定した問題を修正しているのですから、セラーは期限を過ぎていても拒否されたクリエイティブの再送信を受け入れるべきです（SHOULD）。遅れた再送信を受け入れられないセラーは `CREATIVE_DEADLINE_EXCEEDED` を返さなければなりません（MUST）。

### 検証タグの強制

確定したパッケージの `performance_standards` が `vendor` を持つエントリを含む場合、そのパッケージに割り当てられるクリエイティブは、指定された各ベンダーに対応する `url_type: "tracker_script"` または `url_type: "tracker_pixel"` の URL アセットを少なくとも一つ含まなければなりません（MUST）。セールスエージェントは、必要な検証タグを欠くクリエイティブの割り当てを、`CREATIVE_REJECTED` と、不足しているベンダータグを特定する `details` メッセージとともに拒否すべきです（SHOULD）。バイヤーエージェントは、クリエイティブを送信する前に、合意された `measurement_terms` に基づいてベンダータグを事前に含めておくべきです（SHOULD）。

## タスク

メディアバイプロトコルは以下のタスクを定義します。完全なリクエスト/レスポンススキーマと例については、タスクリファレンスページを参照すること。

### get\_products

**スキーマ**: [`media-buy/get-products-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/get-products-request.json) / [`media-buy/get-products-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/get-products-response.json)

**リファレンス**: [`get_products` タスク](/docs/media-buy/task-reference/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` を含めなければなりません
* セールスエージェントは複数の商品が一致する場合、関連性スコアを含めるべきです

**リファインメント要件:**

`buying_mode: "refine"` を持つ各 `get_products` リクエストは自己完結している — セールスエージェントはトランスポートレベルのセッション状態に依存してはなりません。各リクエストの `refine` 配列と `filters` がリファインメントの意図を完全に指定します。セラーは自身の商品およびプロポーザルレジストリを維持します。「ステートレス」とは、プロトコル交換がコール間で暗黙的な状態を持たないことを意味します。これによりステートレスな実装と安全なリトライが可能になります。

* セールスエージェントは、商品エントリおよびプロポーザルのリファインエントリで `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

**スキーマ**: [`media-buy/list-creative-formats-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/list-creative-formats-request.json) / [`media-buy/list-creative-formats-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/list-creative-formats-response.json)

**リファレンス**: [`list_creative_formats` タスク](/docs/creative/task-reference/list_creative_formats)

クリエイティブフォーマットの要件と仕様を発見します。

**要件:**

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

### create\_media\_buy

**スキーマ**: [`media-buy/create-media-buy-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/create-media-buy-request.json) / [`media-buy/create-media-buy-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/create-media-buy-response.json)

**リファレンス**: [`create_media_buy` タスク](/docs/media-buy/task-reference/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/update-media-buy-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/update-media-buy-request.json) / [`media-buy/update-media-buy-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/update-media-buy-response.json)

**リファレンス**: [`update_media_buy` タスク](/docs/media-buy/task-reference/update_media_buy)

既存のメディアバイの予算、ターゲティング、または設定を変更します。

**パッケージの操作**は構造的に明示的です——操作の種類は、パッケージがリクエストのどこに現れるかで決まります:

| 操作        | リクエスト上の位置                         | 説明                                   |
| --------- | --------------------------------- | ------------------------------------ |
| **新規**    | `new_packages[]`                  | メディアバイにパッケージを追加する                    |
| **変更**    | `packages[]`                      | 既存のパッケージを変更する（予算、ターゲティング、日付、クリエイティブ） |
| **キャンセル** | `canceled: true` を伴う `packages[]` | 既存のパッケージをキャンセルする（取り消し不可）             |

**要件:**

* オーケストレーターは `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

**スキーマ**: [`media-buy/sync-catalogs-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/sync-catalogs-request.json) / [`media-buy/sync-catalogs-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/sync-catalogs-response.json)

**リファレンス**: [`sync_catalogs` タスク](/docs/media-buy/task-reference/sync_catalogs)

セラーアカウントのカタログ（商品、インベントリ、ストア、垂直フィード）を同期します。

**要件:**

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

### list\_creatives

<Note>
  `list_creatives` は [クリエイティブプロトコル](/docs/creative/specification#list_creatives) で定義されています。クリエイティブライブラリをホストするセールスエージェントはクリエイティブプロトコルの一部として `list_creatives` を実装してもよい。[`list_creatives` タスクリファレンス](/docs/creative/task-reference/list_creatives)を参照すること。
</Note>

### sync\_creatives

<Note>
  `sync_creatives` は [クリエイティブプロトコル](/docs/creative/specification#sync_creatives) で定義されています。クリエイティブライブラリをホストするエージェントはクリエイティブプロトコルの一部として `sync_creatives` を実装します。[`sync_creatives` タスクリファレンス](/docs/creative/task-reference/sync_creatives)を参照すること。
</Note>

### get\_media\_buys

**スキーマ**: [`media-buy/get-media-buys-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/get-media-buys-request.json) / [`media-buy/get-media-buys-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/get-media-buys-response.json)

**リファレンス**: [`get_media_buys` タスク](/docs/media-buy/task-reference/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` を含めるべきです。これにより、エージェントが状態機械を内部に取り込む必要がなくなります。期待されるマッピング:

| ステータス                                 | 期待される `valid_actions`                                                                              |
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `pending_creatives`                   | `pause`、`cancel`、`sync_creatives`                                                                  |
| `pending_start`                       | `pause`、`cancel`、`sync_creatives`                                                                  |
| `active`                              | `pause`、`cancel`、`update_budget`、`update_dates`、`update_packages`、`add_packages`、`sync_creatives`  |
| `paused`                              | `resume`、`cancel`、`update_budget`、`update_dates`、`update_packages`、`add_packages`、`sync_creatives` |
| `completed` / `rejected` / `canceled` | *（空配列）*                                                                                            |

セラーはビジネスルールに基づいてアクションを省略してもかまいません（例: 契約上の義務がキャンセルを妨げる場合に `cancel` を省略する、プラットフォームがフライト途中の追加をサポートしない場合に `add_packages` を省略する）。

`pending_creatives` または `pending_start` が `paused: true` による作成時の保留を覆い隠している場合、セラーは、セットアップのブロッカーが解消する前にバイヤーが保留を解除できるよう、`resume` も含めるべきです。

`valid_actions` には変更操作のみが含まれます——読み取り専用の操作（`get_media_buys`、`get_media_buy_delivery`）は状態に関わらず常に許可されます。エージェントは `valid_actions` を最適化のヒントとして使うべきですが、`INVALID_STATE` エラーを適切に処理しなければなりません。`valid_actions` は並行操作によるリアルタイムの状態変化を反映していない可能性があるからです。アクションの不在は「このセラーが宣言していない」ことを意味するのであって、必ずしも「禁止されている」ことを意味しません。

クリエイティブの変更について、`valid_actions` にある `sync_creatives` はレガシーなクリエイティブ変更のアクションラベルであり、`sync_creatives` タスクが存在する証明ではありません。バイヤーはセラーが表明しているクリエイティブの経路を使います: `creative.has_creative_library: true` のセラーでは `sync_creatives` と `creative_assignments`、`media_buy.features.inline_creative_management: true` を表明しているインライン専用のセラーでは `update_media_buy` の `packages[].creatives` です。

* オーケストレーターは、`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/get-media-buy-delivery-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/get-media-buy-delivery-request.json) / [`media-buy/get-media-buy-delivery-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/get-media-buy-delivery-response.json)

**リファレンス**: [`get_media_buy_delivery` タスク](/docs/media-buy/task-reference/get_media_buy_delivery)

パフォーマンス指標とキャンペーン配信をトラッキングします。

**要件:**

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

### provide\_performance\_feedback

**スキーマ**: [`media-buy/provide-performance-feedback-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/provide-performance-feedback-request.json) / [`media-buy/provide-performance-feedback-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/provide-performance-feedback-response.json)

**リファレンス**: [`provide_performance_feedback` タスク](/docs/media-buy/task-reference/provide_performance_feedback)

パブリッシャーの最適化を可能にするためのパフォーマンスシグナルを送信します。

**要件:**

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

### sync\_event\_sources

**スキーマ**: [`media-buy/sync-event-sources-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/sync-event-sources-request.json) / [`media-buy/sync-event-sources-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/sync-event-sources-response.json)

**リファレンス**: [`sync_event_sources` タスク](/docs/media-buy/task-reference/sync_event_sources)

アップサートセマンティクスでコンバージョントラッキング用のイベントソースをセラーアカウントに設定します。

**要件:**

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

### log\_event

**スキーマ**: [`media-buy/log-event-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/log-event-request.json) / [`media-buy/log-event-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/log-event-response.json)

**リファレンス**: [`log_event` タスク](/docs/media-buy/task-reference/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

**スキーマ**: [`media-buy/sync-audiences-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/sync-audiences-request.json) / [`media-buy/sync-audiences-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/sync-audiences-response.json)

**リファレンス**: [`sync_audiences` タスク](/docs/media-buy/task-reference/sync_audiences)

セラーアカウントでファーストパーティ CRM オーディエンスを管理します。ハッシュ化された顧客リストをアップロードし、マッチングステータスを確認し、ターゲティングオーバーレイで結果のオーディエンスを参照します。

**要件:**

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

## エラーハンドリング

セールスエージェントは [AdCP 標準エラースキーマ](/docs/building/by-layer/L3/error-handling) を使用してエラーを返さなければなりません。

一般的なエラーコード:

* `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`: 認証情報は提示されたが拒否されました（期限切れ/失効/不正な形式）。復旧: 終端。

## セキュリティの考慮事項

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

すべてのメディアバイプロトコル通信は TLS 1.2 以上の HTTPS を使用しなければなりません。

### 認証

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

### 予算認可

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

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

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

## 適合性

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

適合するメディアバイプロトコルのセールスエージェントは以下を行わなければなりません:

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

すべての AdCP プロトコルにまたがる必須タスクと任意タスクの統合ビューについては、[プロトコル別の必須タスク](/docs/protocol/required-tasks)を参照してください。

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

適合するメディアバイプロトコルのオーケストレーターは以下を行わなければなりません:

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

## 実装ノート

### レスポンスタイムの目安

セールスエージェントは以下のレスポンスタイムを目標とすべきだ:

| オペレーション種別                          | 目標レイテンシ |
| ---------------------------------- | ------- |
| 単純な参照（list\_creative\_formats）     | 1秒未満    |
| AI/LLM を使った発見（get\_products）       | 60秒未満   |
| レポートクエリ（get\_media\_buy\_delivery） | 60秒未満   |
| キャンペーン操作（create、update、sync）       | 非同期でも可  |

### 冪等性

セールスエージェントは `idempotency_key` を使った冪等なオペレーションをサポートすべきだ:

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

ミューテーションタスク（`update_media_buy`、`sync_creatives`）では、オーケストレーターは安全なリトライのために `idempotency_key`（16〜255文字）を含めてもよい。レスポンスなしでリクエストが失敗した場合、同じ `idempotency_key` で再送することで最大1回の実行が保証されます。

### 人間参加型

セールスエージェントはどの操作に対しても人間の承認を要求してもよい。承認は**タスクレイヤー**でモデル化されます:

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

`pending_approval` はメディアバイやタスクの有効なステータスではありません——その値は（アカウントのオンボーディングレビュー向けに）`Account.status` にのみ存在します。メディアバイやタスクレベルの承認のために転用しないでください。

## スキーマリファレンス

| スキーマ                                                                                                                            | 説明                       |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| [`media-buy/get-products-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/get-products-request.json)           | get\_products リクエスト      |
| [`media-buy/get-products-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/get-products-response.json)         | get\_products レスポンス      |
| [`media-buy/create-media-buy-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/create-media-buy-request.json)   | create\_media\_buy リクエスト |
| [`media-buy/create-media-buy-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/create-media-buy-response.json) | create\_media\_buy レスポンス |
| [`media-buy/update-media-buy-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/update-media-buy-request.json)   | update\_media\_buy リクエスト |