仕様レベルのリファレンス対ビルド形式ガイド。 このページはビルドを順に案内します。ワイヤーレベルの不変条件 — すべての変更呼び出しに適用されるすべてのルール — は AdCP エージェントの呼び出し にあります。本番に行く前に一度読んでください。ワイヤー形状エラーをデバッグするときはいつでも参照してください。
SDK をインストール
サーバープリミティブを出荷する同じ SDK が呼び出しクライアントも出荷します。1 つをインストールすれば両方を持ちます。- JavaScript/TypeScript
- Python
- Go
ADCPMultiAgentClient を使います — 同じ呼び出しサーフェス、エージェント id でインデックス化。認証する
ほとんどのエージェントは、get_adcp_capabilities を超えた何かに応答する前に認証情報を要求します。SDK は構築時に認証を受け入れます:
- Bearer / API key
- Signed requests (RFC 9421)
AUTH_REQUIRED を返す場合、認証情報がエージェントに到達していません — リクエストペイロードではなくコンストラクターオプションを確認してください。完全な認証情報モデルについては L1 セキュリティ実装プロファイル を参照。
最初の呼び出し: エージェントを発見する
手動でツールを呼ぶ前に、エージェントに何をサポートするか尋ねます。get_adcp_capabilities はエージェントのプロトコルカバレッジ、AdCP バージョン範囲、機能フラグを返します。呼び出しをゲートするのに使ってください — media_buy が supported_protocols にないなら、このエージェントに対して create_media_buy を呼ばないでください。完全なレスポンス形状については get_adcp_capabilities リファレンスを参照。
ディスカバリーチェーンの残り(エージェントカード、tools/list、get_schema)については、エージェントの呼び出しのディスカバリーチェーンセクション を参照。
呼び出しをする
クライアントの型付きメソッドは AdCP ツールに対応します。SDK は送信前にリクエストをバンドルされたスキーマに対して検証し、レスポンスを型付き値にパースします。- 論理操作ごとに新しい
idempotency_keyを生成。 リトライで同じキー → サーバーは同じレスポンスをリプレイ。失敗後の新しいキーは重複したバイを作る。冪等性ルール を参照。 accountは判別されたoneOf。 1 つのバリアント(sync_accounts/list_accountsからの{account_id}、または自然キーとしての{brand, operator}—brand.domainはバイヤーのブランドドメイン、operatorはセラーエージェントのデプロイホスト名または brand.json 識別子)を選び、その必須フィールドのみを送る。それらをマージすると両方で失敗。accountはoneOfを参照。
3 つのレスポンス形状を扱う
すべての変更ツールは 3 つの形状の 1 つを返します。それらを明示的に扱ってください。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 キーワード(required、oneOf、enum など)、そして — oneOf 失敗については — 各バリアントの必須フィールドをリストする variants[] 配列を持ちます。完全なエンベロープとリカバリーセマンティクスについては エラーリカバリーセクション を参照。
Webhook を受信する
非同期タスクについては、ポーリングまたは webhook 登録のいずれかができます。webhook はinclude_result: true を伴う AdCP タスクポーリングと同じ result ペイロードを配信します。SDK は、セラーの brand.json 経由で鍵を解決し、リプレイウィンドウを強制し、webhook エラータクソノミー の構造化エラーをサーフェスする RFC 9421 webhook 検証者(@adcp/sdk/signing/server の createWebhookVerifier)を出荷します。
マルチエージェントクライアントを webhookUrlTemplate とステータス変更ハンドラーで配線する(@adcp/sdk README 準拠)と、インバウンド webhook が検証され自動的にハンドラーにディスパッチされます — あなたの HTTP ルートはリクエストをクライアントに渡す 1 行です。
配線方法にかかわらずエンドポイントが満たさなければならないワイヤーレベルの要件(カバードコンポーネント、content-digest 強制、重複排除の規律)については、L3 — Webhooks を参照。
レポートを取り込む
レポートは読み取り専用で、他のすべてと同じ呼び出し/レスポンス形状に従います。所有するバイの配信を引き、ウィンドウ付きケイデンスで反復します:delivery オブジェクトの上のあなたのアプリケーションコードです。
書かずに済んだもの
呼び出し元側の L0–L3 が数週間のハンドラーグルーなのは、SDK が既に次を出荷したからです:- L0 — 型付きリクエストビルダー、レスポンスパーサー、バンドルされたスキーマに対するスキーマ検証。
- L1 — アウトバウンド RFC 9421 署名(呼び出しごと)、インバウンド webhook 検証、鍵ローテーション。
- L2 — エージェントレジストリルックアップ、エージェントカード公開、認証情報合成。
- L3 — 非同期タスクポーリング、webhook レシーバー、冪等性キー生成ヘルパー、エラーリカバリー分類。
次は
- エージェントの呼び出し — 正準ワイヤーコントラクトリファレンス。本番に行く前に一度読む。
- Schemas — スキーマバンドル、型生成、バージョンピン留め。
- Webhooks — プッシュ通知、署名、リトライ、信頼性パターン。
- Error handling — エラーカテゴリー、コード、リカバリー分類。
- エージェントを検証する — 呼び出し元側のワイヤー適合性のストーリーボードも存在する。呼び出しが機能したら実行する。