Version Adaptation

Three version axes move at the same time when you ship an AdCP agent — spec version, SDK version, and per-peer version. SDKs ship three concrete mechanisms (per-call pinning, co-existence imports, on-wire negotiation) so adopters don’t carry the translation matrix in handler code.

Three versions move at the same time when you ship an AdCP agent or client:

Axis	Example	What changes
Spec version	AdCP 2.5 → 3.0.5 → 3.1	Wire shapes, error codes, lifecycle states, new tools
SDK version	SDK 5.x → 6.x	API surface, ergonomics, compile-time guarantees
Peer version (per call)	Buyer at v3.0, seller at v2.5	A single conversation crosses versions

Official SDKs ship three concrete mechanisms so adopters don’t carry the translation matrix in handler code. This page is the recipe per mechanism. For the conceptual background see the SDK stack — Version adaptation section. For the spec-side rules see Versioning.

Mechanism 1 — Pin the spec version per call

Use this when you’re a client talking to a peer that’s pinned to an older (or newer beta) spec version. The SDK runs your request and the peer’s response through adapter modules so your handler code stays on the canonical (current) shape.

Pin the version on a single agent

JavaScript / TypeScript (@adcp/sdk):

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 and Go SDKs expose the same mechanism under their idiomatic call sites — see each SDK’s repo. The shape is consistent: per-agent or per-call version pin, validated at construction time, with adapter modules translating to/from the canonical shape transparently.

Validate the version up front

adcpVersion (or the language equivalent) is validated at construction time. The SDK only accepts versions whose schema bundle ships with the build — if the bundle isn’t present (e.g., you pinned a beta channel that hasn’t been synced into your installed SDK), construction throws a typed configuration error with a pointer to the schema-sync tooling.

To see what your installed SDK actually has bundled, query the SDK’s compatibility-list export — every official SDK exposes one. For the spec-side authoritative list of what each AdCP version means on the wire, see schemas/.

What the adapters actually do

Each SDK ships per-tool adapter modules — pure shape translations (field renames, default population, structural reshaping). The SDK applies them transparently when the version pin is set; your handler sees the current shape regardless of which version the peer speaks.

When AdCP 3.1 ships and you bump the SDK, a new adapter folder appears for the now-legacy 3.0. Your handlers don’t move.

Mechanism 2 — Migrate SDK majors via co-existence

Use this when you bump your SDK from one major to the next and don’t want to rewrite every handler the day you upgrade. Each SDK keeps the prior major’s surface available alongside the new entry point.

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

In v6.0, the v5 entry point was hard-removed from the top-level export. Existing v5 code keeps working by swapping one import path:

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

Greenfield code in the same project uses the v6 entry point side by side:

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

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

Both compile, both run, both pass conformance. You migrate one handler — or one specialism — at a time. The legacy subpath is a documented co-existence path, not a deprecation warning.

Other-language SDKs follow the same pattern: prior-major surfaces remain importable from a versioned subpath alongside the current entry point. Check each SDK’s release notes for the specific import paths.

When to actually migrate

Stay on the legacy surface as long as it keeps compiling and passing conformance. Migrate a specialism when you want the new features (compile-time specialism enforcement, capability projection, idempotency / signing / async-task / status-normalization pre-wiring on greenfield code). There’s no rush.

Mechanism 3 — Wire-level negotiation

Use this when you’re a server and you want to be explicit about which spec versions you accept.

Declare what you support

supported_versions (release-precision strings) and/or major_versions go on your agent’s capability declaration. Use release-precision strings — '3.0.5', '3.1.0' — not the legacy aliases ('v2.5', 'v3') used for client-side pinning. A 3.x server with no v2.5 handler logic should not declare 'v2.5' here — its 2.5 callers go through client-side adapters at the buyer end, not the server’s accepted-version set.

Example with @adcp/sdk (lower-level handler-bag API):

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

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

The union of supported_versions (parsed to majors) and major_versions defines the seller’s accepted set on inbound adcp_major_version / adcp_version claims. See Versioning — version negotiation for the spec rules and the bidirectional negotiation flow introduced in 3.1.

What happens on a mismatch

