> ## 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 エージェントを出荷するとき 3 つのバージョン軸が同時に動く — 仕様バージョン、SDK バージョン、ピアごとのバージョン。SDK は 3 つの具体的なメカニズム（呼び出しごとのピン留め、共存インポート、ワイヤーネゴシエーション）を出荷し、採用者がハンドラーコードに変換マトリクスを運ばないようにする。

AdCP エージェントまたはクライアントを出荷するとき、3 つのバージョンが同時に動きます:

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

公式 SDK は 3 つの具体的なメカニズムを出荷し、採用者がハンドラーコードに変換マトリクスを運ばないようにします。このページはメカニズムごとのレシピです。概念的背景については [SDK スタック — バージョン適応セクション](/docs/building/cross-cutting/sdk-stack#version-adaptation) を参照。仕様側のルールについては [Versioning](/docs/reference/versioning) を参照。

## Mechanism 1 — 呼び出しごとに仕様バージョンをピン留め

古い（またはより新しいベータ）仕様バージョンにピン留めされたピアと話す **クライアント** のときこれを使います。SDK はあなたのリクエストとピアのレスポンスをアダプターモジュールを通し、あなたのハンドラーコードが正準（現在）形状に留まるようにします。

### 単一エージェントでバージョンをピン留め

JavaScript / TypeScript（`@adcp/sdk`）:

```ts theme={null}
import { ADCPMultiAgentClient } from '@adcp/sdk';

const client = ADCPMultiAgentClient.simple(
  'https://legacy-agent.example.com/mcp/',
  {
    auth_token: process.env.AGENT_TOKEN,
    adcpVersion: 'v2.5', // ← pin here
  },
);

const agent = client.agent('default-agent');
const result = await agent.getProducts({ brief: 'CTV inventory' });
```

Python と Go の SDK は同じメカニズムをそのイディオム的な呼び出しサイトの下で公開します — 各 SDK のリポジトリを参照。形状は一貫しています: エージェントごとまたは呼び出しごとのバージョンピン、構築時に検証、アダプターモジュールが正準形状に/から透過的に変換。

### 事前にバージョンを検証

`adcpVersion`（または言語同等物）は構築時に検証されます。SDK は、**スキーマバンドルがビルドとともに出荷される** バージョンのみを受け入れます — バンドルが存在しない（例: インストールされた SDK に同期されていないベータチャネルをピン留めした）場合、構築はスキーマ同期ツールへのポインター付きの型付き設定エラーを throw します。

インストールされた SDK が実際に何をバンドルしているかを見るには、SDK の互換性リストエクスポートをクエリします — すべての公式 SDK が 1 つを公開します。各 AdCP バージョンがワイヤー上で何を意味するかの仕様側の権威あるリストについては、[`schemas/`](https://github.com/adcontextprotocol/adcp/tree/main/dist/schemas) を参照。

### アダプターが実際にすること

各 SDK はツールごとのアダプターモジュール — 純粋な形状変換（フィールドリネーム、デフォルト投入、構造的再形成） — を出荷します。SDK はバージョンピンが設定されているときそれらを透過的に適用します。あなたのハンドラーは、ピアがどのバージョンを話すかにかかわらず現在の形状を見ます。

AdCP 3.1 が出荷され SDK を上げると、今やレガシーの 3.0 用の新しいアダプターフォルダーが現れます。あなたのハンドラーは動きません。

## Mechanism 2 — 共存経由で SDK メジャーを移行

SDK をあるメジャーから次に上げ、アップグレードした日にすべてのハンドラーを書き直したくないときこれを使います。各 SDK は前メジャーのサーフェスを新しいエントリポイントと並んで利用可能に保ちます。

### 例: `@adcp/sdk` 5.x → 6.x

v6.0 では、v5 エントリポイントがトップレベルエクスポートからハードに削除されました。既存の v5 コードは 1 つのインポートパスをスワップすることで機能し続けます:

```ts theme={null}
// v5 code — change only the import path
import { createAdcpServer } from '@adcp/sdk/server/legacy/v5';

serve(() => createAdcpServer({
  name: 'My Agent',
  version: '1.0.0',
  // …existing v5 handler bag — unchanged
}));
```

同じプロジェクトのグリーンフィールドコードは v6 エントリポイントを並べて使います:

```ts theme={null}
import { createAdcpServerFromPlatform } from '@adcp/sdk/server';

const platform = new MyPlatform(); // implements DecisioningPlatform
const server = createAdcpServerFromPlatform(platform, {
  name: 'my-agent',
  version: '1.0.0',
});
```

両方がコンパイルし、両方が実行し、両方が適合性を通過します。一度に 1 つのハンドラー — または 1 つの専門分野 — を移行します。レガシーサブパスは、非推奨警告ではなく文書化された共存パスです。

他言語の SDK は同じパターンに従います: 前メジャーのサーフェスが現在のエントリポイントと並んでバージョン管理されたサブパスからインポート可能なままです。特定のインポートパスについては各 SDK のリリースノートを確認してください。

### いつ実際に移行するか

コンパイルし [適合性](/docs/building/verification/conformance) を通過し続ける限りレガシーサーフェスに留まります。新機能（コンパイル時専門分野強制、ケイパビリティ投影、グリーンフィールドコードでの冪等性 / 署名 / 非同期タスク / ステータス正規化の事前配線）が欲しいとき専門分野を移行します。急ぐ必要はありません。

## Mechanism 3 — ワイヤーレベルネゴシエーション

**サーバー** で、どの仕様バージョンを受け入れるかについて明示的にしたいときこれを使います。

### サポートするものを宣言

`supported_versions`（リリース精度文字列）および/または `major_versions` がエージェントのケイパビリティ宣言に載ります。リリース精度文字列 — `'3.0'`、`'3.1'` — を使い、クライアント側ピン留めに使われるレガシーエイリアス（`'v2.5'`、`'v3'`）は使いません。v2.5 ハンドラーロジックのない 3.x サーバーはここに `'v2.5'` を宣言すべきではありません — その 2.5 呼び出し元は、サーバーの受け入れバージョンセットではなく、バイヤー側の *クライアント側* アダプターを通ります。インシデントトリアージのためにデプロイのパッチビルドをサーフェスしたい場合、`supported_versions` ではなく `build_version` ケイパビリティフィールドを使います。

`@adcp/sdk` の例（より低レベルの handler-bag API）:

```ts theme={null}
import { createAdcpServer } from '@adcp/sdk/server';

const server = createAdcpServer({
  name: 'My Agent',
  version: '1.0.0',
  capabilities: {
    major_versions: [3],
    supported_versions: ['3.0', '3.1'],
    // …other capability fields
  },
  // …handlers
});
```

`supported_versions`（メジャーにパース）と `major_versions` の union が、インバウンド `adcp_major_version` / `adcp_version` クレームに対するセラーの受け入れセットを定義します。仕様ルールと 3.1 で導入された双方向ネゴシエーションフローについては [Versioning — version negotiation](/docs/reference/versioning#version-negotiation) を参照。

### 不一致で何が起こるか

バイヤーのリクエストが受け入れセットにない `adcp_major_version`（または `adcp_version`）を運ぶ場合、SDK は `VERSION_UNSUPPORTED` エラーエンベロープを返します。エンベロープはセラーの `supported_versions` をエコーするため、バイヤーは帯域外ルックアップなしにピンをダウングレードできます。エンベロープ形状については [VERSION\_UNSUPPORTED error data](/docs/reference/versioning#version-unsupported-error-data) を参照。

### バイヤー側: 2 つのサーフェス

バージョン不一致がクライアントでサーフェスしうる場所は 2 つあり、異なる条件で発火します:

**1. プリフライトの型付き例外。** クライアントがピアのケイパビリティを既にキャッシュしていて、呼び出しが通らないと事前に知っているとき、SDK はリクエストを送る *前に* 型付き `VersionUnsupportedError`（または言語同等物）を throw します。呼び出しサイトからキャッチ:

```ts theme={null}
import { VersionUnsupportedError } from '@adcp/sdk';

try {
  const result = await agent.getProducts({ brief: '…' });
} catch (err) {
  if (err instanceof VersionUnsupportedError) {
    // peer doesn't support this call at the pinned version —
    // re-pin adcpVersion or switch agents
  }
  throw err;
}
```

**2. ワイヤーからの `VERSION_UNSUPPORTED` エンベロープ。** 不一致がサーバー側でのみ検出される（例: バイヤーの `adcp_major_version` がバイヤーの `adcp_version` 文字列と異なってパースされる）とき、レスポンスはセラーの `supported_versions` をエコーする型付き `VERSION_UNSUPPORTED` エラーエンベロープを運びます:

```ts theme={null}
const result = await agent.getProducts({ brief: '…' });

if (!result.success && result.adcpError?.code === 'VERSION_UNSUPPORTED') {
  const supported = result.adcpError.details?.supported_versions ?? [];
  // pick a version you also support, then re-issue with adcpVersion pinned
}
```

`VERSION_UNSUPPORTED` はリカバリー分類 `correctable` です — プログラム的に扱うクライアントはサポートされるバージョンに対してリトライします。

これは最初のものへのフォールバックではなく 3 番目のメカニズムです: ネゴシエーションは *何が可能か* を教え、呼び出しごとのピン留めは SDK に *どれを使うか* を伝えます。

## まとめ

典型的なマルチバージョン本番セットアップ:

1. **サーバー**: ケイパビリティに `supported_versions: ['3.0', '3.1']` を宣言。SDK はワイヤー上で両方を受け入れ、セット外の誰にでも `VERSION_UNSUPPORTED` を返す。（ハンドラーが実際に満たすバージョンのみを宣言。）
2. **クライアント（ピアごと）**: レジストリまたはピアのケイパビリティがアドバタイズするものに基づいて `adcpVersion`（例: `'v2.5'`）をピン留め。クライアント側アダプターがワイヤー形状を変換し、あなたのアプリケーションコードが現在の仕様に留まる。
3. **SDK アップグレード**: 自分のスケジュールで SDK を上げる。時間をかけて専門分野ごとに新しいエントリポイントに切り替える。準備できるまで残りをレガシーインポートに保つ。

結合効果: **1 つのハンドラーコードベース、3 つのバージョン軸、フォークなし。**

## 構築せずに済むもの

一から作るエージェントは次をしなければなりません:

* サポートを主張するすべての仕様バージョン間の変換マトリクスを維持し、リリースが出荷されるたびに更新する。
* 自身の内部リファクタリングにわたって API 安定性を手書きする。
* ネゴシエーションハンドシェイクを実装する（`adcp_major_version` パース、`adcp_version` クロスチェック、supported-versions エコーを伴う `VERSION_UNSUPPORTED` エンベロープ形成）。
* 新しいバージョンが出荷されるにつれ適合性テストサーフェスを同期に保つ。

これらのそれぞれがすべての仕様改訂で複合します。SDK はそれらを吸収するため、チームの労力はバージョニング配管ではなく L4 差別化に行きます。

## What changed at L3 in 3.0

今日の仕様に対して手書きエージェントをスコープしているなら、AdCP 3.0 で追加された L3 サーフェスが 2.5 からの最大の差分です。SDK が L3 ですることのほとんどは 3.0 の前に公開されたプリミティブとして存在しませんでした:

* **必須の冪等性** — すべての変更ツールで `idempotency_key` 必須、`replayed: true` / `IDEMPOTENCY_CONFLICT` / `IDEMPOTENCY_EXPIRED` セマンティクスが `get_adcp_capabilities` で宣言。[Calling an agent の冪等性](/docs/protocol/calling-an-agent#idempotency-replay-vs-new-operation) を参照。
* **公開されたライフサイクルステートマシン** — 合法エッジ強制と `NOT_CANCELLABLE` / `INVALID_STATE` 優先度を持つ 7 リソースタイプ（`MediaBuy`、`Creative`、`Account`、`SISession`、`CatalogItem`、`Proposal`、`Audience`）。
* **適合性テストサーフェス** — ストーリーボードが状態を決定的に駆動する [`comply_test_controller`](/docs/building/by-layer/L3/comply-test-controller)（サンドボックス専用）。場当たり的なセラーごとのテストエンドポイントを置き換え。
* **ベースラインとしての RFC 9421 署名** — 3.0 では任意、AAO Verified の下で必須。2.5 の緩い bearer トークン姿勢を置き換え。
* **リカバリー分類を伴う拡張エラーカタログ** — `transient` / `correctable` / `terminal` リカバリーセマンティクスを持つ 18 の標準エラーコード。手書き 2.5 エージェントは通常非構造化エラー文字列を返した。
* **非同期タスクコントラクト** — すべての変更ツールが同期または非同期になりうる。どの終端アーティファクトがタスクを閉じるかのコントラクトが指定される。
* **Webhook 署名** — アウトバウンドリクエストと同じ RFC 9421 プロファイルで署名されたプッシュ通知。リプレイウィンドウ + リトライセマンティクスが指定される。

完全な 3.0 チェンジログ（L3 だけでなくプロトコル全体）については [v3 の新機能](/docs/reference/whats-new-in-v3) を参照。移行パスについては [手書きエージェントから移行する](/docs/building/by-layer/L4/migrate-from-hand-rolled) を参照。

一から作る 2.5 エージェントは扱いやすかった。一から作る 3.0 エージェントは、SDK スタックリファレンスで分解された [3〜4 人月の L3 ビルド](/docs/building/cross-cutting/sdk-stack#why-sdks-matter-more-in-adcp-than-in-eg-http) です。SDK が存在するのは、L3 が実装者が手書きできるより速く成長したからです。

## 関連項目

* [AdCP スタック](/docs/building/cross-cutting/sdk-stack) — 層アーキテクチャリファレンス
* [どこから始めるか](/docs/building) — 決定ページ
* [Versioning](/docs/reference/versioning) — 仕様側のバージョンルール
* [v3 の新機能](/docs/reference/whats-new-in-v3) — プロトコル全体の 3.0 チェンジログ
* [手書きエージェントから移行する](/docs/building/by-layer/L4/migrate-from-hand-rolled) — 異なる仕様バージョンの飛行中バイヤーを持つスタックを採用するとき