Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/test-agent-3-3-preview-docs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"adcontextprotocol": patch
---

Docs: the 3.3 beta program page explains how to try the public test agent's opt-in `3.3-beta.3` preview. It covers which pins are served the preview, which experimental 3.3 surfaces become reachable, and that the preview is experimental and moves with each beta. The page now also records that `@adcp/sdk` 17.0.0-beta.11 and later bundle `3.3.0-beta.3`. The quickstart points to the preview.
2 changes: 2 additions & 0 deletions docs/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ export AGENT_URL="https://test-agent.adcontextprotocol.org/sales/mcp"

The test agent is path-routed: `/sales/mcp` serves media-buy tools (this quickstart's path), and sibling URLs serve the other specialisms — `/signals/mcp`, `/governance/mcp`, `/creative/mcp`, `/creative-builder/mcp`, `/brand/mcp`. Hit [`/.well-known/adagents.json`](https://test-agent.adcontextprotocol.org/.well-known/adagents.json) for the full tenant + tool list.

The test agent serves AdCP 3.2, 3.1, and 3.0. It also serves the 3.3 beta as an experimental preview, but only to requests that pin `adcp_version: "3.3-beta.3"` exactly. See [Try the preview on the public test agent](/docs/reference/3-3-beta#try-the-preview-on-the-public-test-agent).

For your own API key (org-scoped, usage tracking), create one at the [AAO dashboard](https://agenticadvertising.org/dashboard/api-keys).

To test an OAuth connect flow, use `/sales/mcp` and follow its `401`
Expand Down
40 changes: 37 additions & 3 deletions docs/reference/3-3-beta.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: AdCP 3.3 beta program
sidebarTitle: 3.3 beta program
description: "Where the AdCP 3.3 beta stands at beta.3, how to test a beta before SDK support, which SDK versions bundle which beta, and which proposals are still in review for 3.3."
description: "Where the AdCP 3.3 beta stands at beta.3, how to test a beta before SDK support or against the public test agent's preview, which SDK versions bundle which beta, and which proposals are still in review for 3.3."
"og:title": "AdCP — 3.3 beta program"
---

Expand All @@ -24,7 +24,7 @@ The latest checkpoint is **`3.3.0-beta.3`, published 2026-10-31**. Each beta is
| `3.3.0-beta.2` | 2026-10-30 | Account change outcomes, seller offers, measurement provenance, structural capability bounds, the principal clarification, reporting-subscription convergence, and the withdrawal of definition pins, purchase rights, and installment selection | The same teams, against the withdrawn surfaces removed |
| `3.3.0-beta.3` | 2026-10-31 | Live creative updates, the protocol envelope on every task response, money terms on resolved account requests, revocation as no access, and reporting-subscription coverage computable from the wire | The same teams; this is the checkpoint the docs describe |

Beta.0 did not wait for the SDKs. A checkpoint is SDK-backed only after the matching SDK versions and integration evidence are published, and no published SDK bundles beta.3 yet ([SDK guidance](#sdk-guidance)). Three features that shipped in the betas are [withdrawn after beta.1](#withdrawn-after-beta-1).
Beta.0 did not wait for the SDKs. A checkpoint is SDK-backed only after the matching SDK versions and integration evidence are published. `@adcp/sdk` 17.0.0-beta.11 is the first published SDK that bundles beta.3 ([SDK guidance](#sdk-guidance)). Three features that shipped in the betas are [withdrawn after beta.1](#withdrawn-after-beta-1).

## Know which version string to use

Expand Down Expand Up @@ -68,6 +68,40 @@ Useful tests are:
4. Exercise raw MCP or A2A calls with `adcp_version: "3.3-beta.3"` against a staging peer that advertises the same pin.
5. Run the compliance assets with a source-compatible runner if you maintain one. Do not weaken production authentication to accommodate a beta runner.

## Try the preview on the public test agent

The public test agent at `https://test-agent.adcontextprotocol.org` serves `3.3.0-beta.3` as an opt-in preview alongside its stable releases. It lists `"3.3-beta.3"` in `adcp.supported_versions` and serves the preview only to a request that pins exactly that value:

| Request | Served |
|---|---|
| `adcp_version: "3.3-beta.3"` | The preview. Responses echo `"3.3-beta.3"` and validate against the published `3.3.0-beta.3` schemas. |
| `adcp_version: "3.2"`, `"3.3"`, or a later release | 3.2. A release pin never resolves onto a prerelease. |
| Any other 3.3 prerelease, such as `"3.3-beta.2"` | Never the preview. Prerelease pins match exactly. |
| `adcp_major_version` alone, or no version | The route's stable default, never the preview. |

```bash
curl -s https://test-agent.adcontextprotocol.org/sales/mcp \
-H "Authorization: Bearer $ADCP_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_adcp_capabilities","arguments":{"adcp_version":"3.3-beta.3"}}}'
```

At the preview pin, `/sales/mcp` serves the experimental 3.3 surfaces the training agent implements:

- account requests (`account.requests`): `request_account`, and `account_requests` on `list_accounts`;
- the caller's `authorization`, with `authorized_at` and `regranted_at`, and `revision` on each `list_accounts` account;
- principal-level reporting subscriptions (`media_buy.reporting_subscriptions`): the `reporting_subscriptions` section of `sync_principal` and `get_principal`, and `subscription_coverage` on `get_reporting_status`;
- the `reporting_subscription_probe` controller scenario, which revokes, reduces, and restores grants and advances a per-caller sandbox clock.

`tools/list` includes `request_account` only when the listing is pinned to the preview (`params._meta.adcp_version`, as `@adcp/sdk` sends it). Hold policy, `extend_hold`, and response collections are not served yet ([#8181](https://github.com/adcontextprotocol/adcp/issues/8181)).

With `@adcp/sdk`, use 17.0.0-beta.11 or later, which negotiates exactly `3.3-beta.3`. Earlier 17.0.0 betas bundle an older beta, so they settle on 3.2 with the test agent.

<Warning>
**The preview is experimental and can change without notice.** It follows the latest published beta and moves to the next one when it ships. Once it moves, the old pin is no longer served. AAO can also switch the preview off, after which the agent serves only its stable releases. Use it to try 3.3 surfaces, not as a stable integration target.
</Warning>

<Note>
**No 3.3 verification badge is issued from a beta.** A beta bundle is an implementation input, not a certification target, and prerelease grading runs are diagnostic, as they were for 3.2.
</Note>
Expand All @@ -88,7 +122,7 @@ SDK maintainers should report protocol ambiguities against the [AdCP repository]

## SDK guidance

**TypeScript.** Use `@adcp/sdk` **17.0.0-beta.6 or later** (npm `beta` dist-tag) to test 3.3. The published prereleases bundle a signed AdCP release: 17.0.0-beta.6 bundles `3.3.0-beta.1`, and 17.0.0-beta.10 bundles `3.3.0-beta.2`. No published `@adcp/sdk` bundles `3.3.0-beta.3` yet, so the beta.3 surfaces (live creative updates, the envelope on every response, money terms on resolved account requests, and the reporting-subscription coverage rules) are raw-wire only until an SDK ingests that bundle. Pin the exact SDK version, and send a prerelease `adcp_version` only to a peer that advertises that exact pin. `@adcp/sdk` 17 is a major release; read its [16 to 17 migration guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-16-to-17.md) first.
**TypeScript.** Use `@adcp/sdk` **17.0.0-beta.6 or later** (npm `beta` dist-tag) to test 3.3. The published prereleases bundle a signed AdCP release: 17.0.0-beta.6 bundles `3.3.0-beta.1`, 17.0.0-beta.10 bundles `3.3.0-beta.2`, and 17.0.0-beta.11 and later bundle `3.3.0-beta.3`. Each negotiates only its own beta, so a buyer and seller on different betas settle on a stable release. Pin the exact SDK version, and send a prerelease `adcp_version` only to a peer that advertises that exact pin. `@adcp/sdk` 17 is a major release; read its [16 to 17 migration guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-16-to-17.md) first.

**Python.** There is no Python SDK release that bundles a 3.3 beta. Support is pending [adcp-client-python#1560](https://github.com/adcontextprotocol/adcp-client-python/issues/1560), which is open. Until it lands, use the `adcp` 3.2 release for production-line work and validate 3.3 behavior over the raw wire against the signed bundle.

Expand Down
24 changes: 24 additions & 0 deletions server/src/scripts/verify-training-agent-runtime-assets.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,13 @@ import { readFile } from 'node:fs/promises';
import path from 'node:path';
import { resolveAdcpVersion } from '@adcp/sdk';
import {
ensurePreviewSchemaBundle,
ensureTrainingAgentSchemaBundle,
PREVIEW_SCHEMA_BUNDLE,
resolveRetainedSchemaRoot,
RETAINED_SCHEMA_BUNDLE,
} from '../training-agent/schema-compat.js';
import { TRAINING_AGENT_HOSTED_PREVIEW } from '../training-agent/candidate-version.js';
import { SELLER_GOVERNANCE_DISCOVERY_ADCP_VERSION } from '../training-agent/types.js';
import { coverageModelHasZone, resolveCoverageModelDir } from '../training-agent/reporting-coverage-model.js';

Expand Down Expand Up @@ -44,6 +47,27 @@ console.log(
`Training-agent runtime schema verified: ${resolvedVersion} -> ${schemaRoot}`,
);

// The hosted 3.3 preview validates against its committed published bundle.
// Checked even when the kill switch is set, so the image can always serve it.
const previewRoot = resolveRetainedSchemaRoot(undefined, undefined, TRAINING_AGENT_HOSTED_PREVIEW.bundle);
const previewIndex = JSON.parse(await readFile(path.join(previewRoot, 'index.json'), 'utf8')) as { adcp_version?: unknown };
if (previewIndex.adcp_version !== TRAINING_AGENT_HOSTED_PREVIEW.bundle) {
throw new Error(
`Training-agent preview schema index ${previewRoot} declares ${String(previewIndex.adcp_version)}; ` +
`expected ${TRAINING_AGENT_HOSTED_PREVIEW.bundle}`,
);
}
if (PREVIEW_SCHEMA_BUNDLE) {
await ensurePreviewSchemaBundle();
const previewResolved = resolveAdcpVersion(TRAINING_AGENT_HOSTED_PREVIEW.wireVersion);
if (previewResolved !== TRAINING_AGENT_HOSTED_PREVIEW.wireVersion && previewResolved !== TRAINING_AGENT_HOSTED_PREVIEW.bundle) {
throw new Error(
`Training-agent preview version ${TRAINING_AGENT_HOSTED_PREVIEW.wireVersion} resolved as ${previewResolved}`,
);
}
}
console.log(`Training-agent preview schema verified: ${TRAINING_AGENT_HOSTED_PREVIEW.wireVersion} -> ${previewRoot}`);

// Reporting-subscription coverage runs the spec's reference model at runtime.
const coverageModelDir = resolveCoverageModelDir();
if (!coverageModelHasZone('America/New_York')) {
Expand Down
75 changes: 74 additions & 1 deletion server/src/training-agent/candidate-version.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
/** Trusted local storyboard processes may serve their generated source bundle.
* Production and ordinary training-agent processes retain released contracts.
* Production and ordinary training-agent processes serve released contracts
* only: the stable lines and, unless disabled, the published preview below.
* This selects a wire release only; it does not enable experimental features. */
export function trainingAgentCandidateVersion(
env: Record<string, string | undefined> = process.env,
Expand All @@ -10,3 +11,75 @@ export function trainingAgentCandidateVersion(
}

export const TRAINING_AGENT_CANDIDATE_ADCP_VERSION = trainingAgentCandidateVersion();

/**
* The published prerelease the hosted training agent serves as an opt-in
* preview (#8181): wire value and the committed, immutable schema bundle
* (`dist/schemas/<bundle>`) its responses validate against.
*
* It must name the prerelease whose published schemas match what the agent
* emits. main's source schemas are structurally identical to 3.3.0-beta.3
* (only descriptions changed since), and @adcp/sdk 17.0.0-beta.11 and later
* negotiate exactly `3.3-beta.3`. Advance both together with the next 3.3
* prerelease cut; tenants/served-release-shape.test.ts grades the agent's
* preview responses against this bundle.
*/
export const TRAINING_AGENT_HOSTED_PREVIEW = Object.freeze({
wireVersion: '3.3-beta.3',
bundle: '3.3.0-beta.3',
} as const);

/** Ops kill switch: set to `1` or `true` to stop advertising and serving the
* preview. Read at startup, so it takes effect on the next restart without a
* code change. A process with the switch set negotiates exactly as one that
* never listed the preview. */
export const TRAINING_AGENT_PREVIEW_KILL_SWITCH = 'TRAINING_AGENT_DISABLE_ADCP_PREVIEW';

export function trainingAgentPreviewDisabled(
env: Record<string, string | undefined> = process.env,
): boolean {
const value = env[TRAINING_AGENT_PREVIEW_KILL_SWITCH]?.trim().toLowerCase();
return value === '1' || value === 'true';
}

/**
* The one prerelease this process serves to callers that pin it exactly:
* the trusted storyboard candidate when candidate mode is on, otherwise the
* hosted preview unless the kill switch is set. Never served to unpinned,
* major-only or release-pinned callers (versioning.mdx, "Pre-release pins").
*/
export function trainingAgentPreviewVersion(
env: Record<string, string | undefined> = process.env,
): string | undefined {
const candidate = trainingAgentCandidateVersion(env);
if (candidate) return candidate;
return trainingAgentPreviewDisabled(env) ? undefined : TRAINING_AGENT_HOSTED_PREVIEW.wireVersion;
}

export const TRAINING_AGENT_PREVIEW_ADCP_VERSION = trainingAgentPreviewVersion();

/** Whether this process serves the published hosted preview (as opposed to a
* local candidate, or no prerelease at all). */
export const TRAINING_AGENT_SERVES_HOSTED_PREVIEW = TRAINING_AGENT_PREVIEW_ADCP_VERSION !== undefined
&& TRAINING_AGENT_PREVIEW_ADCP_VERSION !== TRAINING_AGENT_CANDIDATE_ADCP_VERSION;

/** Whether an MCP request selects this process's preview by an exact pin: a
* `tools/call` whose arguments carry it, or a `tools/list` that carries it in
* params or `params._meta` (as @adcp/sdk sends it). */
export function requestPinsPreview(
body: unknown,
preview: string | undefined = TRAINING_AGENT_PREVIEW_ADCP_VERSION,
): boolean {
if (!preview || !body || typeof body !== 'object') return false;
const { method, params } = body as { method?: unknown; params?: Record<string, unknown> };
if (!params || typeof params !== 'object') return false;
if (method === 'tools/call') {
const args = params.arguments as { adcp_version?: unknown } | undefined;
return args?.adcp_version === preview;
}
if (method === 'tools/list') {
const meta = params._meta as { adcp_version?: unknown } | undefined;
return params.adcp_version === preview || meta?.adcp_version === preview;
}
return false;
}
5 changes: 5 additions & 0 deletions server/src/training-agent/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ import {
import { isWorkOSApiKeyFormat } from '../middleware/api-key-format.js';
import { buildGovernanceAgentCredentialAuthenticator } from './governance-agent-credentials.js';
import { createTrainingBuyerOAuthMiddleware, trainingBuyerOAuthConfig, trainingBuyerMetadata, trainingBuyerDocumentation, TRAINING_BUYER_METADATA_PATH } from './buyer-oauth.js';
import { requestPinsPreview } from './candidate-version.js';
import { ensurePreviewSchemaBundle } from './schema-compat.js';

const logger = createLogger('training-agent-routes');

Expand Down Expand Up @@ -428,6 +430,8 @@ export function createTrainingAgentRouter(options: {
}
}

// Served-release shaping reads the hosted preview's published bundle.
if (requestPinsPreview(req.body)) await ensurePreviewSchemaBundle();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
enableJsonResponse: true,
Expand Down Expand Up @@ -515,6 +519,7 @@ export function createTrainingAgentRouter(options: {
}
}

if (requestPinsPreview(req.body)) await ensurePreviewSchemaBundle();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
enableJsonResponse: true,
Expand Down
52 changes: 46 additions & 6 deletions server/src/training-agent/schema-compat.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,11 @@ import {
SELLER_GOVERNANCE_DISCOVERY_ADCP_VERSION,
TRAINING_AGENT_RETAINED_RC_ADCP_VERSION,
} from './types.js';
import { TRAINING_AGENT_CANDIDATE_ADCP_VERSION } from './candidate-version.js';
import {
TRAINING_AGENT_CANDIDATE_ADCP_VERSION,
TRAINING_AGENT_HOSTED_PREVIEW,
TRAINING_AGENT_SERVES_HOSTED_PREVIEW,
} from './candidate-version.js';

function canonicalSchemaBundleVersion(version: string): string {
const match = version.match(/^(\d+)\.(\d+)(?:\.(\d+))?((?:-(?:beta|rc)\.\d+)?)$/);
Expand Down Expand Up @@ -48,6 +52,17 @@ export const CANDIDATE_SCHEMA_BUNDLE = TRAINING_AGENT_CANDIDATE_ADCP_VERSION
: undefined;
const CANDIDATE_SCHEMA_TREE = 'latest';

/**
* The hosted preview's published bundle (candidate-version.ts), registered
* from the committed, immutable dist/schemas/<bundle> tree under its own
* release key, so preview responses are validated against exactly what was
* published. The installed @adcp/sdk may package a different 3.3 beta, or
* none. Unset when the preview is disabled or a local candidate replaces it.
*/
export const PREVIEW_SCHEMA_BUNDLE: string | undefined = TRAINING_AGENT_SERVES_HOSTED_PREVIEW
? TRAINING_AGENT_HOSTED_PREVIEW.bundle
: undefined;

let registration: Promise<void> | undefined;

export function resolveRetainedSchemaRoot(
Expand Down Expand Up @@ -75,7 +90,8 @@ export function resolveRetainedSchemaRoot(
* Register the training agent's retained prerelease checkpoints (beta.6 and
* the last 3.2 RC) with SDK builds that do not package them,
* and, in a trusted candidate process, the built source tree under the
* candidate's release key (see CANDIDATE_SCHEMA_BUNDLE).
* candidate's release key (see CANDIDATE_SCHEMA_BUNDLE). The hosted preview's
* bundle is registered separately, on first use (ensurePreviewSchemaBundle).
*
* This is deliberately lazy: @adcp/sdk/testing owns the public external-root
* API, but the rest of that entry point is unnecessary unless the training
Expand All @@ -99,11 +115,35 @@ export function ensureTrainingAgentSchemaBundle(): Promise<void> {
// (adcontextprotocol/adcp-client#3519, still so in 17.0.0-beta.6).
// Register there too, or the rule reads the published bundle and drops
// `status`. Remove with #3519's fix.
const cjsTesting = createRequire(import.meta.url)('@adcp/sdk/testing') as {
registerExternalSchemaRoot: (version: string, schemaRoot: string) => void;
};
cjsTesting.registerExternalSchemaRoot(CANDIDATE_SCHEMA_BUNDLE, root);
cjsRegisterExternalSchemaRoot(CANDIDATE_SCHEMA_BUNDLE, root);
}
});
return registration;
}

let previewRegistration: Promise<void> | undefined;

/**
* Register the hosted preview's published bundle (PREVIEW_SCHEMA_BUNDLE) with
* the SDK. Lazy: registering a full bundle costs seconds, so only the preview
* registry and preview-pinned requests on the v5 route pay it. The ESM loader
* is enough: the published bundle composes the envelope the way the SDK's
* status rule expects, so preview responses keep `status` without the
* CommonJS registration the candidate needs (served-release-shape.test.ts
* grades it). A no-op when the preview is off.
*/
export function ensurePreviewSchemaBundle(): Promise<void> {
if (!PREVIEW_SCHEMA_BUNDLE) return Promise.resolve();
const bundle = PREVIEW_SCHEMA_BUNDLE;
previewRegistration ??= import('@adcp/sdk/testing').then(({ registerExternalSchemaRoot }) => {
registerExternalSchemaRoot(bundle, resolveRetainedSchemaRoot(undefined, undefined, bundle));
});
return previewRegistration;
}

function cjsRegisterExternalSchemaRoot(version: string, schemaRoot: string): void {
const cjsTesting = createRequire(import.meta.url)('@adcp/sdk/testing') as {
registerExternalSchemaRoot: (version: string, schemaRoot: string) => void;
};
cjsTesting.registerExternalSchemaRoot(version, schemaRoot);
}
Loading
Loading