If a buyer’s request carries an adcp_major_version (or adcp_version) that isn’t in the accepted set, the SDK returns a VERSION_UNSUPPORTED error envelope. The envelope echoes the seller’s supported_versions so the buyer can downgrade their pin without an out-of-band lookup. See VERSION_UNSUPPORTED error data for the envelope shape.

Buyer side: two surfaces

There are two places version mismatch can surface on the client, and they fire in different conditions:

1. Pre-flight typed exception. When the client already has the peer’s capabilities cached and knows up front that the call won’t go through, the SDK throws a typed VersionUnsupportedError (or language equivalent) before sending the request. Catch it from the call site:

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 envelope from the wire. When the mismatch is only detected on the server side (e.g., the buyer’s adcp_major_version parses different than the buyer’s adcp_version string), the response carries a typed VERSION_UNSUPPORTED error envelope that echoes the seller’s supported_versions:

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 is recovery-classified correctable — clients that handle it programmatically retry against a supported version.

This is the third mechanism rather than a fallback to the first: negotiation tells you what’s possible; per-call pinning tells the SDK which one to use.

Putting it together

A typical multi-version production setup:

1. Server: declare supported_versions: ['3.0.5', '3.1.0'] in capabilities. The SDK accepts both on the wire and returns VERSION_UNSUPPORTED to anyone outside the set. (Only declare a version your handlers actually satisfy.)
2. Client (per peer): pin adcpVersion (e.g., 'v2.5') based on what the registry or peer’s capabilities advertise. The client-side adapters translate the wire shape so your application code stays on the current spec.
3. SDK upgrades: bump the SDK on your schedule; switch to the new entry point per specialism over time; keep the rest on the legacy import until you’re ready.

The combined effect: one handler codebase, three version axes, no fork.

What this saves you from building

A from-scratch agent has to:

• Maintain a translation matrix between every spec version it claims to support, and update it every time a release ships.
• Hand-roll API stability across its own internal refactors.
• Implement the negotiation handshake (adcp_major_version parsing, adcp_version cross-checks, VERSION_UNSUPPORTED envelope shaping with the supported-versions echo).
• Keep its conformance test surface in sync as new versions ship.

Each of these compounds at every spec revision. SDKs absorb them so your team’s effort goes into L4 differentiation, not into versioning plumbing.

What changed at L3 in 3.0

If you’re scoping a hand-rolled agent against today’s spec, the L3 surface added with AdCP 3.0 is the largest delta from 2.5. Most of what an SDK does at L3 didn’t exist as a published primitive before 3.0:

• Mandatory idempotency — idempotency_key required on every mutating tool, with the replayed: true / IDEMPOTENCY_CONFLICT / IDEMPOTENCY_EXPIRED semantics declared on get_adcp_capabilities. See Idempotency on Calling an agent.
• Published lifecycle state machines — seven resource types (MediaBuy, Creative, Account, SISession, CatalogItem, Proposal, Audience) with legal-edge enforcement and the NOT_CANCELLABLE / INVALID_STATE precedence.
• Conformance test surface — comply_test_controller (sandbox-only) so storyboards drive state deterministically. Replaces ad-hoc per-seller test endpoints.
• RFC 9421 signatures as a baseline — optional in 3.0, mandatory under AAO Verified. Replaces the loose-bearer-token posture of 2.5.
• Expanded error catalog with recovery classification — 18 standard error codes with transient / correctable / terminal recovery semantics. Hand-rolled 2.5 agents typically returned unstructured error strings.
• Async-task contract — every mutating tool can be sync or async; the contract for which terminal artifact closes the task is specified.
• Webhook signing — push notifications signed with the same RFC 9421 profile as outbound requests; replay-window + retry semantics specified.

For the full 3.0 changelog (protocol-wide, not just L3), see What’s new in v3. For the migration path, see Migrate from a hand-rolled agent.

A from-scratch 2.5 agent was tractable; a from-scratch 3.0 agent is the 3–4 person-month L3 build decomposed in the SDK stack reference. SDKs exist because L3 grew faster than implementers could hand-roll.

See also

• The AdCP stack — layered architecture reference
• Where to start — decision page
• Versioning — spec-side version rules
• What’s new in v3 — protocol-wide 3.0 changelog
• Migrate from a hand-rolled agent — when adopting a stack with mid-flight buyers on different spec versions