> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# AdCP スタック

> AdCP 実装者のための層リファレンス。5 つの層（L0 ワイヤー、L1 署名、L2 認証、L3 プロトコルセマンティクス、L4 ビジネスロジック）、各層が何を含むか、各層の SDK が何を提供すべきか、SDK がどうバージョンドリフトを吸収するか、「一から」が実際に何にサインアップするか。

<Note>
  **AdCP はトランザクション/制御プレーンと独自の配信時実行層にまたがります。** プランニング、ディール作成、クリエイティブ提出、レポートは AdCP の MCP/A2A タスクサーフェスを使います。事前交渉されたパッケージのインプレッション時アクティベーションは [Trusted Match Protocol](/docs/trusted-match) を使い、オークションとレンダリングは依然として RTB や VAST のような隣接プロトコルに位置します。ほとんどの AdCP タスクレイテンシー予算は秒でしばしば設計上非同期です。TMP はミリ秒の配信時決定のために構築された AdCP サーフェスです。
</Note>

AdCP エージェントを構築するために座るときの最初の問いは、**エンジニアリング時間をどこに費やしたいか** です。バイヤーの `create_media_buy` があなたのビジネスロジックに到達するまでに、それは 5 つの distinct な層 — ワイヤー形式、署名、認証、プロトコルセマンティクス、そして最後にあなたが実際に構築したいもの — を越えています。低く始めるほど、スタックのより多くを所有します。

