Migrating from 3.0 to 3.1
3.1 is released. New 3.1 integrations should pin
"3.1" after confirming the agent advertises it in supported_versions. Existing 3.0 integrations can remain pinned to "3.0" while they migrate."3.0" without changing request or response shapes. Experimental surfaces follow their separate stability contract; TMP operators should apply the immediate v3.1.22 guidance below. Use this guide when you are preparing an SDK, buyer, seller, creative agent, signal agent, brand agent, or compliance workflow to claim or consume 3.1.
For the feature narrative, start with What’s New in AdCP 3.1. For the full release record, see Release Notes.
Immediate Context Match cache action
Version 3.1.22 shipped emergency privacy/security corrections for Context Match: #7396 restricts non-public single-user context, and #7397 requires request-aware response-cache partitioning. Router operators affected by unsafe caching MUST bypass or disable Context Match response caching until they implement both the v3.1.22 request-aware partition and a trusted namespace covering every result-affecting authentication, authorization, tenant, active-package, endpoint, provider-configuration, model, and targeting/rules generation. The trustedcache_namespace conformance contract is defined for 3.2 in main #7446 and becomes effective October 25, 2026. It is immediate safe-operations guidance for affected deployments, but it is not a retroactive 3.1 conformance requirement. If the router cannot establish either the complete request partition or the trusted provider-evaluation namespace, keep cache lookup, coalescing, and insertion disabled.
Version 3.1.22 was an emergency security exception to the normal six-week experimental-change notice process. Its published package, tag, and versioned artifacts remain immutable; the missing #7397 changelog coverage is carried forward by an independent v3.1.23 patch changeset. See the v3.1.22 release note for the release record.
Upgrade checklist
Version pinning
3.0 integrations negotiated by major version only. 3.1 adds release-precision negotiation:- Use
"3.0"for stable 3.0 traffic. - Use
"3.1"for stable 3.1 traffic after the agent advertises it. - Do not send patch values such as
"3.0.19"or full semver prereleases such as"3.1.0-rc.15"on the wire.
VERSION_UNSUPPORTED and include the supported release list in error.data.supported_versions. Buyers should not silently downshift across minor releases. Surface the mismatch or retry against a version the seller explicitly advertised.
Runtime changes to audit
Idempotency and read-envelope tolerance
3.0 requiredidempotency_key on mutating requests. The original 3.1 text extended keyed replay to reads, but reference SDKs continued to generate keys only for requests they classified as mutating. Read wrappers must tolerate an optional key; buyers should not rely on byte-stable read replay. Hand-rolled buyers should generate UUID v4 keys for mutations and may omit them on pure reads.
When a response is marked replayed: true, treat it as the historical result of the original operation. If you need fresh state before acting, re-read the relevant resource after handling the replayed response.
Envelope tolerance
3.1 relies on transport adapters tolerating the AdCP envelope root. MCP and A2A clients should unwrap the transport-specific wrapper first, then read AdCP fields such asstatus, result, errors, adcp_version, replayed, and context. Unknown envelope members must not cause rejection.
Error decoding
The standard error catalog expanded in 3.1, buterror.code remains an open string. Clients should:
- Accept unknown error codes.
- Prefer
error.recoverywhen present. - Apply a bounded transient fallback for unknown legacy errors when
error.recoveryis absent. - Handle the auth split between
AUTH_MISSINGandAUTH_INVALID. - Treat
CREDENTIAL_IN_ARGSas terminal and move credentials to the proper transport channel before retrying.
Proposal and action discovery cleanup
3.1 makesproposal_status the proposal source of truth and uses structured action discovery on products and buys. Sellers should not emit the pre-GA requires_proposal action mode. Buyers with cached prerelease action metadata should invalidate it and re-read the product, proposal, or buy surface.
Brand verification signing
Brand agents that implementverify_brand_claim or verify_brand_claims must return signed response evidence. Publish a per-brand response-signing key and bind signatures to the task, resolved brand tenant, responding agent URL, caller/request hash, and validity window.
Signal targeting
Signal identity moves towardSignalRef, with product-scoped included_signals, signal_targeting_options, and buy-time signal_targeting_groups. Owned-signal discovery and marketplace activation are separate capabilities. Buyers should call activate_signal only when the agent declares marketplace or activation support.
Creative formats and transformers
Creative agents should expose canonicalformat_kind values and discover build units through list_transformers. Format-attached input/output/pricing declarations are deprecated in favor of transformer-scoped configuration and pricing. Hosted audio/video slots should use duration_ms_exact for fixed durations and duration_ms_range for bounded or one-sided ranges.
Reporting and billing
3.1 adds delivery and usage finality markers, reach-window semantics,viewability.viewed_seconds, and the BILLING_OUT_OF_BAND error for creative billing outside AdCP. Buyers should avoid treating delivery numbers as final until the relevant finality fields say they are final.
Role-based migration
Prerelease artifacts
The 3.1 prerelease artifacts remain available for adopters who pinned them during validation, but new integrations should use the stable"3.1" wire value. If you built against a prerelease, invalidate cached prerelease-only fields such as requires_proposal, re-read current product/proposal/action metadata, and rerun the 3.1 storyboard bundle before claiming the stable release.