AdCP — Version Adaptation

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 → 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.

AdCP v2.5 is end of life. The v2.5 examples below describe a temporary migration bridge for existing integrations, not a supported production configuration. New integrations must use v3.

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({
  idempotency_key: '550e8400-e29b-41d4-a716-446655442052',
  buying_mode: 'brief',
  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.

Same-major tool replacements

AdCP 3.2’s compact lifecycle replaces the broad get_products, create_media_buy, and update_media_buy facades with narrower tool names. This is not ordinary version-shape adaptation: some current operations need more than one legacy call, and one has no faithful legacy equivalent. The release manifest makes that distinction machine-readable through legacy_fallback on each replacement and superseded_by on each compatibility facade.

Current SDK method	Legacy peer tool	Fallback mode	Required behavior
`listProducts`	`get_products` wholesale	`orchestrated`	Translate the common case directly; when exact `product_ids` are requested, page and filter until every requested ID is found or the feed is exhausted
`requestProposals`	`get_products` brief	`orchestrated`	Return immutable draft snapshots with source IDs preserved
`refineProposals`	`get_products` refine or proposal finalize	`orchestrated`	Mint draft revisions or committed held snapshots with source-result correspondence and atomic finalize batches
`declineProposals`	none	`none`	Throw a typed capability error before sending a call; never silently discard terminal feedback
`buyProducts`	`create_media_buy` explicit packages	`orchestrated`	Translate product purchases to packages without adding creatives, then materialize the accepted proposal snapshot expected by the current result
`acceptProposal`	`create_media_buy` proposal mode	`orchestrated`	Execute a new-buy proposal directly; amendment/cancellation proposals require an SDK-managed compatibility workflow or a typed capability error when the legacy seller cannot preserve it
`controlMediaBuy`	`update_media_buy`	`orchestrated`	Map only canonical operational fields and never route creative, flight, package-addition, or billing-term mutations through this adapter

Client SDKs SHOULD expose the current methods as their primary API and choose the peer path from media_buy.lifecycle_tools. A directly advertised current tool always wins. A direct fallback may run transparently. An orchestrated fallback may run transparently only when the SDK ships a handwritten adapter that preserves the current tool’s result completeness, terminal state, atomicity, and idempotency semantics; the manifest classification does not synthesize that state machine. In particular, SDKs adapting a direct 3.x creation MUST retain the accepted commercial snapshot locally when the legacy seller cannot return it, and MUST not pretend a legacy seller supports proposal-based amendments. Each underlying legacy mutation needs its own deterministic replay identity, and retrying the current SDK call must resume rather than restart the sequence. Otherwise the SDK MUST throw a typed CapabilityUnsupportedError carrying requested_tool, the peer’s advertised tools, and fallback_mode. For proposal finalization, the adapter MUST retain a durable mapping from the current successor proposal_id to the legacy source ID that get_products finalized. A later acceptProposal sends the mapped legacy ID to create_media_buy while returning and retaining the current immutable successor snapshot. The mapping is part of the adapter’s replay state: losing it, reusing the source ID as the current ID, or minting a second successor on retry violates the 3.2 contract. These tools deliberately retain distinct operation_family values. Fallback metadata describes SDK adaptation, not cross-name authorization, idempotency equivalence, task recovery, or webhook identity. A client adapter MUST be authorized for the actual legacy call; a grant for a split tool does not transfer across names. Server SDKs may implement the current lifecycle once and derive the deprecated facades for 3.x callers, but may advertise only behavior the adapter actually preserves.

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', '3.1' — 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. If you want to surface your deployment’s patch build for incident triage, use the build_version capability field — not supported_versions. 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', '3.1'],
    // …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({
    idempotency_key: '550e8400-e29b-41d4-a716-446655442053',
    buying_mode: 'brief',
    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({
  idempotency_key: '550e8400-e29b-41d4-a716-446655442054',
  buying_mode: 'brief',
  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 supported multi-version production setup, with an optional migration-only bridge for an end-of-life v2.5 peer:

Server: declare supported_versions: ['3.0', '3.1'] 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.)
Client (per peer): pin adcpVersion to a supported release based on what the registry or peer’s capabilities advertise. Use 'v2.5' only as a short-lived migration bridge for an existing end-of-life peer; the client-side adapters translate its wire shape so your application code stays on the current spec.
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.

Getting Started

Building with AdCP

Protocol

FAQ

Trust & Security

Reference

Certification

Version Adaptation

Mechanism 1 — Pin the spec version per call

Pin the version on a single agent

Validate the version up front

What the adapters actually do

Same-major tool replacements

Mechanism 2 — Migrate SDK majors via co-existence

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

When to actually migrate

Mechanism 3 — Wire-level negotiation

Declare what you support

What happens on a mismatch

Buyer side: two surfaces

Putting it together

What this saves you from building

What changed at L3 in 3.0

See also

​Mechanism 1 — Pin the spec version per call

​Pin the version on a single agent

​Validate the version up front

​What the adapters actually do

​Same-major tool replacements

​Mechanism 2 — Migrate SDK majors via co-existence

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

​When to actually migrate

​Mechanism 3 — Wire-level negotiation

​Declare what you support

​What happens on a mismatch

​Buyer side: two surfaces

​Putting it together

​What this saves you from building

​What changed at L3 in 3.0

​See also

Mechanism 1 — Pin the spec version per call

Pin the version on a single agent

Validate the version up front

What the adapters actually do

Same-major tool replacements

Mechanism 2 — Migrate SDK majors via co-existence

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

When to actually migrate

Mechanism 3 — Wire-level negotiation

Declare what you support

What happens on a mismatch

Buyer side: two surfaces

Putting it together

What this saves you from building

What changed at L3 in 3.0

See also