AdCP はトランザクション/制御プレーンと独自の配信時実行層にまたがります。 プランニング、ディール作成、クリエイティブ提出、レポートは AdCP の MCP/A2A タスクサーフェスを使います。事前交渉されたパッケージのインプレッション時アクティベーションは Trusted Match Protocol を使い、オークションとレンダリングは依然として RTB や VAST のような隣接プロトコルに位置します。ほとんどの AdCP タスクレイテンシー予算は秒でしばしば設計上非同期です。TMP はミリ秒の配信時決定のために構築された AdCP サーフェスです。
create_media_buy があなたのビジネスロジックに到達するまでに、それは 5 つの distinct な層 — ワイヤー形式、署名、認証、プロトコルセマンティクス、そして最後にあなたが実際に構築したいもの — を越えています。低く始めるほど、スタックのより多くを所有します。
このページはそれらの層、各層で SDK が提供するもの、どちらにせよあなたが書くために残されるものを説明します。チームに合う入口を選ぶために使ってください — エージェントを差別化する L4 ロジックに集中できるよう SDK にプロトコルサーフェスを吸収させるか、特定の理由があってより低く行くか。下のコスト分解（コンポーネントごとの L3 内訳、バージョン適応）は、どちらの選択も意図的にするためにあります。
層の前にフレーミングについて 2 つのノート:
- プロトコルサーフェスは成長した。 AdCP 3.0 は 実質的な L3 の底 を追加しました — 必須の冪等性、公開されたライフサイクルステートマシン、適合性テストサーフェス、ベースラインとしての RFC 9421 署名、拡張エラーカタログ。以前のバージョンに対して最後に SDK を評価したなら、「SDK がすること」と「自分で書くもの」の間の線は動きました。
- AdCP は外からは薄いプロトコルに見える。 内側からは、実装者が初読で予期するより多くの L3（ステートマシン、冪等性、非同期タスクコントラクト、エラーセマンティクス、適合性）を持ちます。このページの分解は、L3 の見積もりが事前に可視になるよう存在します。
The five layers
同じ 5 つの層が AdCP 会話の両側 — エージェント（サーバー） と 呼び出し元（クライアント） — に存在します。しかし作業は非対称です: エージェントはプロトコルを 強制 し（ステートマシン、冪等性、エラーセマンティクス、適合性サーフェス、webhook 発出）、呼び出し元はそれを 消費 します（状態を読む、冪等性キーを供給、エラーを扱う、webhook を受け取る）。L0（ワイヤー）と L1（署名）はほぼ対称。L2（認証）と特に L3（プロトコルセマンティクス）がサーフェスが分岐する場所です。L4 は両側に存在しますが、異なる形状です — エージェントの L4 はそのインベントリと決定、呼び出し元の L4 はそのプランニングと購買ロジック。 このページがエージェント形状の用語で層を記述するとき、末尾の Client side ノートを探してください — それが（通常より小さい）呼び出し元側のサーフェスを名指しします。ページごとのコストコメンタリー、L3 人月見積もり、適合性の議論のほとんどはサーバー側を記述します。呼び出し元の構築は L2–L3 で意味あるほど軽い。なぜなら作業のほとんどはプロトコルを消費することで、強制することではないからです。 呼び出し元のみ？ 下の各層の Client side ノートをざっと読み、次にコスト比較のため Server vs client at each layer にジャンプ。L0 — Wire & transport
それがすること: プロトコルバイトをワイヤーから取り出し型付きのインメモリ値に変える。スキーマ検証が不正なペイロードを入口で捕まえる。 その中にあるもの:- HTTP ルーティング（または MCP-over-stdio の stdio）。
- MCP メッセージフレーミング（
tools/callエンベロープ、JSON-RPC 2.0）。 - A2A SSE イベントストリーム。
- 仕様の
*.jsonファイルに対する JSON スキーマ検証（Schemas を参照）。 - 型生成: 仕様のスキーマから言語ネイティブ型を生成し、アプリケーションコードが静的にチェックされる。
create_media_buy はあなたのスタック上の型付きオブジェクト — そして他のすべてを自分でしなければなりません。
Client side: 同じプリミティブ、鏡映方向。クライアントはアウトバウンドリクエストを同じスキーマに対してシリアライズし、同じ型生成パイプラインを通じてレスポンスを消費する。L0 は本質的に対称。
L1 — Identity & signing
それがすること: リクエストがヘッダーが主張する者から来たこと、ボディが転送中に変更されなかったことを暗号学的に検証する。Security model と 実装プロファイル を参照。 その中にあるもの:- RFC 9421 HTTP メッセージ署名（
Signature-Input、Signatureヘッダー）。 - エージェントレジストリからの公開鍵解決（またはオペレーター公開の JWKS）。
- 正準化されたリクエストに対する署名検証。
- リプレイウィンドウ強制（
created/expiresパラメーター）。 - 鍵ローテーション: 飛行中のリクエストを落とさずに
keyid変更を扱う。
L2 — Auth & registry
それがすること: 検証されたアイデンティティをスコープされたプリンシパルに変える — どのバイヤー、どのブランド、どの広告主アカウント、どの sandbox 対 live ティア。Accounts と Calling an agent を参照。 その中にあるもの:- エージェントレジストリルックアップ（公開された エージェントカード からエージェントメタデータを解決）。
- ブランド解決: Brand Protocol 経由でリクエストエージェントをバイヤーブランド / 広告主アイデンティティにマッピング。
- AAO（AgenticAdvertising.org）ブリッジ: エージェントのメンバー組織、AAO Verified バッジ、レジストリ可視性を解決 — Registering an agent と AAO Verified を参照。
- マルチテナントアカウント解決: 同じワイヤーリクエストがプリンシパルに応じて異なるアカウントにマップする。
- Sandbox 対 live アカウントフラグ付け — Sandbox を参照。
- 権限スコーピング: このプリンシパルがどの AdCP ツールを呼ぶことを許されるか。
L3 — Protocol semantics
それがすること: AdCP が 何を意味するか を強制する。ワイヤー形状は整形式（L0）、呼び出し元は本物（L1）で認可済み（L2）。今: リクエストは世界の現在の状態を考慮して合法か？ その中にあるもの:- ライフサイクルステートマシン —
MediaBuy（リファレンス）、Creative、Account、SISession、CatalogItem、Proposal、Audience。それぞれが仕様で定義された合法エッジを持つ。 - 遷移検証 — リソースごとに合法エッジを強制。それを禁じる状態へのキャンセル試行に
NOT_CANCELLABLE、他の不正な移動にINVALID_STATEを発する。試みられたアクションがキャンセルのとき、キャンセル固有のコードが汎用のものより優先する。 - 冪等性 — すべての変更ツールで
idempotency_key必須。同じキーが TTL 内でキャッシュされたレスポンスをリプレイ。クロスペイロード再利用がIDEMPOTENCY_CONFLICTで失敗（盗まれた鍵の read-oracle 脅威モデルに従いペイロードエコーなし）。冪等性プロファイル を参照。 - エラーコードカタログ — リカバリーセマンティクス（
transient/correctable/terminal）を持つコード。正しいコードの選択は仕様コントラクトの一部。Error handling を参照。 - 非同期タスクコントラクト — 同期的に完了しないツールは
task_idを返す。クライアントはポーリングまたは webhook コールバックを受け取る。タスクの終端アーティファクトが元のツールのレスポンス形状を運ぶ。Task lifecycle を参照。 - Webhook 発出 — 状態変更がサブスクライブしたバイヤーに通知、リトライ、冪等性、署名付き。Webhooks を参照。
- 適合性テストサーフェス —
comply_test_controller（サンドボックス専用）がseed_*/force_*/simulate_*を公開し、ストーリーボードが状態を決定的に駆動できる。comply_test_controller と Conformance を参照。 - レスポンスエンベロープ —
context、task_id、statusフィールド、エラーエンベロープ形状、adcp_versionエコー、ケイパビリティアドバタイズ。
idempotency_key を 供給 する。発する正しいものを選ぶのではなくエラーコードをリカバリーセマンティクスで 分類 する（transient → リトライ、correctable → 修正して再送信、terminal → リトライしない）。発するのではなく非同期タスク結果と webhook コールバックを ポーリングまたは受け取る。公開する comply_test_controller サーフェスはなく、コンシューマー側で認証する適合性のラインもない。このページの後の L3 人月見積もりはサーバー側。クライアント L3 は数か月ではなく数週間のハンドラーグルー。
L4 — Business logic
これがあなたのエージェントをあなたのものにするものです。 その中にあるもの:- 実際のアドサーバーに対するインベントリ予測。
- 価格ロジック、ディール条件、契約セマンティクス。
- クリエイティブレビューポリシー（ブランドセーフティ、フォーマットコンプライアンス）。
- GAM / FreeWheel / Kevel / Yahoo / 社内決定エンジンへの上流呼び出し。
- 最適化、ペーシング、詐欺検出 — インベントリを競合のものと差別化する何でも。
Server vs client at each layer
同じ 5 つの層、非常に異なるコスト。呼び出し元のみのビルド対エージェントビルドの作業をサイズするときこれを使います。
一から作る呼び出し元は L0–L3 にわたる数週間の仕事です — ハンドラーグルー、署名、レジストリルックアップ、レスポンスパース — エージェント側が要求する 3〜4 人月の L3 ビルド ではありません。このページの残りはコストが存在するためエージェント側に集中しますが、層モデルと SDK カバレッジマトリクスは呼び出し元のみのビルドにも等しく適用されます。
What an SDK at each layer should provide
実装者向けチェックリスト。層 Ln のカバレッジを主張する SDK は、最低限、下のプリミティブを公開すべきです。採用者は SDK を選ぶときこれを自己評価ツールとして使い、SDK 作者はビルドターゲットとして使います。 チェックリストは サーバー側カバレッジ を記述します — エージェントサーフェスが SDK の価値の大部分が存在する場所です。各層での クライアント側カバレッジ はサブセットです: 型付きリクエストビルダー + レスポンスパーサー（L0）、アウトバウンド署名 + webhook 検証（L1）、エージェントカード公開 + レジストリルックアップ（L2）、ステートマシン ハンドラー + 冪等性キー生成 + エラーリカバリー分類 + 非同期結果ポーリング（L3）。フルスタック SDK は両方を出荷。L0 coverage
- 公開された JSON スキーマからの生成された言語ネイティブ型（リクエスト/レスポンスペアごとに 1 型、加えて共有リソース型）。
- バンドルされたスキーマに対して配線されたスキーマ検証器 — そのため採用者はスキーマロードのダンスを手書きせずにインバウンドとアウトバウンドのペイロードを検証できる。
- {MCP, A2A} の少なくとも一方のトランスポートアダプター。理想的には両方。これらは通常、上流プロトコル SDK を再実装するのではなくラップする。
- 採用者にパスをハードコードさせずにアクティブな AdCP バージョンの正しいスキーマファイルを見つけるスキーマバンドルアクセサー。
L1 coverage
- アウトバウンドリクエストのための RFC 9421 メッセージ署名の署名。
created/expiresのリプレイウィンドウ強制とkeyidベースの鍵ルックアップを含む、インバウンドリクエストの RFC 9421 検証。- プラグイン可能な署名プロバイダー抽象: 開発用のプロセス内鍵、本番用の KMS / HSM プロバイダー。
- 採用者が完全なエージェントを起動せずに署名配線が正しいことをアサートできるテストフィクスチャまたは検証者テストハーネス。
L2 coverage
- マルチテナントルーティングのフック付きで、認証されたプリンシパルをスコープされたアカウントに解決するアカウントストア抽象。
- 少なくとも API キーと bearer トークンの形状のための認証プリミティブ、加えてそれらを合成する方法。
- ブランド解決 / エージェントレジストリルックアップ（または SDK がネイティブに出荷しない場合は文書化された拡張ポイント）。
- 適合性テストサーフェスが本番アカウントでのディスパッチを拒否するよう SDK 境界で強制される sandbox 対 live アカウントフラグ。
L3 coverage
- すべての仕様定義リソースのライフサイクルステートマシングラフ、仕様正しいエラーコード（
NOT_CANCELLABLE/INVALID_STATEなど）を発する遷移アサーションプリミティブ付き。 - クロスペイロード衝突検出と
IDEMPOTENCY_CONFLICTエンベロープの no-payload-echo 不変条件を持つ冪等性キャッシュ。 - 非同期タスクストア + ディスパッチャー: ツールは非同期にオプトイン。SDK は
task_idを返し、ポーリングを受け入れ、終端アーティファクトを発する。 - Webhook エミッター: 署名済み、リトライ済み、冪等。
- 解決されたアカウントが sandbox または mock モードのとき状態を決定的に駆動するよう配線された（そうでなければ拒否される）適合性テストサーフェス（
comply_test_controller）。 - 仕様のエコーコントラクトを扱うリソースごとの永続性プリミティブ。
- 上のすべてを賢明なデフォルトで結びつけるサーバー構築エントリポイント。
L4 coverage
任意の SDK のスコープ外。採用者がこれを書きます。SDK coverage varies
異なる言語 SDK は L0–L3 の異なるサブセットをカバーします。すべての実装者が使わなければならない単一の SDK はありません。重要なのは、実装が L3 で 適合性のライン に到達することで、そこに到達するのにどれだけ手書きが必要だったかにかかわらずです。 特定の言語内では、フルスタック SDK がデフォルトの出発点です。このドキュメントの層モデルは、より低く行った（特殊目的プロキシ、カスタムスタック統合）または SDK を新しい言語に移植した場合に何を再実装するかを説明するために存在し — 典型的なエージェントビルドでより低く始めることに意味ある勝利があると示唆するためではありません。Current SDK coverage
Python と TypeScript がファーストクラスの言語です。 両方が完全な L0–L4 カバレッジにコミット — TypeScript は今日 L0–L3 全体で GA、Python は 4.x サイクルを同じラインに向けて仕上げ中。Go は同じ方向に動き、L0 と部分的 L1 が活発に開発中。他の言語 は今日公式ロードマップにありませんが、コミュニティ保守のポートに開かれています — 手伝いたいなら Builders Working Group と Slack コミュニティ を参照。 各公式 SDK が今日出荷するもののスナップショット。この表を SDK メジャーと AdCP 仕様改訂でリフレッシュしてください。 最終更新: 2026-05-03。
凡例: ✅ 出荷済み · ⚠️ 部分的 / 進行中 · ❌ まだ未カバー。Production GA は今日ピン留めすべきライン。Beta / dev は次のメジャーで進行中のもの。
@adcp/sdk 6.x は完全な L0–L3 を運ぶ — 採用者は L4 のみを書く。Python 3.x は完全な L0 を持つ本番ライン。4.x 書き直し（ベータ）が L1–L3 を閉じる。Go は開発で型 + トランスポートを出荷。L1–L3 はスコープ内。インストールコマンド、パッケージエクスポート、言語ごとのギャップ詳細については Choose your SDK を参照。
各層で「出荷済み」が何を意味するかは上の L0–L3 チェックリスト — これらの行は、公開された SDK ビルドですべてのチェックリスト項目が満たされるまで ✅ を主張すべきではありません。このスナップショットを超えたカバレッジ詳細については、各 SDK のリポジトリを参照。
形状比較の目的で、SDK が言語にかかわらず着地できる 3 つのカバレッジアーキタイプ:
Hosted implementations
SDK とは異なる形状: インポートするライブラリではなく実行する デプロイ可能なエージェント。採用者はコードではなく設定する。ハンドラーコードを自分で書かずに既存システムの前に AdCP サーフェスが欲しいとき有用。
ホストされた実装は、SDK がするのと同じ L3 適合性のラインを満たします — 仕様は実装非依存です。違いは運用形状: ホストされた実装はデプロイして設定するサービス、SDK は自身のサービスにコンパイルするコードです。
選択はレバレッジと制御の間のトレードオフです。フルスタック SDK は最も多くのコードを無料で出荷しますが、その選択にあなたを結びつけます。トランスポートのみの SDK は最大の制御を与えますが、認証できる前に数か月の L1–L3 作業にサインアップさせます。ほとんどの本番採用者は、個々の層をスワップするオプション（カスタム署名プロバイダー、カスタムアカウントストア、カスタム冪等性バックエンド）を持つフルスタックを望みます — よく設計されたフルスタック SDK はそれをフォークではなく設定として公開します。
Where can you start?
任意の層で実装できます。低く始めるほど、より多くを構築します。
フルスタック AdCP SDK はあなたを L4 に持ち上げます。あなたは上流呼び出しを実装します。SDK はそれらの周りにプロトコルエンベロープを通します。チームの付加価値が L4 差別化なら 1 つを選び、特定の理由があるならより低く構築する — そして L1–L3 のスコープを正直に予算化してください。
構築しているものに基づいて入口を選ぶ短い決定ページについては Where to start を参照。
Why SDKs matter more in AdCP than in (e.g.) HTTP
一般的な比較: 「HTTP はプロトコルだ。人々は常に HTTP サーバーを一から構築する。なぜ AdCP は違うのか？」 答えは層 L3 です。HTTP のプロトコルセマンティクスは最小 — メソッド、ステータスコード、ヘッダー。一から作る HTTP サーバーは既製のパーサーで週末に出荷できます。 AdCP の L3 は大きい:- ステートマシン — 公開されたライフサイクルグラフを持つ 7 リソースタイプ。
- 非同期タスク — すべての変更ツールが同期または非同期になりうる。どの終端アーティファクトがタスクを閉じるかのコントラクトは非自明。
- 冪等性 — キャッシュ、リプレイ、衝突、TTL — すべて正しく配線。
- エラーカタログ — リカバリー分類を持つコード。誤ったものを選ぶと 適合性 に失敗。
- 適合性テストサーフェス — ストーリーボードが
comply_test_controllerツール経由で状態を駆動。非自明なコントローラーサーフェスを出荷する。 - Webhook 発出 — 署名済み、リトライ済み、冪等。
それは 約 14〜18 週間 で、チームの HTTP メッセージ署名とライフサイクルモデリングへの習熟に依存します。見積もりは バージョン適応作業を除外 します — ツール、エッジ、エラーコードを追加するすべての仕様改訂が、あなたが永遠に運ぶ変換マトリクスに行を追加します。SDK 採用者はそれらを無料で得ます。一から作る実装者はすべてのリリースでそれらを払います。
これは 1 エンジニアから mock 適合性までの見積もりです。パブリッシャー / 大規模プラットフォームスケールでは、SRE、セキュリティレビュー、既存の鍵インフラとの KMS / HSM 統合、負荷テスト、オンコール負担のため約 2 倍〜3 倍を掛けてください — そのどれも L3 仕様作業ではなく、すべてがサーフェスが本番グレードになる前の実際のコストです。
「一から」は L0（ワイヤー形状）が視野の唯一の層のとき安く読めます。L3 が実際のスコープが隠れる場所です — 上の表は、チームがどちらにせよコミットする前に指すものです。
Version adaptation
3 つの「バージョン」軸が同時に動き、SDK の仕事はそれらがあなたのビジネスロジック内で衝突するのを防ぐことです:
一から作るエージェントは 3 つすべてを手で扱わなければなりません。SDK は 3 つの具体的なメカニズムを出荷し、採用者がそうしないようにします:
- 呼び出しごとの仕様バージョンピン留め。 エージェントに
adcpVersion（または言語同等物）を設定。SDK はリクエストとレスポンスをアダプターモジュールを通し、ハンドラーコードがピアが何を話すかにかかわらず正準（現在）形状に留まる。 - 共存インポート経由の SDK メジャー移行。 SDK メジャーを上げても同日の書き直しを強制しない — 前メジャーのサーフェスが新しいエントリポイントと並んで利用可能なまま。一度に 1 つの専門分野を移行。
- ワイヤーレベルネゴシエーション。 すべてのリクエストが
adcp_major_versionを運ぶ。サーバーはサポートするものを宣言し、呼び出し元が範囲外ならVERSION_UNSUPPORTED（リカバリー分類されたエラー）を返す。
Why this matters
AdCP のバージョニングは エピソード的ではなく連続的 です。3.1 が出荷されたら、3.0 と 3.1 の呼び出し元と同時に、無期限に話します。変換アダプターなしではこれはコードベースのフォークです。それらがあればコンストラクターフラグです。 仕様自体が既にこれらの交差の 1 つをしました。2.5 → 3.0 は実質的な L3 の底を追加しました — 正準リストについては What changed at L3 in 3.0 を参照。一から作る 2.5 エージェントは扱いやすかった。一から作る 3.0 エージェントは上で分解された 約 3〜4 人月の L3 ビルド です。 2.5 で機能した一から作るパスは 3.0 にスケールせず、3.0 が仕様の止まる場所ではありません。SDK が存在するのは L3 が実装者が手書きできるより速く成長したからで、バージョン適応サーフェスはリリースごとに成長し続けます。Where the work actually lives
L3 コストが集中する 5 つの場所、おおよその桁順。一から作るビルドをスコープしているか手書きのものを再評価しているかの自己チェックとして有用:- L3 が作業のほとんど。 ステートマシン、冪等性、エラーカタログ、非同期タスク — 任意の L4 差別化の前に約 3〜4 人月。コンポーネントごとの週については 分解 を参照。
- 適合性は L3 駆動。 ストーリーボードは状態遷移とエラー形状をプローブする（Conformance を参照）。遷移検証器なしでは、仕様がテスト失敗から再導出される。
- バージョニングが複合する。 ツール、ライフサイクルエッジ、エラーコードを追加する各仕様改訂は、アダプター層が運ぶ新しい変換行。アダプター層の所有は、すべてのリリースでそのマトリクスを所有することを意味する。
- RFC 9421 + 鍵ローテーションは独自のプロジェクト。 署名プロバイダー、KMS 統合、リプレイウィンドウ — 実際のエンジニアリング、そのどれも L4 差別化でない。
- mock-server は共有インフラ。 SDK は mock-mode ディスパッチをそれに無料で配線する。手書き実装は mock-mode をスキップする（そして仕様適合性認証を失う）か再構築するか。
What this means for compliance
2 種類のコンプライアンス、両方が層モデルによって形作られる:- 仕様適合性（L3 プロトコルテスト） — 実装は AdCP ワイヤーコントラクトを満たすか？ ストーリーボードがステートマシンを歩き、エラーコードを実行し、非同期タスクコントラクトをテストする。採用者の上流は無関係。mock-mode アカウントに対して実行: エージェントがすべてのツール呼び出しをリファレンスモックサーバーに転送。これが SDK の（または手書き実装の）L3 層を認証する。
- ライブ適合性（フルスタックテスト、計画中） — 実際にデプロイされたエージェント（テストインフラに対する採用者の L4 コード）がストーリーボードの下でエンドツーエンドで正しく振る舞うか？ sandbox-mode アカウントに対して実行: mock ではなく採用者のコードパスが実行される。これが L0–L3 + 採用者の上流が結合して正しいワイヤー動作を生成することを認証する。
TL;DR
- AdCP は 5 つの層を持つ。仕様は L0–L3 に存在し、あなたのエージェントは L4 に存在する。
- 「一から」は L0–L3 を自分で実装することを意味する。それは多い — コンポーネントごとの内訳 を参照。
- フルスタック AdCP SDK はあなたを L4 に持ち上げる。あなたはビジネスロジックを書き、SDK がプロトコルを扱う。異なる言語 SDK は L0–L3 の異なるサブセットをカバーする。継承したいプロトコルの量に合うものを選ぶ — カバレッジマトリクス を参照。
- バージョン適応は SDK 機能で、採用者プロジェクトではない。 呼び出しごとの仕様バージョンアダプター、SDK メジャーをまたいだ共存インポート、ワイヤー上の
adcp_major_versionネゴシエーションが、ハンドラーをフォークせずに任意のサポートバージョンのピアと話させる。手書きエージェントは変換マトリクス全体を永遠に継承する。 - コンプライアンスは 2 つの風味で来る: 仕様適合性（mock-mode、プロトコルのみ、L3 リファレンステスト）と ライブ適合性（sandbox-mode、フルスタック、L0–L4 エンドツーエンド、計画中）。
- 3.0 の前に最後に SDK を評価したなら、比較は動いた — 3.0 が追加した L3 の底 を参照。覚えているものではなく今日のカバレッジに対して再評価してください。