Skip to main content
バイ側 — DSP、プランニングツール、エージェンティッククライアント、またはプラン、購入、レポートのために AdCP エージェントを呼ぶ任意のアプリケーション — を構築しているなら、ここから始めてください。呼び出し元側の L0–L3 は、エージェント側が要求する 3〜4 人月のビルド ではなく、数週間のハンドラーグルーです。あなたの言語のフルスタック SDK が L0–L3 を運びます。あなたは呼び出しロジック、レスポンス処理、そしてアプリケーションがデータで何をするかを書きます。
仕様レベルのリファレンス対ビルド形式ガイド。 このページはビルドを順に案内します。ワイヤーレベルの不変条件 — すべての変更呼び出しに適用されるすべてのルール — は AdCP エージェントの呼び出し にあります。本番に行く前に一度読んでください。ワイヤー形状エラーをデバッグするときはいつでも参照してください。
ライブエージェントに対して試す。 AAO は https://test-agent.adcontextprotocol.org でパブリックテストエージェントを、ドメインごとのエンドポイント — /sales/mcp/creative/mcp/signals/mcp/governance/mcp — で実行します。クライアントを一致するエンドポイントに向けると getAdcpCapabilities() が認証なしで機能します。実際のセラーに向ける前にインストールを検証するために使ってください。

SDK をインストール

サーバープリミティブを出荷する同じ SDK が呼び出しクライアントも出荷します。1 つをインストールすれば両方を持ちます。
マルチエージェントファンアウト(1 つのクライアントが並列で多くのセラーを駆動)には、代わりに ADCPMultiAgentClient を使います — 同じ呼び出しサーフェス、エージェント id でインデックス化。

認証する

ほとんどのエージェントは、get_adcp_capabilities を超えた何かに応答する前に認証情報を要求します。SDK は構築時に認証を受け入れます:
最初の呼び出しが 401 / AUTH_REQUIRED を返す場合、認証情報がエージェントに到達していません — リクエストペイロードではなくコンストラクターオプションを確認してください。完全な認証情報モデルについては L1 セキュリティ実装プロファイル を参照。

最初の呼び出し: エージェントを発見する

手動でツールを呼ぶ前に、エージェントに何をサポートするか尋ねます。
get_adcp_capabilities はエージェントのプロトコルカバレッジ、AdCP バージョン範囲、機能フラグを返します。呼び出しをゲートするのに使ってください — media_buysupported_protocols にないなら、このエージェントに対して create_media_buy を呼ばないでください。完全なレスポンス形状については get_adcp_capabilities リファレンスを参照。 ディスカバリーチェーンの残り(エージェントカード、tools/listget_schema)については、エージェントの呼び出しのディスカバリーチェーンセクション を参照。

呼び出しをする

クライアントの型付きメソッドは AdCP ツールに対応します。SDK は送信前にリクエストをバンドルされたスキーマに対して検証し、レスポンスを型付き値にパースします。
最初の呼び出しで知っておく価値のある 2 つのこと:
  • 論理操作ごとに新しい idempotency_key を生成。 リトライで同じキー → サーバーは同じレスポンスをリプレイ。失敗後の新しいキーは重複したバイを作る。冪等性ルール を参照。
  • account は判別された oneOf 1 つのバリアント(sync_accounts / list_accounts からの {account_id}、または自然キーとしての {brand, operator}brand.domain はバイヤーのブランドドメイン、operator はセラーエージェントのデプロイホスト名または brand.json 識別子)を選び、その必須フィールドのみを送る。それらをマージすると両方で失敗。accountoneOf を参照。

3 つのレスポンス形状を扱う

すべての変更ツールは 3 つの形状の 1 つを返します。それらを明示的に扱ってください。
SDK は非同期完了のため webhook に導きます。構築時に webhookUrlTemplate とステータス変更ハンドラーを設定します。SDK はインバウンド webhook をセラーの JWKS に対して検証し、同期レスポンスが運ぶのと同じ result 形状であなたのハンドラーを発火します — 下の Webhook を受信する を参照。 webhook を使う代わりにポーリングしなければならない場合(例: ワンショットスクリプト内)、AdCP ポーリングサーフェスを呼びます: セラーがアドバタイズするとき get_task_status、そうでなければ 3.x のレガシー AdCP tasks/getエージェントの呼び出しの非同期レスポンスセクション にワイヤーコントラクトがあります。

エラーから回復する

レスポンスに adcp_error を見たら、issues[] を読み recovery に基づいて行動します:
issues[] は実行可能な部分です: 各エントリは JSON Pointer(pointer)、Ajv キーワード(requiredoneOfenum など)、そして — oneOf 失敗については — 各バリアントの必須フィールドをリストする variants[] 配列を持ちます。完全なエンベロープとリカバリーセマンティクスについては エラーリカバリーセクション を参照。

Webhook を受信する

非同期タスクについては、ポーリングまたは webhook 登録のいずれかができます。webhook は include_result: true を伴う AdCP タスクポーリングと同じ result ペイロードを配信します。SDK は、セラーの brand.json 経由で鍵を解決し、リプレイウィンドウを強制し、webhook エラータクソノミー の構造化エラーをサーフェスする RFC 9421 webhook 検証者(@adcp/sdk/signing/servercreateWebhookVerifier)を出荷します。 マルチエージェントクライアントを webhookUrlTemplate とステータス変更ハンドラーで配線する(@adcp/sdk README 準拠)と、インバウンド webhook が検証され自動的にハンドラーにディスパッチされます — あなたの HTTP ルートはリクエストをクライアントに渡す 1 行です。 配線方法にかかわらずエンドポイントが満たさなければならないワイヤーレベルの要件(カバードコンポーネント、content-digest 強制、重複排除の規律)については、L3 — Webhooks を参照。

レポートを取り込む

レポートは読み取り専用で、他のすべてと同じ呼び出し/レスポンス形状に従います。所有するバイの配信を引き、ウィンドウ付きケイデンスで反復します:
パフォーマンス webhook をサポートするセラーについては、上に示した同じ webhook レシーバー経由でデルタを受け取ります。そうでなければレポートニーズに応じた任意のケイデンスでポーリングします。呼び出し元 L4 — 最適化、ペーシングアラート、アトリビューション結合、ダッシュボード — は型付き delivery オブジェクトの上のあなたのアプリケーションコードです。

書かずに済んだもの

呼び出し元側の L0–L3 が数週間のハンドラーグルーなのは、SDK が既に次を出荷したからです:
  • L0 — 型付きリクエストビルダー、レスポンスパーサー、バンドルされたスキーマに対するスキーマ検証。
  • L1 — アウトバウンド RFC 9421 署名(呼び出しごと)、インバウンド webhook 検証、鍵ローテーション。
  • L2 — エージェントレジストリルックアップ、エージェントカード公開、認証情報合成。
  • L3 — 非同期タスクポーリング、webhook レシーバー、冪等性キー生成ヘルパー、エラーリカバリー分類。
SDK スタックリファレンス が各層を分解します。サーバー対クライアント比較表 がコスト非対称性の並列ビューです。

次は

  • エージェントの呼び出し — 正準ワイヤーコントラクトリファレンス。本番に行く前に一度読む。
  • Schemas — スキーマバンドル、型生成、バージョンピン留め。
  • Webhooks — プッシュ通知、署名、リトライ、信頼性パターン。
  • Error handling — エラーカテゴリー、コード、リカバリー分類。
  • エージェントを検証する — 呼び出し元側のワイヤー適合性のストーリーボードも存在する。呼び出しが機能したら実行する。
プロトコルごとのタスクリファレンス: