> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 → 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](/docs/building/cross-cutting/sdk-stack#version-adaptation). For the spec-side rules see [Versioning](/docs/reference/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`):

```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 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/`](https://github.com/adcontextprotocol/adcp/tree/main/dist/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:

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

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

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

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](/docs/building/verification/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):

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

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](/docs/reference/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](/docs/reference/versioning#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:

```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` 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`:

```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` 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', '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.)
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](/docs/protocol/calling-an-agent#idempotency-replay-vs-new-operation).
* **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`](/docs/building/by-layer/L3/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](/docs/reference/whats-new-in-v3). For the migration path, see [Migrate from a hand-rolled agent](/docs/building/by-layer/L4/migrate-from-hand-rolled).

A from-scratch 2.5 agent was tractable; a from-scratch 3.0 agent is the [3–4 person-month L3 build](/docs/building/cross-cutting/sdk-stack#why-sdks-matter-more-in-adcp-than-in-eg-http) decomposed in the SDK stack reference. SDKs exist because L3 grew faster than implementers could hand-roll.

## See also

* [The AdCP stack](/docs/building/cross-cutting/sdk-stack) — layered architecture reference
* [Where to start](/docs/building) — decision page
* [Versioning](/docs/reference/versioning) — spec-side version rules
* [What's new in v3](/docs/reference/whats-new-in-v3) — protocol-wide 3.0 changelog
* [Migrate from a hand-rolled agent](/docs/building/by-layer/L4/migrate-from-hand-rolled) — when adopting a stack with mid-flight buyers on different spec versions