このページはそれらの層、各層で SDK が提供するもの、どちらにせよあなたが書くために残されるものを説明します。チームに合う入口を選ぶために使ってください — エージェントを差別化する L4 ロジックに集中できるよう SDK にプロトコルサーフェスを吸収させるか、特定の理由があってより低く行くか。下のコスト分解（[コンポーネントごとの L3 内訳](#why-sdks-matter-more-in-adcp-than-in-eg-http)、[バージョン適応](#version-adaptation)）は、どちらの選択も意図的にするためにあります。

層の前にフレーミングについて 2 つのノート:

* **プロトコルサーフェスは成長した。** AdCP 3.0 は [実質的な L3 の底](/docs/building/cross-cutting/version-adaptation#what-changed-at-l3-in-3-0) を追加しました — 必須の冪等性、公開されたライフサイクルステートマシン、適合性テストサーフェス、ベースラインとしての RFC 9421 署名、拡張エラーカタログ。以前のバージョンに対して最後に SDK を評価したなら、「SDK がすること」と「自分で書くもの」の間の線は動きました。
* **AdCP は外からは薄いプロトコルに見える。** 内側からは、実装者が初読で予期するより多くの L3（ステートマシン、冪等性、非同期タスクコントラクト、エラーセマンティクス、適合性）を持ちます。このページの分解は、L3 の見積もりが事前に可視になるよう存在します。

対象読者: 任意の言語の AdCP 実装者 — エージェントを構築、SDK を作成、または評価しているか。

## 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](#server-vs-client-at-each-layer) にジャンプ。

```mermaid theme={null}
%%{init: {"flowchart": {"htmlLabels": true, "wrappingWidth": 9999}, "themeVariables": {"fontSize": "14px"}}}%%
flowchart TB
    subgraph yours["yours, always"]
        L4["<b>L4 — Business logic</b><br/>Inventory forecasting · pricing · creative review · upstream ad-server calls<br/>(GAM / FreeWheel / Kevel / your decisioning engine)<br/><i>The agent's competitive surface — what makes your agent yours</i>"]
    end

    subgraph sdk["what an AdCP SDK provides"]
        direction TB
        L3["<b>L3 — Protocol semantics</b><br/>Lifecycle state machines · idempotency · error catalog · transition validation<br/>Async-task contract · webhook emission · conformance surface · response envelope"]
        L2["<b>L2 — Auth &amp; registry</b><br/>Agent identity verification · brand resolution · AAO bridge<br/>Multi-tenant account resolution · principal scoping · sandbox-vs-live routing"]
        L1["<b>L1 — Identity &amp; signing</b><br/>RFC 9421 HTTP message signatures · public-key registries<br/>Signature verification · replay-window enforcement · key rotation"]
        L0["<b>L0 — Wire &amp; transport</b><br/>JSON-over-HTTP framing · MCP message envelopes · A2A SSE streams<br/>JSON schema validation · language-native type generation"]
        L3 ~~~ L2
        L2 ~~~ L1
        L1 ~~~ L0
    end

    L4 ~~~ L3
```

### L0 — Wire & transport

それがすること: プロトコルバイトをワイヤーから取り出し型付きのインメモリ値に変える。スキーマ検証が不正なペイロードを入口で捕まえる。

その中にあるもの:

* HTTP ルーティング（または MCP-over-stdio の stdio）。
* MCP メッセージフレーミング（`tools/call` エンベロープ、JSON-RPC 2.0）。
* A2A SSE イベントストリーム。
* 仕様の `*.json` ファイルに対する JSON スキーマ検証（[Schemas](/docs/building/by-layer/L0/schemas) を参照）。
* 型生成: 仕様のスキーマから言語ネイティブ型を生成し、アプリケーションコードが静的にチェックされる。

L0 のみを持つなら、パーサーを持ちます。バイヤーの `create_media_buy` はあなたのスタック上の型付きオブジェクト — そして他のすべてを自分でしなければなりません。

*Client side:* 同じプリミティブ、鏡映方向。クライアントはアウトバウンドリクエストを同じスキーマに対してシリアライズし、同じ型生成パイプラインを通じてレスポンスを消費する。L0 は本質的に対称。

### L1 — Identity & signing

それがすること: リクエストがヘッダーが主張する者から来たこと、ボディが転送中に変更されなかったことを暗号学的に検証する。[Security model](/docs/building/concepts/security-model) と [実装プロファイル](/docs/building/by-layer/L1/security) を参照。

その中にあるもの:

* RFC 9421 HTTP メッセージ署名（`Signature-Input`、`Signature` ヘッダー）。
* エージェントレジストリからの公開鍵解決（またはオペレーター公開の JWKS）。
* 正準化されたリクエストに対する署名検証。
* リプレイウィンドウ強制（`created` / `expires` パラメーター）。
* 鍵ローテーション: 飛行中のリクエストを落とさずに `keyid` 変更を扱う。

L0+L1 を持つなら、誰があなたを呼んでいるかを知ります。まだ彼らが *何を* することを許されているかを知りません。

*Client side:* 自身の鍵でアウトバウンドリクエストに署名。エージェントからの webhook コールバックを検証。同じ RFC 9421 + リプレイウィンドウ + 鍵ローテーションのプリミティブ、すべてのリクエストの代わりに 1 つのインバウンドパス（webhook）だけ。

### L2 — Auth & registry

それがすること: 検証されたアイデンティティをスコープされたプリンシパルに変える — どのバイヤー、どのブランド、どの広告主アカウント、どの sandbox 対 live ティア。[Accounts](/docs/accounts/overview) と [Calling an agent](/docs/protocol/calling-an-agent) を参照。

その中にあるもの:

* エージェントレジストリルックアップ（公開された [エージェントカード](/docs/protocol/calling-an-agent) からエージェントメタデータを解決）。
* ブランド解決: [Brand Protocol](/docs/brand-protocol) 経由でリクエストエージェントをバイヤーブランド / 広告主アイデンティティにマッピング。
* AAO（[AgenticAdvertising.org](https://agenticadvertising.org)）ブリッジ: エージェントのメンバー組織、AAO Verified バッジ、レジストリ可視性を解決 — [Registering an agent](/docs/registry/registering-an-agent) と [AAO Verified](/docs/building/verification/aao-verified) を参照。
* マルチテナントアカウント解決: 同じワイヤーリクエストがプリンシパルに応じて異なるアカウントにマップする。
* Sandbox 対 live アカウントフラグ付け — [Sandbox](/docs/media-buy/advanced-topics/sandbox) を参照。
* 権限スコーピング: このプリンシパルがどの AdCP ツールを呼ぶことを許されるか。

L0+L1+L2 を持つなら、何かをしようとする検証されスコープされたプリンシパルを持ちます。まだ *その何か* が現在の状態で合法かを知りません。

*Client side:* 小さなサブセット。クライアントは自身のアイデンティティ（エージェントカード、ブランドドメイン）を公開し、レジストリ経由で呼んでいるエージェントをルックアップし、認証情報を提示する。マルチテナントルーティングなし、プリンシパルスコーピングなし、強制する sandbox/live 境界なし — クライアント *が* プリンシパルで、どのエージェントと話すかを選ぶ。

### L3 — Protocol semantics

それがすること: AdCP が *何を意味するか* を強制する。ワイヤー形状は整形式（L0）、呼び出し元は本物（L1）で認可済み（L2）。今: リクエストは世界の現在の状態を考慮して合法か？

その中にあるもの:

* **ライフサイクルステートマシン** — `MediaBuy`（[リファレンス](/docs/media-buy/media-buys/lifecycle)）、`Creative`、`Account`、`SISession`、`CatalogItem`、`Proposal`、`Audience`。それぞれが仕様で定義された合法エッジを持つ。
* **遷移検証** — リソースごとに合法エッジを強制。それを禁じる状態へのキャンセル試行に `NOT_CANCELLABLE`、他の不正な移動に `INVALID_STATE` を発する。試みられたアクションがキャンセルのとき、キャンセル固有のコードが汎用のものより優先する。
* **冪等性** — すべての変更ツールで `idempotency_key` 必須。同じキーが TTL 内でキャッシュされたレスポンスをリプレイ。クロスペイロード再利用が `IDEMPOTENCY_CONFLICT` で失敗（盗まれた鍵の read-oracle 脅威モデルに従いペイロードエコーなし）。[冪等性プロファイル](/docs/building/by-layer/L1/security#idempotency) を参照。
* **エラーコードカタログ** — リカバリーセマンティクス（`transient` / `correctable` / `terminal`）を持つコード。正しいコードの選択は仕様コントラクトの一部。[Error handling](/docs/building/by-layer/L3/error-handling) を参照。
* **非同期タスクコントラクト** — 同期的に完了しないツールは `task_id` を返す。クライアントはポーリングまたは webhook コールバックを受け取る。タスクの終端アーティファクトが元のツールのレスポンス形状を運ぶ。[Task lifecycle](/docs/building/by-layer/L3/task-lifecycle) を参照。
* **Webhook 発出** — 状態変更がサブスクライブしたバイヤーに通知、リトライ、冪等性、署名付き。[Webhooks](/docs/building/by-layer/L3/webhooks) を参照。
* **適合性テストサーフェス** — `comply_test_controller`（サンドボックス専用）が `seed_*` / `force_*` / `simulate_*` を公開し、ストーリーボードが状態を決定的に駆動できる。[comply\_test\_controller](/docs/building/by-layer/L3/comply-test-controller) と [Conformance](/docs/building/verification/conformance) を参照。
* **レスポンスエンベロープ** — `context`、`task_id`、`status` フィールド、エラーエンベロープ形状、`adcp_version` エコー、ケイパビリティアドバタイズ。

L0+L1+L2+L3 を持つなら、完全な AdCP プロトコル実装を持ちます。まだビジネスロジックを何もしていません。

*Client side:* コンシューマー側のミラー、はるかに小さい。クライアントは遷移を強制するのではなくステートマシンを *読む*（各終端ステータスを正しく扱う）。キャッシュを維持するのではなくリトライで `idempotency_key` を *供給* する。発する正しいものを選ぶのではなくエラーコードをリカバリーセマンティクスで *分類* する（`transient` → リトライ、`correctable` → 修正して再送信、`terminal` → リトライしない）。発するのではなく非同期タスク結果と webhook コールバックを *ポーリングまたは受け取る*。公開する `comply_test_controller` サーフェスはなく、コンシューマー側で認証する適合性のラインもない。このページの後の L3 人月見積もりはサーバー側。クライアント L3 は数か月ではなく数週間のハンドラーグルー。

### L4 — Business logic

これがあなたのエージェントをあなたのものにするものです。

その中にあるもの:

* 実際のアドサーバーに対するインベントリ予測。
* 価格ロジック、ディール条件、契約セマンティクス。
* クリエイティブレビューポリシー（ブランドセーフティ、フォーマットコンプライアンス）。
* GAM / FreeWheel / Kevel / Yahoo / 社内決定エンジンへの上流呼び出し。
* 最適化、ペーシング、詐欺検出 — インベントリを競合のものと差別化する何でも。

これは AdCP SDK があなたに委ねる層、**そしてこの層のみ** です。

*Client side:* L4 もあなたのもの、ただ異なる形状。呼び出し元の L4 はメディアプランニング、予算割り当て、ターゲットオーディエンス選択、ディール評価、レポート取り込み — 呼ぶエージェントであなたのバイ側アプリケーションがする何でも。仕様側リファレンスについては [Calling an agent](/docs/protocol/calling-an-agent) を参照。非対称性はスタック全体に及ぶ: エージェント L4 は *インベントリ* を、呼び出し元 L4 は *需要* を差別化する。

## Server vs client at each layer

同じ 5 つの層、非常に異なるコスト。呼び出し元のみのビルド対エージェントビルドの作業をサイズするときこれを使います。

| Layer  | Agent (server)                                                  | Caller (client)                                                            |
| ------ | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **L4** | インベントリ、価格、クリエイティブレビュー、アドサーバー統合。セラーとしてあなたを差別化するもの。               | プランニング、予算、エージェント選択、レポート消費。バイヤーとしてあなたを差別化するもの。                              |
| **L3** | ステートマシン、冪等性、エラーセマンティクス、適合性テストサーフェス、webhook 発出を **強制**。約 3〜4 人月。 | 同じものを **消費**。状態を読む、冪等性キーを供給、エラーを分類、非同期 + webhook をポーリング/受け取る。数週間のハンドラーグルー。 |
| **L2** | マルチテナントプリンシパル解決、sandbox/live 境界、ブランド解決、権限スコーピング。                | 自身のアイデンティティを公開。呼んでいるエージェントをルックアップ。はるかに小さいサーフェス。                            |
| **L1** | すべてのリクエストでインバウンドを検証。アウトバウンド webhook に署名。                        | すべてのリクエストでアウトバウンドに署名。インバウンド webhook を検証。同じ暗号、鏡映パス。                         |
| **L0** | 受信 + パース + スキーマに対して検証。                                          | シリアライズ + 送信 + スキーマに対して検証。対称。                                               |

一から作る呼び出し元は L0–L3 にわたる数週間の仕事です — ハンドラーグルー、署名、レジストリルックアップ、レスポンスパース — エージェント側が要求する [3〜4 人月の L3 ビルド](#why-sdks-matter-more-in-adcp-than-in-eg-http) ではありません。このページの残りはコストが存在するためエージェント側に集中しますが、層モデルと SDK カバレッジマトリクスは呼び出し元のみのビルドにも等しく適用されます。

## What an SDK at each layer should provide

実装者向けチェックリスト。層 L*n* のカバレッジを主張する 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 で [適合性のライン](/docs/building/verification/conformance) に到達することで、そこに到達するのにどれだけ手書きが必要だったかにかかわらずです。

特定の言語内では、フルスタック SDK がデフォルトの出発点です。このドキュメントの層モデルは、より低く行った（特殊目的プロキシ、カスタムスタック統合）または SDK を新しい言語に移植した場合に何を再実装するかを説明するために存在し — 典型的なエージェントビルドでより低く始めることに意味ある勝利があると示唆するためではありません。

### Current SDK coverage

**Python と TypeScript がファーストクラスの言語です。** 両方が完全な L0–L4 カバレッジにコミット — TypeScript は今日 L0–L3 全体で GA、Python は 4.x サイクルを同じラインに向けて仕上げ中。**Go** は同じ方向に動き、L0 と部分的 L1 が活発に開発中。**他の言語** は今日公式ロードマップにありませんが、コミュニティ保守のポートに開かれています — 手伝いたいなら [Builders Working Group](/docs/community/working-group) と [Slack コミュニティ](https://join.slack.com/t/agenticads/shared_invite/zt-3c5sxvdjk-x0rVmLB3OFHVUp~WutVWZg) を参照。

各公式 SDK が今日出荷するもののスナップショット。この表を SDK メジャーと AdCP 仕様改訂でリフレッシュしてください。

*最終更新: 2026-05-03。*

| SDK                  | Production GA | Beta / dev |  L0 |  L1 |  L2 |  L3 |
| -------------------- | ------------- | ---------- | :-: | :-: | :-: | :-: |
| **`@adcp/sdk`** (TS) | `6.9.0`       | —          |  ✅  |  ✅  |  ✅  |  ✅  |
| **`adcp`** (Python)  | `3.x`         | `4.x`      |  ✅  |  ⚠️ |  ⚠️ |  ⚠️ |
| **`adcp-go`**        | —             | `v1.x`     |  ⚠️ |  ❌  |  ❌  |  ❌  |

凡例: ✅ 出荷済み · ⚠️ 部分的 / 進行中 · ❌ まだ未カバー。**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](/docs/building/by-layer/L4/choose-your-sdk) を参照。

各層で「出荷済み」が何を意味するかは上の L0–L3 チェックリスト — これらの行は、公開された SDK ビルドですべてのチェックリスト項目が満たされるまで ✅ を主張すべきではありません。このスナップショットを超えたカバレッジ詳細については、各 SDK のリポジトリを参照。

形状比較の目的で、SDK が言語にかかわらず着地できる 3 つのカバレッジアーキタイプ:

| Archetype       | L0 | L1 | L2 | L3 | Adopter writes    |
| --------------- | -- | -- | -- | -- | ----------------- |
| フルスタック SDK      | ✅  | ✅  | ✅  | ✅  | L4 のみ             |
| トランスポート + 署名のみ  | ✅  | ✅  | ⚠️ | ❌  | L2 + L3 + L4      |
| 型のみ / 生成バインディング | ✅  | ❌  | ❌  | ❌  | L1 + L2 + L3 + L4 |

### Hosted implementations

SDK とは異なる形状: インポートするライブラリではなく実行する **デプロイ可能なエージェント**。採用者はコードではなく設定する。ハンドラーコードを自分で書かずに既存システムの前に AdCP サーフェスが欲しいとき有用。

| Implementation        | Maintainer                                            | Stack     | Notes                                                                                                                              |
| --------------------- | ----------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **AdCP mock-server**  | 仕様メンテナー                                               | Reference | ストーリーボードが対して実行するブラックボックス AdCP エージェント。すべての言語 SDK が mock-mode トラフィックをそれに転送。[仕様適合性](/docs/building/verification/conformance) の共有インフラ。 |
| **Prebid SalesAgent** | [Prebid コミュニティ](https://github.com/prebid/salesagent) | Python    | オープンソースのセラー側 AdCP エージェント。パブリッシャーが AdCP 向け実装として実行。今日 L0–L3 で手書き、公式 SDK と並んで進化。                                                      |

ホストされた実装は、SDK がするのと同じ L3 適合性のラインを満たします — 仕様は実装非依存です。違いは運用形状: ホストされた実装はデプロイして設定するサービス、SDK は自身のサービスにコンパイルするコードです。

選択はレバレッジと制御の間のトレードオフです。フルスタック SDK は最も多くのコードを無料で出荷しますが、その選択にあなたを結びつけます。トランスポートのみの SDK は最大の制御を与えますが、認証できる前に数か月の L1–L3 作業にサインアップさせます。ほとんどの本番採用者は、個々の層をスワップするオプション（カスタム署名プロバイダー、カスタムアカウントストア、カスタム冪等性バックエンド）を持つフルスタックを望みます — よく設計されたフルスタック SDK はそれをフォークではなく設定として公開します。

## Where can you start?

任意の層で実装できます。低く始めるほど、より多くを構築します。

| Starting layer               | What you write | What's done for you |
| ---------------------------- | -------------- | ------------------- |
| L0（一から）                      | 5 つすべての層       | なし                  |
| L1（JSON-over-HTTP ツールキットを持つ） | L1+L2+L3+L4    | L0（パーサー、スキーマ検証）     |
| L2（ライブラリ経由で HTTP 署名を持つ）      | L2+L3+L4       | L0+L1               |
| L3（認証/レジストリライブラリを持つ）         | L3+L4          | L0+L1+L2            |
| L4（フルスタック AdCP SDK を使う）      | L4 のみ          | L0+L1+L2+L3         |

フルスタック AdCP SDK はあなたを L4 に持ち上げます。あなたは上流呼び出しを実装します。SDK はそれらの周りにプロトコルエンベロープを通します。チームの付加価値が L4 差別化なら 1 つを選び、特定の理由があるならより低く構築する — そして L1–L3 のスコープを正直に予算化してください。

構築しているものに基づいて入口を選ぶ短い決定ページについては [Where to start](/docs/building) を参照。

## Why SDKs matter more in AdCP than in (e.g.) HTTP

一般的な比較: *「HTTP はプロトコルだ。人々は常に HTTP サーバーを一から構築する。なぜ AdCP は違うのか？」*

答えは層 L3 です。HTTP のプロトコルセマンティクスは最小 — メソッド、ステータスコード、ヘッダー。一から作る HTTP サーバーは既製のパーサーで週末に出荷できます。

AdCP の L3 は大きい:

* **ステートマシン** — 公開されたライフサイクルグラフを持つ 7 リソースタイプ。
* **非同期タスク** — すべての変更ツールが同期または非同期になりうる。どの終端アーティファクトがタスクを閉じるかのコントラクトは非自明。
* **冪等性** — キャッシュ、リプレイ、衝突、TTL — すべて正しく配線。
* **エラーカタログ** — リカバリー分類を持つコード。誤ったものを選ぶと [適合性](/docs/building/verification/conformance) に失敗。
* **適合性テストサーフェス** — ストーリーボードが [`comply_test_controller`](/docs/building/by-layer/L3/comply-test-controller) ツール経由で状態を駆動。非自明なコントローラーサーフェスを出荷する。
* **Webhook 発出** — 署名済み、リトライ済み、冪等。

一から作る AdCP エージェントは、任意の L4 差別化の前に **L3 作業だけで約 3〜4 人月** です。1 人のシニアエンジニアが mock-mode 適合性のラインまでの内訳は、おおよそ:

| L3 component                                                                     | Honest estimate      |
| -------------------------------------------------------------------------------- | -------------------- |
| 7 つのライフサイクルステートマシン（エッジを定義、遷移を検証、正しい `NOT_CANCELLABLE` / `INVALID_STATE` コードを発する） | 各約 1 週間 = **6〜7 週間** |
| 冪等性キャッシュ（クロスペイロード衝突検出 + no-payload-echo 不変条件）                                    | **1 週間**             |
| 非同期タスクストア + ディスパッチャー（ツールごとの正しい終端アーティファクトコントラクト）                                  | **1〜2 週間**           |
| エラーコードカタログ配線（リカバリー分類、コード優先度）                                                     | **1〜2 週間**           |
| `comply_test_controller` 適合性サーフェス（`seed_*` / `force_*` / `simulate_*`）           | **1〜2 週間**           |
| Webhook 発出（署名済み、リトライ済み、冪等、重複排除キー付き）                                              | **1 週間**             |
| RFC 9421 署名 + 検証 + リプレイウィンドウ + 鍵ローテーション（L1 として別途カウントされるが、通常同じスコープにバンドル）          | **2〜3 週間**           |
| 統合、適合性デバッグ、仕様の再読                                                                 | **2〜3 週間**           |

それは **約 14〜18 週間** で、チームの HTTP メッセージ署名とライフサイクルモデリングへの習熟に依存します。見積もりは **バージョン適応作業を除外** します — ツール、エッジ、エラーコードを追加するすべての仕様改訂が、あなたが永遠に運ぶ変換マトリクスに行を追加します。SDK 採用者はそれらを無料で得ます。一から作る実装者はすべてのリリースでそれらを払います。

これは 1 エンジニアから mock 適合性までの見積もりです。**パブリッシャー / 大規模プラットフォームスケールでは、SRE、セキュリティレビュー、既存の鍵インフラとの KMS / HSM 統合、負荷テスト、オンコール負担のため約 2 倍〜3 倍を掛けてください** — そのどれも L3 仕様作業ではなく、すべてがサーフェスが本番グレードになる前の実際のコストです。

「一から」は L0（ワイヤー形状）が視野の唯一の層のとき安く読めます。L3 が実際のスコープが隠れる場所です — 上の表は、チームがどちらにせよコミットする前に指すものです。

## Version adaptation

3 つの「バージョン」軸が同時に動き、SDK の仕事はそれらがあなたのビジネスロジック内で衝突するのを防ぐことです:

| Axis                | Example                  | What changes when it moves     |
| ------------------- | ------------------------ | ------------------------------ |
| **仕様バージョン**         | AdCP `2.5 → 3.0.5 → 3.1` | ワイヤー形状、エラーコード、ライフサイクル状態、新しいツール |
| **SDK バージョン**       | SDK `5.x → 6.x`          | API サーフェス、人間工学、コンパイル時保証        |
| **ピアバージョン（呼び出しごと）** | v3.0 のバイヤー、v2.5 のセラー     | 単一の会話がバージョンを越える。ペイロードが変換を要する   |

一から作るエージェントは 3 つすべてを手で扱わなければなりません。SDK は 3 つの具体的なメカニズムを出荷し、採用者がそうしないようにします:

1. **呼び出しごとの仕様バージョンピン留め。** エージェントに `adcpVersion`（または言語同等物）を設定。SDK はリクエストとレスポンスをアダプターモジュールを通し、ハンドラーコードがピアが何を話すかにかかわらず正準（現在）形状に留まる。
2. **共存インポート経由の SDK メジャー移行。** SDK メジャーを上げても同日の書き直しを強制しない — 前メジャーのサーフェスが新しいエントリポイントと並んで利用可能なまま。一度に 1 つの専門分野を移行。
3. **ワイヤーレベルネゴシエーション。** すべてのリクエストが `adcp_major_version` を運ぶ。サーバーはサポートするものを宣言し、呼び出し元が範囲外なら `VERSION_UNSUPPORTED`（リカバリー分類されたエラー）を返す。

メカニズムごとのコードレベルレシピは [Version Adaptation](/docs/building/cross-cutting/version-adaptation) にあります。仕様側のルールについては [Versioning](/docs/reference/versioning) を参照。

### Why this matters

AdCP のバージョニングは **エピソード的ではなく連続的** です。3.1 が出荷されたら、3.0 と 3.1 の呼び出し元と同時に、無期限に話します。変換アダプターなしではこれはコードベースのフォークです。それらがあればコンストラクターフラグです。

仕様自体が既にこれらの交差の 1 つをしました。**2.5 → 3.0** は実質的な L3 の底を追加しました — 正準リストについては [What changed at L3 in 3.0](/docs/building/cross-cutting/version-adaptation#what-changed-at-l3-in-3-0) を参照。一から作る 2.5 エージェントは扱いやすかった。一から作る 3.0 エージェントは上で分解された [約 3〜4 人月の L3 ビルド](#why-sdks-matter-more-in-adcp-than-in-eg-http) です。

2.5 で機能した一から作るパスは 3.0 にスケールせず、3.0 が仕様の止まる場所ではありません。SDK が存在するのは L3 が実装者が手書きできるより速く成長したからで、バージョン適応サーフェスはリリースごとに成長し続けます。

## Where the work actually lives

L3 コストが集中する 5 つの場所、おおよその桁順。一から作るビルドをスコープしているか手書きのものを再評価しているかの自己チェックとして有用:

1. **L3 が作業のほとんど。** ステートマシン、冪等性、エラーカタログ、非同期タスク — 任意の L4 差別化の前に約 3〜4 人月。コンポーネントごとの週については [分解](#why-sdks-matter-more-in-adcp-than-in-eg-http) を参照。
2. **適合性は L3 駆動。** ストーリーボードは状態遷移とエラー形状をプローブする（[Conformance](/docs/building/verification/conformance) を参照）。遷移検証器なしでは、仕様がテスト失敗から再導出される。
3. **バージョニングが複合する。** ツール、ライフサイクルエッジ、エラーコードを追加する各仕様改訂は、アダプター層が運ぶ新しい変換行。アダプター層の所有は、すべてのリリースでそのマトリクスを所有することを意味する。
4. **RFC 9421 + 鍵ローテーションは独自のプロジェクト。** 署名プロバイダー、KMS 統合、リプレイウィンドウ — 実際のエンジニアリング、そのどれも L4 差別化でない。
5. **mock-server は共有インフラ。** SDK は mock-mode ディスパッチをそれに無料で配線する。手書き実装は mock-mode をスキップする（そして仕様適合性認証を失う）か再構築するか。

SDK が多くをカバーする前に構築したなら、このリストは再評価への入力 — どちらにせよの判定ではありません。[移行ガイド](/docs/building/by-layer/L4/migrate-from-hand-rolled) が、部分的スワップが価値があると決めるチームのため swap-one-layer-at-a-time パスを案内します: どの層を最初にスワップするか、注意すべき衝突モード、どの中間状態がまだ適合性を通過するか。

## What this means for compliance

2 種類のコンプライアンス、両方が層モデルによって形作られる:

* **仕様適合性（L3 プロトコルテスト）** — 実装は AdCP ワイヤーコントラクトを満たすか？ ストーリーボードがステートマシンを歩き、エラーコードを実行し、非同期タスクコントラクトをテストする。採用者の上流は無関係。**mock-mode** アカウントに対して実行: エージェントがすべてのツール呼び出しをリファレンスモックサーバーに転送。これが SDK の（または手書き実装の）L3 層を認証する。
* **ライブ適合性（フルスタックテスト、計画中）** — 実際にデプロイされたエージェント（テストインフラに対する採用者の L4 コード）がストーリーボードの下でエンドツーエンドで正しく振る舞うか？ **sandbox-mode** アカウントに対して実行: mock ではなく採用者のコードパスが実行される。これが L0–L3 + 採用者の上流が結合して正しいワイヤー動作を生成することを認証する。

リファレンスモックサーバーは **仕様適合性オラクル** です — ストーリーボードが対して実行するブラックボックス AdCP エージェント。すべての言語 SDK が mock-mode トラフィックを HTTP 上でそれに転送するため、リファレンスパスはエコシステム全体で共有される。mock-server は SDK 非依存: 手書きの L0–L3 実装は、自身の mock 風味のアカウントを同じ mock-server にルーティングし自身の L3 ワイヤー動作に対してストーリーボードの pass/fail を検証することで仕様適合性を通過できる。失敗が SDK または mock 自体を巻き込むときの権威チェーンとトリアージ順については、[Mock-server authority and failure triage](/docs/building/verification/conformance#mock-server-authority-and-failure-triage) を参照。

## TL;DR

* AdCP は 5 つの層を持つ。仕様は L0–L3 に存在し、あなたのエージェントは L4 に存在する。
* 「一から」は L0–L3 を自分で実装することを意味する。それは多い — [コンポーネントごとの内訳](#why-sdks-matter-more-in-adcp-than-in-eg-http) を参照。
* フルスタック AdCP SDK はあなたを L4 に持ち上げる。あなたはビジネスロジックを書き、SDK がプロトコルを扱う。異なる言語 SDK は L0–L3 の異なるサブセットをカバーする。継承したいプロトコルの量に合うものを選ぶ — [カバレッジマトリクス](#current-sdk-coverage) を参照。
* **バージョン適応は SDK 機能で、採用者プロジェクトではない。** 呼び出しごとの仕様バージョンアダプター、SDK メジャーをまたいだ共存インポート、ワイヤー上の `adcp_major_version` ネゴシエーションが、ハンドラーをフォークせずに任意のサポートバージョンのピアと話させる。手書きエージェントは変換マトリクス全体を永遠に継承する。
* コンプライアンスは 2 つの風味で来る: **仕様適合性**（mock-mode、プロトコルのみ、L3 リファレンステスト）と **ライブ適合性**（sandbox-mode、フルスタック、L0–L4 エンドツーエンド、計画中）。
* 3.0 の前に最後に SDK を評価したなら、比較は動いた — [3.0 が追加した L3 の底](/docs/building/cross-cutting/version-adaptation#what-changed-at-l3-in-3-0) を参照。覚えているものではなく今日のカバレッジに対して再評価してください。