バージョン適応

​

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

​

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

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' });

​

事前にバージョンを検証

​

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

​

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

​

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

// 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
}));

import { createAdcpServerFromPlatform } from '@adcp/sdk/server';

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

​

いつ実際に移行するか

​

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

​

サポートするものを宣言

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
});

​

不一致で何が起こるか

​

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

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;
}

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
}

​

まとめ

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

​

構築せずに済むもの

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

​

What changed at L3 in 3.0

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

​

関連項目

• AdCP スタック — 層アーキテクチャリファレンス
• どこから始めるか — 決定ページ
• Versioning — 仕様側のバージョンルール
• v3 の新機能 — プロトコル全体の 3.0 チェンジログ
• 手書きエージェントから移行する — 異なる仕様バージョンの飛行中バイヤーを持つスタックを採用するとき