AdCP — create_media

選択したパッケージからメディアバイを作成するか、プロポーザルを実行します。必要に応じたバリデーションや承認、キャンペーン作成を処理します。 2 つのモードをサポート:

Manual Mode: packages 配列で明示的にラインアイテムを指定
Proposal Mode: proposal_id と total_budget を指定し、get_products のプロポーザルを実行

Response Time: 即時〜日単位（completed、120 秒未満の working、数時間〜数日の submitted） Request Schema: /schemas/v3/media-buy/create-media-buy-request.json Response Schema: /schemas/v3/media-buy/create-media-buy-response.json

クイックスタート

2 つのパッケージでシンプルなメディアバイを作成:

import { testAgent } from '@adcp/client/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/client';

// Calculate dates dynamically - start tomorrow, end in 90 days
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(0, 0, 0, 0);
const endDate = new Date(tomorrow);
endDate.setDate(endDate.getDate() + 90);

const result = await testAgent.createMediaBuy({
  brand: {
    domain: 'acmecorp.com'
  },
  packages: [
    {
      product_id: 'prod_d979b543',
      pricing_option_id: 'cpm_usd_auction',
      format_ids: [
        {
          agent_url: 'https://creative.adcontextprotocol.org',
          id: 'display_300x250_image'
        }
      ],
      budget: 2500,
      bid_price: 5.00
    },
    {
      product_id: 'prod_e8fd6012',
      pricing_option_id: 'cpm_usd_auction',
      format_ids: [
        {
          agent_url: 'https://creative.adcontextprotocol.org',
          id: 'display_300x250_html'
        }
      ],
      budget: 2500,
      bid_price: 4.50
    }
  ],
  start_time: tomorrow.toISOString(),
  end_time: endDate.toISOString()
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

// Validate response against schema
const validated = CreateMediaBuyResponseSchema.parse(result.data);

// Check for errors (discriminated union response)
if ('errors' in validated && validated.errors) {
  throw new Error(`Failed to create media buy: ${JSON.stringify(validated.errors)}`);
}

if ('media_buy_id' in validated) {
  console.log(`Created media buy ${validated.media_buy_id}`);
  console.log(`Upload creatives by: ${validated.creative_deadline}`);
  console.log(`Packages created: ${validated.packages.length}`);
}

リクエストパラメーター

Parameter	Type	Required	Description
`account`	account-ref	Yes	アカウント参照。`{ "account_id": "..." }` または、セラーが暗黙的な解決をサポートする場合は `{ "brand": {...}, "operator": "..." }` を渡します。請求とポリシー評価に必要。
`proposal_id`	string	No*	`get_products` のプロポーザル ID。packages の代替
`total_budget`	TotalBudget	No*	プロポーザル実行時の総予算。配分割合はパブリッシャーが適用
`packages`	Package[]	No*	パッケージ構成の配列（下記）。proposal_id を使わない場合は必須
`brand`	BrandRef	Yes	ブランド参照 — 実行時に完全なアイデンティティに解決されます。brand.json 参照
`start_time`	string	Yes	`"asap"` または ISO 8601 日時
`end_time`	string	Yes	ISO 8601 日時（指定がなければ UTC）
`po_number`	string	No	発注番号
`idempotency_key`	string	No	安全なリトライのための一意キー。同じキーとアカウントのリクエストがすでに処理済みの場合、セラーは既存のメディアバイを返します。（セラー、リクエスト）ペアごとに一意でなければなりません。最低 16 文字。
`context`	object	No	レスポンスにそのまま返される不透明な相関データ。内部トラッキング、トレース ID、その他の呼び出し元固有の識別子に使用。
`reporting_webhook`	ReportingWebhook	No	レポーティングの自動配信設定

* Either packages OR (proposal_id + total_budget) must be provided.

TotalBudget オブジェクト

Parameter	Type	Required	Description
`amount`	number	Yes	総予算額
`currency`	string	Yes	ISO 4217 通貨コード

Package オブジェクト

Parameter	Type	Required	Description
`product_id`	string	Yes	`get_products` で取得した product_id
`pricing_option_id`	string	Yes	プロダクトの `pricing_options` 配列にある価格オプション ID
`format_ids`	FormatID[]	Yes	使用するフォーマット ID（プロダクトでサポートされている必要あり）
`budget`	number	Yes	価格オプションの通貨での予算
`impressions`	number	No	このパッケージのインプレッション目標
`paused`	boolean	No	一時停止状態で作成する場合（デフォルト: `false`）
`pacing`	string	No	`"even"`（デフォルト）、`"asap"`、`"front_loaded"`
`bid_price`	number	No	オークション価格の場合の入札額。選択した価格オプションに `max_bid: true` がない限り、指定した金額がそのまま入札/価格として扱われる。`max_bid: true` の場合はバイヤーの最大支払い意思額（上限）として扱われる。
`optimization_goals`	OptimizationGoal[]	No	このパッケージの最適化ターゲット。各ゴールは `kind: "event"`（`event_sources` 配列を持つコンバージョンイベント。オプションで `cost_per`、`per_ad_spend`、`maximize_value` ターゲットを指定可）または `kind: "metric"`（オプションで `cost_per` または `threshold_rate` ターゲットを持つセラー独自のメトリクス）。イベントゴールにはプロダクトの `conversion_tracking.supported_targets` が必要。メトリクスゴールには `metric_optimization.supported_metrics` が必要。
`targeting_overlay`	TargetingOverlay	No	追加ターゲティング条件（Targeting 参照）
`start_time`	string	No	このパッケージのフライト開始日時（ISO 8601）。省略するとメディアバイの `start_time` を継承。メディアバイの日付範囲内である必要があります。`"asap"` はサポートしません。
`end_time`	string	No	このパッケージのフライト終了日時（ISO 8601）。省略するとメディアバイの `end_time` を継承。メディアバイの日付範囲内である必要があります。
`creative_assignments`	CreativeAssignment[]	No	既存ライブラリのクリエイティブを重み/プレースメント指定付きで割り当て
`creatives`	CreativeAsset[]	No	新規アセットをアップロードして割り当て（`creative_id` は未使用であること）
`context`	object	No	パッケージレスポンスにそのまま返される不透明な相関データ。セラーが割り当てた `package_id` を内部ラインアイテム、キャンペーン構造、トラッキング状態にマッピングするために使用。

レスポンス

成功レスポンス

Field	Description
`media_buy_id`	パブリッシャーの一意 ID
`creative_deadline`	クリエイティブ提出期限 (ISO 8601)
`packages`	作成されたパッケージの配列（完全な状態付き）

エラーレスポンス

Field	Description
`errors`	失敗理由を示すエラーオブジェクト配列

Note: レスポンスは判別可能なユニオン。成功フィールドか errors のどちらかのみ返されるため、成功フィールドにアクセスする前に常に errors を確認してください。

主なシナリオ

ターゲティング付きキャンペーン

地理制限やフリークエンシーキャップを追加:

import { testAgent } from '@adcp/client/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/client';

// Calculate end date dynamically - 90 days from now
const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);

const result = await testAgent.createMediaBuy({
  brand: {
    domain: 'acmecorp.com'
  },
  packages: [{
    product_id: 'prod_d979b543',
    pricing_option_id: 'cpm_usd_auction',
    format_ids: [{
      agent_url: 'https://creative.adcontextprotocol.org',
      id: 'display_300x250_image'
    }],
    budget: 2500,
    bid_price: 5.00,
    targeting_overlay: {
      geo_countries: ['US'],
      geo_regions: ['US-CA', 'US-NY'],
      frequency_cap: {
        suppress: { interval: 60, unit: 'minutes' }
      }
    }
  }],
  start_time: 'asap',
  end_time: endDate.toISOString()
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
  throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}

if ('media_buy_id' in validated) {
  console.log(`Campaign ${validated.media_buy_id} created with targeting`);
}

コンバージョン最適化付きキャンペーン

コンバージョン最適化配信のために per_ad_spend ターゲットを設定します。プロダクトが conversion_tracking.supported_targets でサポートを宣言しており、sync_event_sources 経由でイベントソースが設定済みである必要があります:

import { testAgent } from '@adcp/client/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/client';

const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);

const result = await testAgent.createMediaBuy({
  brand: {
    domain: 'acmecorp.com'
  },
  packages: [{
    product_id: 'prod_retail_sp',
    pricing_option_id: 'cpc_usd_auction',
    budget: 10000,
    bid_price: 1.20,
    optimization_goals: [{
      kind: 'event',
      event_sources: [
        { event_source_id: 'retailer_sales', event_type: 'purchase', value_field: 'value' }
      ],
      target: { kind: 'per_ad_spend', value: 4.0 },
      priority: 1
    }]
  }],
  start_time: 'asap',
  end_time: endDate.toISOString()
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
  throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}

if ('media_buy_id' in validated) {
  console.log(`Campaign ${validated.media_buy_id} created with per_ad_spend target`);
}

カタログ連動パッケージ

カタログ連動パッケージは、カタログ全体のアイテムに対して単一の予算枠を割り当てます。アイテムごとにパッケージを個別作成する代わりに、プラットフォームがパフォーマンスに基づいてカタログ全アイテムへの配信を最適化します。これは Google Performance Max や Meta Dynamic Product Ads などのカタログベースのキャンペーンタイプに相当する AdCP の機能です。パッケージにカタログ連動を設定するには catalogs フィールドを含めます。各カタログはそれぞれ異なるタイプ（例：プロダクトカタログ 1 件、ストアカタログ 1 件）を持つ必要があります。参照するカタログは sync_catalogs 経由で事前に同期されている必要があります。 同期済みジョブカタログを使ったジョブキャンペーン:

test=false

{
  "brand": { "domain": "acme-restaurants.com" },
  "packages": [{
    "product_id": "prod_job_board",
    "pricing_option_id": "cpc_eur_auction",
    "budget": 5000,
    "bid_price": 2.50,
    "catalogs": [{
      "catalog_id": "chef-vacancies",
      "type": "job"
    }]
  }],
  "start_time": "asap",
  "end_time": "2026-06-30T23:59:59Z"
}

プロダクトカタログとストア集客圏ターゲティングを使ったリテールメディア:

test=false

{
  "brand": { "domain": "acmecorp.com" },
  "packages": [{
    "product_id": "prod_retail_sp",
    "pricing_option_id": "cpc_usd_auction",
    "budget": 10000,
    "bid_price": 1.20,
    "catalogs": [{
      "catalog_id": "gmc-primary",
      "type": "product",
      "tags": ["summer"]
    }],
    "targeting_overlay": {
      "store_catchments": [{
        "catalog_id": "retail-locations",
        "catchment_ids": ["drive"]
      }]
    }
  }],
  "start_time": "asap",
  "end_time": "2026-09-30T23:59:59Z"
}

プラットフォームはパフォーマンスに基づいてカタログアイテム間で予算を配分します。アイテムごとのレポートには、by_catalog_item ブレークダウンを返す get_media_buy_delivery を使用します。カタログ連動パッケージのクリエイティブバリアントは、広告としてレンダリングされた個別のカタログアイテムを表します。

クリエイティブをインライン指定したキャンペーン

キャンペーン作成と同時にクリエイティブをアップロードします:

import { testAgent } from '@adcp/client/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/client';

// Calculate end date dynamically - 90 days from now
const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);

const result = await testAgent.createMediaBuy({
  brand: {
    domain: 'acmecorp.com'
  },
  packages: [{
    product_id: 'prod_d979b543',
    pricing_option_id: 'cpm_usd_auction',
    format_ids: [{
      agent_url: 'https://creative.adcontextprotocol.org',
      id: 'display_300x250_image'
    }],
    budget: 2500,
    bid_price: 5.00,
    creatives: [{
      creative_id: 'hero_video_30s',
      name: 'Hero Video',
      format_id: {
        agent_url: 'https://creative.adcontextprotocol.org',
        id: 'display_300x250_image'
      },
      assets: {
        image: {
          url: 'https://cdn.example.com/hero-banner.jpg',
          width: 300,
          height: 250
        }
      }
    }]
  }],
  start_time: 'asap',
  end_time: endDate.toISOString()
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
  throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}

if ('packages' in validated) {
  console.log(`Campaign created with ${validated.packages[0].creative_assignments.length} creatives`);
}

レポート用 Webhook を設定したキャンペーン

自動レポート通知を受け取ります。

import { testAgent } from '@adcp/client/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/client';

// Calculate end date dynamically - 90 days from now
const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);

const result = await testAgent.createMediaBuy({
  brand: {
    domain: 'acmecorp.com'
  },
  packages: [{
    product_id: 'prod_d979b543',
    pricing_option_id: 'cpm_usd_auction',
    format_ids: [{
      agent_url: 'https://creative.adcontextprotocol.org',
      id: 'display_300x250_image'
    }],
    budget: 2500,
    bid_price: 5.00
  }],
  start_time: 'asap',
  end_time: endDate.toISOString(),
  reporting_webhook: {
    url: 'https://buyer.example.com/webhooks/reporting',
    authentication: {
      schemes: ['Bearer'],
      credentials: 'secret_token_xyz_minimum_32_chars'
    },
    reporting_frequency: 'daily',
    requested_metrics: ['impressions', 'spend', 'video_completions']
  }
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
  throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}

if ('media_buy_id' in validated) {
  console.log(`Campaign created - daily reports will be sent to webhook`);
}

プロポーザルの実行

get_products のプロポーザルを、パッケージを手作業で組まずに実行します。

import { testAgent } from '@adcp/client/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/client';

// Calculate end date dynamically - 90 days from now
const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);

const result = await testAgent.createMediaBuy({
  proposal_id: 'swiss_balanced_v1',  // From get_products response
  total_budget: {
    amount: 50000,
    currency: 'USD'
  },
  brand: {
    domain: 'acmecorp.com'
  },
  start_time: 'asap',
  end_time: endDate.toISOString()
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
  throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}

if ('media_buy_id' in validated) {
  // パブリッシャーがプロポーザルの配分をパッケージに変換
  console.log(`Created media buy ${validated.media_buy_id}`);
  console.log(`Packages created: ${validated.packages.length}`);
}

プロポーザルを実行する際:

パブリッシャーが total_budget を使って配分割合を実額に変換
配分に基づきパッケージが自動生成
それ以外のフィールド（brand、start_time、end_time など）は Manual モードと同じ

会話的なリファインを含む完全なフローは Proposals を参照。

エラーハンドリング

よくあるエラーと解決策:

Error Code	Description	Resolution
`PRODUCT_NOT_FOUND`	Invalid product_id	Verify product exists via `get_products`
`FORMAT_INCOMPATIBLE`	Format not supported by product	Check product’s `format_ids` field
`BUDGET_INSUFFICIENT`	Budget below product minimum	Increase budget or choose different product
`TARGETING_TOO_NARROW`	Targeting yields zero inventory	Broaden geographic or audience criteria
`POLICY_VIOLATION`	Brand/product violates policy	Review publisher’s content policies
`INVALID_PRICING_OPTION`	pricing_option_id not found	Use ID from product’s `pricing_options`
`CREATIVE_ID_EXISTS`	Creative ID already exists in library	Use a different `creative_id`, assign existing creatives via `creative_assignments`, or update via `sync_creatives`

Example error response:

{
  "errors": [{
    "code": "FORMAT_INCOMPATIBLE",
    "message": "Product 'prod_d979b543' does not support format 'display_728x90'",
    "field": "packages[0].format_ids",
    "suggestion": "Use display_300x250_image, display_300x250_html, or display_300x250_generative formats"
  }]
}

Key Concepts

フォーマット指定

フォーマット ID は各パッケージで必須です。理由は以下の通りです:

パブリッシャーが正しい仕様でアドサーバーにプレースホルダーを作成します
双方が必要なクリエイティブアセットを正確に把握できます
バリデーションによりプロダクトが要求フォーマットをサポートするか確認できます
進捗トラッキングで不足アセットを可視化できます

詳細は下記のフォーマットワークフローを参照。

ブランド参照

brand フィールドはポリシー準拠とビジネス目的のために広告主を識別します。

{
  "brand": {
    "domain": "acmecorp.com"
  }
}

ブランドの完全なアイデンティティデータ（色、フォント、プロダクトカタログ）は実行時に brand.json から解決されます。brand.json を参照。

価格と通貨

各パッケージは pricing_option_id を指定し、以下を決定します:

通貨（USD、EUR など）
価格モデル（CPM、CPCV、CPP など）
レートと固定/オークションの区別

セラーがサポートする場合、パッケージごとに異なる通貨を使用できます。Pricing Models 参照。

ターゲティングオーバーレイ

使用は最小限に — ターゲティングの大部分はブリーフに含め、プロダクト選択で処理されるべきです。オーバーレイは以下に限定して使用します:

地理的制限（RCT テスト、規制対応）
フリークエンシーキャップ
AXE セグメントの包含/除外

詳細は Targeting を参照。

フォーマットワークフロー

フォーマット指定が重要な理由

メディアバイ作成時にフォーマットを指定すると次が可能になります:

プレースホルダー作成 - パブリッシャーが正しい仕様でアドサーバーにプレースホルダーを用意
検証 - 要求フォーマットをプロダクトがサポートするかシステムが検証
期待値の明確化 - 双方が必要なものを正確に把握
進捗トラッキング - 不足アセットと必須アセットを可視化
技術セットアップ - クリエイティブ到着前にアドサーバーを設定

完全なワークフロー

list_creative_formats → 利用可能なフォーマット仕様を取得
get_products → プロダクトを発見（サポートする format_ids を返す）
互換性を検証 → 望むフォーマットをプロダクトがサポートするか確認
create_media_buy → フォーマットを指定（必須）
   └── パブリッシャーがプレースホルダーを作成
   └── クリエイティブ要件を明確化
sync_creatives → フォーマットに合致する実ファイルをアップロード
キャンペーン有効化 → プレースホルダーを実クリエイティブに置換

フォーマット検証

パブリッシャーが必ず検証する事項:

すべてのフォーマットがプロダクトでサポートされています
フォーマット仕様が list_creative_formats の出力と一致
期限内にクリエイティブ要件を満たせる

無効なフォーマットの例:

{
  "errors": [{
    "code": "FORMAT_INCOMPATIBLE",
    "message": "Product 'ctv_sports_premium' does not support format 'audio_standard_30s'",
    "field": "packages[0].format_ids",
    "supported_formats": [
      { "agent_url": "https://creative.adcontextprotocol.org", "id": "video_standard_30s" },
      { "agent_url": "https://creative.adcontextprotocol.org", "id": "video_standard_15s" }
    ]
  }]
}

フライト日程バリデーション

パッケージに start_time または end_time を指定した場合、セラーは以下を検証すべきだ:

両日程がメディアバイの日付範囲内に収まっています
start_time が end_time より前です

範囲外または逆転した日程は INVALID_REQUEST エラーを返すべきだ:

{
  "errors": [{
    "code": "INVALID_REQUEST",
    "message": "Package 'week_5' end_time 2026-04-05T23:59:59Z is after media buy end_time 2026-03-31T23:59:59Z",
    "field": "packages[3].end_time"
  }]
}

非同期オペレーション

このタスクは即時完了する場合も、複雑さや承認要件によっては日数を要する場合もあります。レスポンスの status フィールドで結果と次のアクションを確認してください。

Status	Meaning	Your Action
`completed`	即時完了	結果を処理
`working`	処理中（約2分）	高頻度でポーリング or Webhook を待つ
`submitted`	長時間（数時間〜日）	Webhook を使うか低頻度でポーリング
`input-required`	追加情報が必要	メッセージを読み、情報を返す
`failed`	エラー発生	エラーに対応

Note: 完全なステータス一覧は Task Lifecycle を参照。

即時成功 (`completed`)

タスクが同期的に完了しました。非同期処理は不要です。Request:

test=false

const response = await session.call('create_media_buy', {
  brand: { domain: 'acmecorp.com' },
  packages: [
    {
      product_id: 'prod_ctv_sports',
      pricing_option_id: 'cpm_fixed',
      budget: 50000
    }
  ]
});

Response:

{
  "status": "completed",
  "media_buy_id": "mb_12345",
  "creative_deadline": "2025-06-15T23:59:59Z",
  "packages": [
    {
      "package_id": "pkg_001",
      "product_id": "prod_ctv_sports"
    }
  ]
}

長時間処理 (`submitted`)

タスクが手動承認キューに入っています。更新を受け取るため Webhook を設定します。Request with webhook:

test=false

const response = await session.call('create_media_buy',
  {
    brand: { domain: 'acmecorp.com' },
    packages: [
      {
        product_id: 'prod_premium_ctv',
        pricing_option_id: 'cpm_fixed',
        budget: 500000  // Large budget triggers approval
      }
    ]
  },
  {
    pushNotificationConfig: {
      url: 'https://your-app.com/webhooks/adcp',
      authentication: {
        schemes: ['bearer'],
        credentials: 'your_webhook_secret'
      }
    }
  }
);

Initial response:

{
  "status": "submitted",
  "task_id": "task_abc123",
  "message": "Budget exceeds auto-approval limit. Sales review required (2-4 hours)."
}

Webhook POST when approved:

{
  "task_id": "task_abc123",
  "task_type": "create_media_buy",
  "status": "completed",
  "timestamp": "2025-01-22T14:30:00Z",
  "message": "Media buy approved and created",
  "result": {
    "media_buy_id": "mb_67890",
    "creative_deadline": "2025-06-20T23:59:59Z",
    "packages": [
      {
        "package_id": "pkg_002",
      }
    ]
  }
}

Error (`failed`)

Response:

{
  "status": "failed",
  "errors": [
    {
      "code": "INSUFFICIENT_INVENTORY",
      "message": "Requested targeting yields no available impressions",
      "field": "packages[0].targeting",
      "suggestion": "Expand geographic targeting or increase CPM bid"
    }
  ]
}

即時成功 (`completed`)

Request:

test=false

const response = await a2a.send({
  message: {
    parts: [{
      kind: 'data',
      data: {
        skill: 'create_media_buy',
        parameters: {
          brand: { domain: 'acmecorp.com' },
          packages: [
            {
              product_id: 'prod_ctv_sports',
              pricing_option_id: 'cpm_fixed',
              budget: 50000
            }
          ]
        }
      }
    }]
  }
});

Response:

{
  "status": "completed",
  "taskId": "task_123",
  "contextId": "ctx_456",
  "artifacts": [{
    "parts": [
      { "text": "Media buy created successfully" },
      {
        "data": {
          "media_buy_id": "mb_12345",
          "creative_deadline": "2025-06-15T23:59:59Z",
          "packages": [
            {
              "package_id": "pkg_001",
            }
          ]
        }
      }
    ]
  }]
}

処理中 (`working`)

タスクが処理中です。SSE ストリーミングまたはポーリングで更新を取得します。Initial response:

{
  "status": "working",
  "taskId": "task_789",
  "contextId": "ctx_456"
}

SSE status update:

{
  "taskId": "task_789",
  "status": {
    "state": "working",
    "message": {
      "parts": [
        { "text": "Validating inventory availability..." },
        {
          "data": {
            "percentage": 50,
            "current_step": "inventory_check"
          }
        }
      ]
    }
  }
}

長時間処理 (`submitted`)

Request with push notification:

test=false

const response = await a2a.send({
  message: {
    parts: [{
      kind: 'data',
      data: {
        skill: 'create_media_buy',
        parameters: {
          packages: [{ budget: 500000 }]  // Triggers approval
        }
      }
    }]
  },
  pushNotificationConfig: {
    url: 'https://your-app.com/webhooks/a2a',
    authentication: {
      schemes: ['bearer'],
      credentials: 'your_webhook_secret'
    }
  }
});

Initial response:

{
  "status": "submitted",
  "taskId": "task_abc",
  "contextId": "ctx_456"
}

Webhook POST (Task) when completed:

{
  "id": "task_abc",
  "contextId": "ctx_456",
  "status": {
    "state": "completed",
    "message": {
      "parts": [
        { "text": "Media buy approved and created" },
        {
          "data": {
            "media_buy_id": "mb_67890",
            "packages": [{ "package_id": "pkg_002" }]
          }
        }
      ]
    },
    "timestamp": "2025-01-22T14:30:00Z"
  }
}

入力要求 (`input-required`)

タスクが確認または承認待ちで一時停止しています。Response:

{
  "status": "input-required",
  "taskId": "task_def",
  "contextId": "ctx_456",
  "artifacts": [{
    "parts": [
      { "text": "The requested budget exceeds your pre-approved limit. Please confirm you want to proceed with $500K spend." },
      {
        "data": {
          "reason": "APPROVAL_REQUIRED",
          "errors": [
            {
              "code": "BUDGET_EXCEEDS_LIMIT",
              "message": "Requested budget exceeds pre-approved limit",
              "field": "total_budget"
            }
          ]
        }
      }
    ]
  }]
}

Follow-up to approve:

test=false

await a2a.send({
  contextId: 'ctx_456',  // Continue the conversation
  message: {
    parts: [{ kind: 'text', text: 'Yes, I confirm the $500K budget' }]
  }
});

Error (`failed`)

Response:

{
  "status": "failed",
  "taskId": "task_xyz",
  "artifacts": [{
    "parts": [
      { "text": "Failed to create media buy" },
      {
        "data": {
          "errors": [
            {
              "code": "INSUFFICIENT_INVENTORY",
              "message": "Requested targeting yields no available impressions",
              "suggestion": "Expand geographic targeting"
            }
          ]
        }
      }
    ]
  }]
}

非同期処理の完全なパターンは Async Operations を参照。

使用上の注意

総予算は各パッケージの個別の budget 値に基づいて配分されます
クリエイティブアセットはキャンペーン有効化のためにデッドライン前にアップロードしなければなりません
AXE セグメントにより高度なオーディエンスターゲティングが可能
working、submitted などの保留状態は正常であり、エラーではありません
オーケストレーターは保留状態を通常のワークフローの一部として処理しなければなりません
インラインクリエイティブ: creatives 配列は新規クリエイティブのみを作成します。既存クリエイティブを更新するには sync_creatives を使用。既存のライブラリクリエイティブを割り当てるには creative_assignments を使用。

ポリシー準拠

ブランドとプロダクトは作成時に検証されます。ポリシー違反はエラーを返します:

{
  "errors": [{
    "code": "POLICY_VIOLATION",
    "message": "Brand or product category not permitted on this publisher",
    "field": "brand",
    "suggestion": "Contact publisher for category approval process"
  }]
}

パブリッシャーは以下を確認すべきだ:

ブランド/プロダクトが選択したパッケージと整合しています
クリエイティブが宣言したブランド/プロダクトと一致しています
キャンペーンがすべての広告ポリシーに準拠しています

次のステップ

メディアバイ作成後:

クリエイティブのアップロード: デッドライン前に sync_creatives を使用
ステータスの監視: get_media_buy_delivery を使用
最適化: provide_performance_feedback を使用
更新: update_media_buy でキャンペーンを変更

Documentation Index

​クイックスタート

​リクエストパラメーター

​TotalBudget オブジェクト

​Package オブジェクト

​レスポンス

​成功レスポンス

​エラーレスポンス

​主なシナリオ

​ターゲティング付きキャンペーン

​コンバージョン最適化付きキャンペーン

​カタログ連動パッケージ

​クリエイティブをインライン指定したキャンペーン

​レポート用 Webhook を設定したキャンペーン

​プロポーザルの実行

​エラーハンドリング

​Key Concepts

​フォーマット指定

​ブランド参照

​価格と通貨

​ターゲティングオーバーレイ

​フォーマットワークフロー

​フォーマット指定が重要な理由

​完全なワークフロー

​フォーマット検証

​フライト日程バリデーション

​非同期オペレーション

​即時成功 (completed)

​長時間処理 (submitted)

​Error (failed)

​即時成功 (completed)

​処理中 (working)

​長時間処理 (submitted)

​入力要求 (input-required)

​Error (failed)

​使用上の注意

​ポリシー準拠

​次のステップ

​関連ドキュメント

クイックスタート

リクエストパラメーター

TotalBudget オブジェクト

Package オブジェクト

レスポンス

成功レスポンス

エラーレスポンス

主なシナリオ

ターゲティング付きキャンペーン

コンバージョン最適化付きキャンペーン

カタログ連動パッケージ

クリエイティブをインライン指定したキャンペーン

レポート用 Webhook を設定したキャンペーン

プロポーザルの実行

エラーハンドリング

Key Concepts

フォーマット指定

ブランド参照

価格と通貨

ターゲティングオーバーレイ

フォーマットワークフロー

フォーマット指定が重要な理由

完全なワークフロー

フォーマット検証

フライト日程バリデーション

非同期オペレーション

即時成功 (`completed`)

長時間処理 (`submitted`)

Error (`failed`)

即時成功 (`completed`)

処理中 (`working`)

長時間処理 (`submitted`)

入力要求 (`input-required`)

Error (`failed`)

使用上の注意

ポリシー準拠

次のステップ

関連ドキュメント