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 only the representable criteria subset. A normal compact result requires a real seller-issued feed version and cache scope; exact `product_ids` require paging one stable feed until every ID is found or the feed is exhausted. 3.0 and 2.5 cannot supply the ordinary fenced result.
`requestProposals`	`get_products` brief	`orchestrated`	Project genuine proposals only when every canonical commercial term is present. A products-only legacy result becomes the projection-only `products_available` compatibility outcome with an actionable continuation; never fabricate a proposal or digest.
`refineProposals`	`get_products` refine or proposal finalize	`orchestrated`	Translate only dimensions the legacy peer represents exactly. Mint and durably map immutable successors; finalize batches require the same all-or-none hold boundary.
`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. orchestrated is conditional, not a promise that every valid compact payload can be sent to every earlier 3.x peer. Adapters MUST preflight each structured field and fail before calling the peer when the older version has no exact representation. They MUST preserve legacy incomplete[], time-budget, and product-pagination semantics instead of turning a partial result into complete success. In particular, 2.5 has no wholesale-feed contract, while 3.0 has wholesale pagination but no seller-issued feed or pricing fence. Released 3.1 can support a normal listProducts projection only when the seller returns a real scope-correct wholesale feed version and all requested criteria map exactly.

Products-only brief results

A valid 2.5, 3.0, or 3.1 brief may return useful products and no proposals. Compact compatibility preserves that result as products_available. This is a projection-only compatibility outcome: native 3.2 sellers do not emit it, and ordinary request_proposals success still contains a genuine proposal. Its purchase_continuation is discriminated:

listed_purchase is available only after the coordinator re-reads the exact selected products through a real seller-issued, account-scoped feed and obtains its feed and pricing fences. Those seller values flow unchanged into buyProducts.
legacy_create routes to established explicit-package create_media_buy when no truthful fence exists. It declares feed_version_not_atomic and pricing_version_not_atomic. For AdCP 2.5 it additionally declares mutation_idempotency_not_guaranteed; 3.0 and 3.1 declare that loss when the actual peer cannot provide their mutation replay guarantee. It fails closed unless the caller explicitly accepts every returned loss before mutation.

Client SDKs expose that second path through an SDK-local continueLegacyPurchase operation using the generated CompatibilityPurchaseCoordinatorInput type. The input carries a coordinator idempotency key, the opaque token, the bound account, selected product IDs, the exact accepted loss set, and the proposed source-version create_media_buy payload. It is not an AdCP tool payload. The coordinator validates every binding, exact consent, expiry, source-version request schema, and token claim before sending only the legacy create request. Exact retries resume durable state; crash-ambiguous mutations fail unless they can be reconciled authoritatively. The coordinator never promotes products into a feed on the seller’s behalf and never synthesizes feed_version, pricing_version, a proposal, commercial_terms, or terms_digest. A projection token may bind the observed response to the caller, account, and selected payload, but it is not a seller-issued atomic fence. The legacy seller still revalidates availability and price during create. This compatibility outcome and its legacy continuation are deprecated in 3.2 and removed in AdCP 4.0. In the reverse direction, a 3.2 seller advertising established get_products and create_media_buy facades keeps products returned by a products-only brief executable through that same legacy create facade. An established buyer is never required to understand products_available or an SDK-local continuation token. For every proposal revision and finalization, the adapter MUST retain a durable mapping from the current successor proposal_id to the legacy source ID. 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. A legacy proposal may be projected only when the adapter can source every required purchase price, resolved flight, brand, and other canonical term. Valid legacy proposals may omit those facts; the adapter returns products_available or a typed capability error rather than filling the gaps itself. Simple free-text refinement and product include/omit operations may map when their result is a complete successor. Typed budget, CPM, impression, flight, alternative-count, criteria-replacement, amendment, and cancellation semantics need exact adapters or a pre-mutation failure. Legacy more_like_this maps to free text only with explicit lossy consent. Legacy proposal omit is response filtering and MUST NOT be interpreted as terminal declineProposals; no legacy decline fallback exists. Released legacy get_products does not provide the compact tasks’ required mutation-idempotency contract. Durable local replay state is necessary but is not sufficient when a process can crash after the seller commits and before the adapter records the response. Unless the adapter can authoritatively reconcile that state, it MUST fail the fallback rather than claim compact exactly-once behavior. 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. The complete version and transaction-boundary matrix is in specs/legacy-compact-lifecycle-compatibility.md.

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

Products-only brief results

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

​Products-only brief results

​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

Products-only brief results

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