AdCP — サンドボックスモード

概要

サンドボックスモードを使用すると、バイヤーは実際のプラットフォームコールや実際の費用なしに、メディア購入のライフサイクル全体 — 発見、キャンペーン作成、クリエイティブ、配信 — をテストできます。レスポンスにはシミュレートされたが現実的なデータが含まれます。サンドボックスはリクエストごとではなくアカウントレベルで機能します。リクエストがサンドボックスアカウントを参照すると、リクエスト全体がサンドボックスとして扱われる。これにより、マルチステップフローで実際のトラフィックとテストトラフィックを誤って混在させるリスクを排除します。

ケイパビリティの発見

セラーは get_adcp_capabilities でサンドボックスサポートを宣言する:

{
  "account": {
    "sandbox": true
  }
}

サンドボックスモードを使用する前にこれを確認します。account.sandbox が宣言されていないか false の場合、セラーはサンドボックスをサポートしていません。

サンドボックスへの2つの経路

サンドボックスモードへの入り方は、セラーのアカウントモデル（require_operator_auth）によって異なります。2つの経路はまったく異なる — 正しい方に従うようにすること。

バイヤー宣言アカウント（`require_operator_auth: false`）

セラーはエージェントを信頼し、オペレーターごとの認証を必要としません。サンドボックスはナチュラルキーの一部だ — 同じブランド/オペレーターのペアがプロダクションとサンドボックスの両方のアカウントを持つことができ、sandbox: true で区別されます。 セットアップ: アカウントエントリに sandbox: true を付けて sync_accounts でサンドボックスアカウントを宣言する:

// sync_accounts — サンドボックスアカウントを宣言する
{
  "accounts": [{
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "billing": "operator",
    "sandbox": true
  }]
}

使用方法: すべてのリクエストで sandbox: true を付けたナチュラルキーでサンドボックスアカウントを参照する:

// get_products — バイヤー宣言サンドボックス
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "brief": "Premium CTV inventory for Q2 campaign"
}

アカウント ID 名前空間（`require_operator_auth: true`）

セラーは各オペレーターが直接認証することを要求します。サンドボックスアカウントはセラーのプラットフォーム上の既存のテストアカウントだ — Stripe のテストモード、Google Ads サンドボックスアカウント、Snap のテスト広告主アカウントのようなもの。作成するのではなく、発見します。 セットアップ: sandbox: true フィルターを使って list_accounts でサンドボックスアカウントを発見する:

// list_accounts — サンドボックスアカウントを探す
{
  "sandbox": true
}

セラーは既存のテストアカウントを返します:

{
  "accounts": [{
    "account_id": "acct_sandbox_acme_001",
    "name": "Acme Test Account",
    "status": "active",
    "sandbox": true
  }]
}

使用方法: すべてのリクエストで account_id でサンドボックスアカウントを参照する:

// get_products — アカウント ID 名前空間サンドボックス
{
  "account": { "account_id": "acct_sandbox_acme_001" },
  "brief": "Premium CTV inventory for Q2 campaign"
}

クイックリファレンス

	バイヤー宣言（`require_operator_auth: false`）	アカウント ID 名前空間（`require_operator_auth: true`）
サンドボックスアカウント	バイヤーが `sync_accounts` で宣言	セラーのプラットフォームに既存
発見方法	N/A — バイヤーが作成	`sandbox: true` で `list_accounts`
アカウント参照	`sandbox: true` を持つナチュラルキー	`account_id`
実世界の類似	セルフサービステストモード	Stripe テストモード、Google Ads サンドボックス

レスポンスの確認

成功レスポンスには sandbox: true が含まれ、リクエストがサンドボックスモードで処理されたことを確認します:

{
  "products": [...],
  "sandbox": true
}

完全なライフサイクルの例（バイヤー宣言アカウント）

この例はバイヤー宣言アカウントのパスを示します。アカウント ID 名前空間の場合、サンドボックスアカウントを list_accounts（またはセラー定義 ID のためのアウトオブバンドのオンボーディング）を通じて解決してから、各ステップのナチュラルキーアカウント参照を { "account_id": "acct_sandbox_acme_001" } に置き換える。

1. 商品の発見

// get_products
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "brief": "CTV inventory for brand awareness"
}

2. メディアバイの作成

// create_media_buy
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "proposal_id": "prop_abc",
  "total_budget": { "amount": 50000, "currency": "USD" },
  "brand": { "domain": "acme-corp.com" },
  "start_time": { "start_type": "asap" },
  "end_time": "2026-04-01T00:00:00Z"
}

セラーはリアルな ID、パッケージ、クリエイティブ締め切りを持つシミュレートされたメディアバイを返す — 実際のプラットフォームには何も予約されない。

3. クリエイティブのアップロード

// sync_creatives
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "creatives": [{
    "creative_id": "hero_video_30s",
    "name": "Brand Hero Video 30s",
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "video_standard_30s"
    },
    "assets": {
      "video": {
        "url": "https://cdn.example.com/hero.mp4",
        "width": 1920,
        "height": 1080,
        "duration_ms": 30000
      }
    }
  }],
  "assignments": {
    "hero_video_30s": ["pkg_001"]
  }
}

4. 配信の確認

// get_media_buy_delivery
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "media_buy_ids": ["mb_sandbox_123"]
}

