​

AdCP エージェントの呼び出し

​

Discovery chain

1. Agent card（A2A）または tools/list（MCP）: ツール名を返す。AdCP MCP サーバーは tools/list でツールごとのパラメータースキーマをもはや公開しません — すべてのツールは {type: 'object', properties: {}} を示す。そこから形状を推論しようとしないでください。
2. get_adcp_capabilities: サポートするプロトコル、AdCP メジャーバージョン、機能フラグを返す。このエージェントがどのツールをサポートするかを教えますが、それらをどう呼ぶかは教えません。get_adcp_capabilities を参照。
3. get_schema(tool_name) （エージェントがそれを公開するとき — 標準化保留中、#3057 を参照）: 特定のツールのリクエスト/レスポンスの JSON Schema を返す。
4. バンドルされたスキーマ（オフライン、権威的）: すべての公開された AdCP バージョンは、すべてのツールの JSON Schema を Sigstore 経由で署名して出荷します。パスは SDK によって異なります — 仕様リポジトリソースは dist/schemas/<version>/bundled/ を使い、@adcp/sdk は npm run sync-schemas の後にそれらを schemas/cache/<version>/bundled/ に置き、Python と Go の SDK は独自の慣例を使います。パスをハードコードせず、SDK のローダーに見つけさせてください。いったん見つかれば、各スキーマは <protocol>/<tool>-{request,response}.json にあります。

​

Idempotency: replay vs. new operation

• リトライで同じキー → サーバーは同じレスポンスをバイト単位でリプレイする。トランスポートレベルのリトライ（タイムアウト、5xx、切断された接続）にこれを使う。
• 新しいキー → ボディにかかわらず新しい操作。前回の試行が失敗したという理由で新しい UUID を生成することは、素朴な呼び出し元が重複したメディアバイを作る最も一般的な方法です。
• 同じキー、異なる正準ボディ → IDEMPOTENCY_CONFLICT。セラーは拒否しなければならない（MUST）（security.mdx#冪等性 のルール 5） — 2 番目のボディを黙って適用せず、最初のレスポンスを黙ってリプレイしないでください。
• 最初のリクエストがまだ実行中に同じキー → IDEMPOTENCY_IN_FLIGHT（security.mdx#冪等性 のルール 9）。セラーはブロックする代わりに error.details.retry_after 付きでこのコードを返してもよい（MAY）。同じキーで待って再試行する — このコードで新しいキーを鋳造すると、安全なリトライが二重実行レースになります。

​

account is oneOf — pick exactly one variant

// variant 0: セラー割り当て id による（list_accounts または帯域外オンボーディングから。
// バイヤー宣言セラーは sync_accounts の account_id を内部ハンドルとしてエコーすることもある）
"account": { "account_id": "seller_assigned_id" }

// variant 1: 自然キーによる（brand + operator、任意の sandbox）
//   brand.domain — バイヤーのブランドドメイン（例: 広告主のウェブサイト）
//   operator     — ブランドに代わって動作するバイヤー側のエンティティ
"account": { "brand": { "domain": "acme.com" }, "operator": "pinnacle-media.com" }

​

Async responses: status: 'submitted' means queued

// 成功（同期）: 作業は完了
{ "media_buy_id": "mb_123", "packages": [...], "confirmed_at": "..." }

// Submitted（非同期）: 作業はキューイングされた
{ "status": "submitted", "task_id": "tk_abc", "message": "Awaiting IO signature" }

// エラー: 修正せずにリトライしない
{ "errors": [{ "code": "PRODUCT_NOT_FOUND", "message": "..." }] }

// tasks/get リクエスト（任意の get_task_status エイリアスと同じペイロード）
{
  "task_id": "task_456",
  "include_result": true,
  "account": {
    "brand": { "domain": "acmeoutdoor.example" },
    "operator": "pinnacle-agency.example",
    "sandbox": true
  }
}

// tasks/get レスポンス — completed
{
  "task_id": "task_456",
  "task_type": "create_media_buy",
  "protocol": "media-buy",
  "status": "completed",
  "completed_at": "2025-01-22T10:30:00Z",
  "result": {
    "media_buy_id": "mb_12345",
    "packages": [{ "package_id": "pkg_001" }]
  }
}

​

Error recovery — read issues[]

{
  "adcp_error": {
    "code": "VALIDATION_ERROR",
    "recovery": "correctable",
    "field": "/first/offending/pointer",
    "issues": [
      {
        "pointer": "/account",
        "keyword": "oneOf",
        "message": "must match exactly one schema in oneOf",
        "variants": [
          { "index": 0, "required": ["account_id"],        "properties": ["account_id"] },
          { "index": 1, "required": ["brand", "operator"], "properties": ["brand", "operator", "sandbox"] }
        ]
      },
      { "pointer": "/brand/domain", "keyword": "required", "message": "must have required property 'domain'" }
    ]
  }
}

• issues[].pointer — 問題のあるフィールドへの RFC 6901 JSON Pointer
• issues[].keyword — Ajv キーワード（required、type、oneOf、anyOf、additionalProperties、format、enum）
• issues[].variants — keyword が oneOf または anyOf のとき、各エントリが 1 つのバリアントの required + 宣言された properties をリストする

• correctable — バイヤー側の修正。issues[] を読み、ポインターをパッチし、再送する
• transient — 同じ idempotency_key でリトライする
• terminal — 人間の対応が必要（アカウント停止、支払い必要）。リトライしない

​

Common shape pitfalls

​

Transport notes

• MCP: { name: 'tool_name', arguments: {...} } を伴う tools/call。型付きレスポンスは structuredContent を読む。
• A2A: { skill: 'tool_name', input: {...} } の形状の DataPart を伴う message/send。型付きレスポンスは task.artifacts[0].parts[0].data にある。

​

Related

• タスクごとのリクエスト/レスポンス形状: プロトコル固有のリファレンス（/docs/media-buy/、/docs/creative/、/docs/signals/ など）を参照。
• プロトコルアーキテクチャ — プロトコルドメインがどう組み合わさるか。
• 必須タスク — 専門分野を主張するためにエージェントが実装しなければならないタスク。
• get_adcp_capabilities — 任意の新しいエージェントに対する最初の呼び出し。
• Schemas — SDK がプロトコル tarball（現在 skills/ をバンドル）をどう消費するか。
• Build a caller — 呼び出し元側のビルド形式ガイド: インストール、呼び出し、レスポンス処理、レポート取り込み。