セラーはシミュレートされた配信メトリクス — インプレッション、スペンド、ペーシング — をキャンペーンが実行中であるかのように返します。

サンドボックス vs ドライラン

一部の sync タスク（sync_creatives、sync_catalogs）は dry_run パラメータをサポートします。これらは異なる目的を持ちます:

	サンドボックスアカウント	`dry_run`
意味	何も実際ではない	変更を適用せずにプレビュー
スコープ	アカウント上のすべてのタスク	sync タスクのみ
副作用	なし（シミュレート）	なし（プレビューのみ）
ユースケース	完全なライフサイクルのテスト	コミット前に同期が何を変えるかを確認

これらは組み合わせられます——サンドボックスアカウントでの dry_run: true は、サンドボックスの状態すら更新せずに同期をプレビューします。

X-Dry-Run、X-Test-Session-ID、X-Mock-Time の HTTP ヘッダーは非推奨です。サンドボックスモードが、プロトコルレベルのパラメータとしてそれらを置き換えます。

セラーはこれらのヘッダーに基づいて挙動を変えてはなりません（MUST NOT）。サンドボックスモードはアカウント参照のみで決まります。セラーはヘッダーを完全に無視すべきであり（SHOULD）、バイヤーが古い統合を特定するのを助けるために非推奨の警告をログに記録してもかまいません（MAY）。
バイヤーはプロダクションの副作用を防ぐためにこれらのヘッダーに頼ってはなりません（MUST NOT）。アカウント参照の sandbox: true のみがサンドボックスセマンティクスを保証します。

セラーの実装

リクエストがサンドボックスアカウントを参照する場合（ナチュラルキーの sandbox: true またはサンドボックスの account_id を通じて）、エージェントはプロダクションの状態を永続化したり実世界の副作用を引き起こしたりしてはなりません（MUST NOT）:

実際の広告プラットフォーム API コール（実際の注文、ラインアイテムなど）を行ってはならない（MUST NOT）
実際のお金を請求したり、実際の請求レコードを作成してはならない（MUST NOT）
プロダクションと同じ方法で入力を検証しなければならない（MUST）（無効な予算、不正な日付などを拒否します）
シミュレートされたデータを含むリアルなレスポンスシェイプを返さなければならない（MUST）
成功レスポンスに sandbox: true を含めるべきだ（SHOULD）

サンドボックスのエラーは実際の検証エラーです。バイヤーがサンドボックスアカウントを使用して無効な予算を送信した場合、実際のエラーを返す — 偽のエラーをシミュレートしません。 アカウント ID 名前空間のセラー: プラットフォームに list_accounts が sandbox: true でフィルタリングした際に返すことができる既存のサンドボックス/テストアカウントがあることを確認するか、サンドボックス ID をアウトオブバンドで供給します。 バイヤー宣言アカウントのセラー: sync_accounts とアカウント参照でナチュラルキーの一部として sandbox: true を受け入れる。(brand, operator, sandbox: true) を (brand, operator) とは別のアカウントとして扱います。

プロトコルコンプライアンス

ケイパビリティで account.sandbox: true を宣言するセラーは以下をしなければなりません (MUST):

アカウントモデルに適したサンドボックスアカウントを受け入れる
サンドボックスアカウントを参照するすべてのリクエストにサンドボックスセマンティクスを適用します
サンドボックスリクエストを処理する際、プロダクションの状態を永続化したり実世界の副作用を引き起こしたりしない
通常の入力検証を適用する（サンドボックスは検証をバイパスしない）

セラーはサンドボックスアカウントリクエストを処理する際に成功レスポンスに sandbox: true を含めるべきだ (SHOULD)。

はじめに

AdCP で構築する

プロトコル

FAQ

トラストとセキュリティ

リファレンス

AAO

認定

サンドボックスモード

概要

ケイパビリティの発見

サンドボックスへの2つの経路

バイヤー宣言アカウント（`require_operator_auth: false`）

アカウント ID 名前空間（`require_operator_auth: true`）

クイックリファレンス

レスポンスの確認

完全なライフサイクルの例（バイヤー宣言アカウント）

1. 商品の発見

2. メディアバイの作成

3. クリエイティブのアップロード

4. 配信の確認

サンドボックス vs ドライラン

セラーの実装

プロトコルコンプライアンス

​概要

​ケイパビリティの発見

​サンドボックスへの2つの経路

​バイヤー宣言アカウント（require_operator_auth: false）

​アカウント ID 名前空間（require_operator_auth: true）

​クイックリファレンス

​レスポンスの確認

​完全なライフサイクルの例（バイヤー宣言アカウント）

​1. 商品の発見

​2. メディアバイの作成

​3. クリエイティブのアップロード

​4. 配信の確認

​サンドボックス vs ドライラン

​セラーの実装

​プロトコルコンプライアンス

概要

ケイパビリティの発見

サンドボックスへの2つの経路

バイヤー宣言アカウント（`require_operator_auth: false`）

アカウント ID 名前空間（`require_operator_auth: true`）

クイックリファレンス

レスポンスの確認

完全なライフサイクルの例（バイヤー宣言アカウント）

1. 商品の発見

2. メディアバイの作成

3. クリエイティブのアップロード

4. 配信の確認

サンドボックス vs ドライラン

セラーの実装

プロトコルコンプライアンス