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/rc0-sdk-and-test-agent-preview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"adcontextprotocol": patch
---

Docs: `@adcp/sdk` 17.0.0-beta.29 and Python `adcp` 10.0.0b20 bundle `3.3.0-rc.0`, and the public test agent's opt-in 3.3 preview moves to `3.3-rc.0`. Choose your SDK, the 3.3 prerelease page, the release notes, Versions, and the quickstart name the new versions and pin. `@adcp/sdk` 17.0.0-beta.24 through 17.0.0-beta.28 and Python `adcp` 10.0.0b17 through 10.0.0b19 support beta.6. The training agent's hosted preview is `3.3-rc.0`, validated against the published `3.3.0-rc.0` schemas.
12 changes: 6 additions & 6 deletions docs/building/by-layer/L4/choose-your-sdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -43,18 +43,18 @@ Production stays on the 3.2 line and the packages above. For development and sta

| SDK | Package | AdCP bundle | Roles and transports | Known limits |
|---|---|---|---|---|
| **`@adcp/sdk`** (TypeScript) | `17.0.0-beta.28` (npm `beta` dist-tag) | Signed `3.3.0-beta.6`; also bundles stable 3.2.8, 3.1.31 and 3.0.25. Earlier 3.3 betas require a matching external schema root | Buyer client and seller server, MCP and A2A | Identity and Web Bot Auth (`@adcp/sdk/identity-3.3`) remain experimental opt-ins. Use a Reliable Reporting storage release whose `@adcp/sdk` peer range matches this SDK. |
| **`adcp`** (Python) | `10.0.0b17` (PyPI prerelease) | Signed `3.3.0-beta.6` | Buyer client and seller server, MCP and A2A | Negotiates only `3.3-beta.6`. Install the exact prerelease with `pip install --pre "adcp==10.0.0b17"`; for Reliable Reporting storage, use an `adcp-reporting-storage` prerelease whose `adcp` requirement matches this SDK. |
| **`@adcp/sdk`** (TypeScript) | `17.0.0-beta.29` (npm `beta` dist-tag) | Signed `3.3.0-rc.0`; also bundles stable 3.2.8, 3.1.31 and 3.0.25. Earlier 3.3 betas require a matching external schema root | Buyer client and seller server, MCP and A2A | Identity and Web Bot Auth (`@adcp/sdk/identity-3.3`) remain experimental opt-ins. Use a Reliable Reporting storage release whose `@adcp/sdk` peer range matches this SDK. |
| **`adcp`** (Python) | `10.0.0b20` (PyPI prerelease) | Signed `3.3.0-rc.0` | Buyer client and seller server, MCP and A2A | Negotiates only `3.3-rc.0`. Install the exact prerelease with `pip install --pre "adcp==10.0.0b20"`; for Reliable Reporting storage, use an `adcp-reporting-storage` prerelease whose `adcp` requirement matches this SDK. |
| Go, Java | — | No 3.3 prerelease | — | Not supported for 3.3. Test from these languages through raw-wire calls against the signed bundle. |

SDK prereleases that adopt `3.3.0-rc.0` follow within days of the cut, and this table gains their rows when they publish. Until a row names rc.0, test rc.0 from its signed bundle and keep SDK-backed testing on beta.6.
`@adcp/sdk` 17.0.0-beta.29 and Python `adcp` 10.0.0b20 bundle `3.3.0-rc.0`. Each negotiates only its own prerelease, so a buyer on rc.0 and a seller on beta.6 settle on a stable release.

```bash
npm install @adcp/sdk@17.0.0-beta.28
node -p "require('@adcp/sdk').ADCP_VERSION" # 3.3.0-beta.6
npm install @adcp/sdk@17.0.0-beta.29
node -p "require('@adcp/sdk').ADCP_VERSION" # 3.3.0-rc.0
```

This `@adcp/sdk` prerelease negotiates only the `3.3-beta.6` preview. A peer still on `3.3-beta.5` settles on a shared stable release instead, so upgrade both sides together to keep exercising 3.3 preview features.
This `@adcp/sdk` prerelease negotiates only the `3.3-rc.0` preview. A peer still on `3.3-beta.6` settles on a shared stable release instead, so upgrade both sides together to keep exercising 3.3 preview features.

SDK 17 is a major release. Before upgrading from 16, read the [16 to 17 migration guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-16-to-17.md). It changes the HTML-markup legacy formats (`display_html`, `display_WxH_html`) from `html5` to `display_tag` with inline-markup delivery ([#8339](https://github.com/adcontextprotocol/adcp/issues/8339)). It also fails closed on unresolved account references on 3.3 routes. A 3.3 seller must advertise the exact beta it serves in `supported_versions` before an SDK 17 buyer sends that pin.

Expand Down
4 changes: 2 additions & 2 deletions docs/contributing/creative33-sandbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ description: "Exercise AdCP 3.3 beta creative workflows with the published SDK,
# Creative 3.3 beta sandbox

This development lab serves the frozen AdCP `3.3.0-beta.1` contract using the
published TypeScript SDK `17.0.0-beta.28`. The server registers the retained
beta.1 schemas; SDK 17 beta.28's bundled preview is beta.6, so a client validating this
published TypeScript SDK `17.0.0-beta.29`. The server registers the retained
beta.1 schemas; SDK 17 beta.29's bundled preview is rc.0, so a client validating this
frozen lab needs the matching beta.1 schema root. Its MCP endpoint is:

`https://test-agent.adcontextprotocol.org/beta/3.3/creative/mcp`
Expand Down
2 changes: 1 addition & 1 deletion docs/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ 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.6"` exactly. See [Try the preview on the public test agent](/docs/reference/3-3-beta#try-the-preview-on-the-public-test-agent).
The test agent serves AdCP 3.2, 3.1, and 3.0. It also serves the 3.3 release candidate as an experimental preview, but only to requests that pin `adcp_version: "3.3-rc.0"` 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).

Expand Down
20 changes: 11 additions & 9 deletions docs/reference/3-3-beta.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ GA follows the first release candidate that meets every one of the GA criteria i

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), and the [closed-schema triage](#closed-schema-triage-before-rc-0) removes further beta fields before rc.0.

`@adcp/sdk` 17.0.0-beta.18 through 17.0.0-beta.20 and Python `adcp` 10.0.0b12 support beta.4. `@adcp/sdk` 17.0.0-beta.21 through 17.0.0-beta.23 and Python `adcp` 10.0.0b13 through 10.0.0b16 support beta.5. `@adcp/sdk` 17.0.0-beta.24 and later and Python `adcp` 10.0.0b17 and later support beta.6. No published SDK supports rc.0 yet: rc.0 is SDK-backed once new SDK prereleases bundle it ([SDK guidance](#sdk-guidance)).
`@adcp/sdk` 17.0.0-beta.18 through 17.0.0-beta.20 and Python `adcp` 10.0.0b12 support beta.4. `@adcp/sdk` 17.0.0-beta.21 through 17.0.0-beta.23 and Python `adcp` 10.0.0b13 through 10.0.0b16 support beta.5. `@adcp/sdk` 17.0.0-beta.24 through 17.0.0-beta.28 and Python `adcp` 10.0.0b17 through 10.0.0b19 support beta.6. `@adcp/sdk` 17.0.0-beta.29 and Python `adcp` 10.0.0b20 support rc.0, so rc.0 is SDK-backed ([SDK guidance](#sdk-guidance)).

## Know which version string to use

Expand Down Expand Up @@ -78,21 +78,21 @@ Useful tests are:

## Try the preview on the public test agent

The public test agent at `https://test-agent.adcontextprotocol.org` serves `3.3.0-beta.6` as an opt-in preview alongside its stable releases. The preview moves to rc.0 once an `@adcp/sdk` prerelease that negotiates rc.0 publishes, which is expected within days of the cut; until then, this section describes the beta.6 preview. It lists `"3.3-beta.6"` in `adcp.supported_versions` and serves the preview only to a request that pins exactly that value:
The public test agent at `https://test-agent.adcontextprotocol.org` serves `3.3.0-rc.0` as an opt-in preview alongside its stable releases. It lists `"3.3-rc.0"` in `adcp.supported_versions` and serves the preview only to a request that pins exactly that value:

| Request | Served |
|---|---|
| `adcp_version: "3.3-beta.6"` | The preview. Responses echo `"3.3-beta.6"` and validate against the published `3.3.0-beta.6` schemas. |
| `adcp_version: "3.3-rc.0"` | The preview. Responses echo `"3.3-rc.0"` and validate against the published `3.3.0-rc.0` 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-rc.0"` or the earlier preview `"3.3-beta.5"` | Never the preview. Prerelease pins match exactly. |
| Any other 3.3 prerelease, such as `"3.3-rc.1"` or the earlier preview `"3.3-beta.6"` | 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.6"}}}'
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_adcp_capabilities","arguments":{"adcp_version":"3.3-rc.0"}}}'
```

At the preview pin, `/sales/mcp` serves the experimental 3.3 surfaces the training agent implements:
Expand All @@ -106,6 +106,8 @@ At the preview pin, `/sales/mcp` serves the experimental 3.3 surfaces the traini
- the `seed_collection` controller scenario, which changes the caller's cards (a sample, a removal, a follower sweep) so the card webhooks fire;
- inventory holds ([Hold policy](/docs/media-buy/task-reference/refine_proposals#hold-policy-experimental)): `hold_policy` on products and drafts (`media_buy.hold_policy`), committed proposals with `hold_placed_at`, ranked holds with `hold_rank` (`media_buy.hold_ranking`), per-installment `holds` (`media_buy.installment_holds`), `extend_hold` (`media_buy.hold_extension`), and the `force_hold_unavailable` controller scenario.

The agent does not implement `media_buy.installment_refinement` or `media_buy.installment_creative_assignment`. It refuses `installment_refs` on any assignment operation with `UNSUPPORTED_FEATURE` ([#8986](https://github.com/adcontextprotocol/adcp/pull/8986)), as a seller without the feature must. `creative.assignment_operations` lists `assign`, `unassign`, and `replace` on `/sales` and `/mcp`; the creative-only routes list none and refuse every operation ([#8997](https://github.com/adcontextprotocol/adcp/pull/8997)).

At the same pin, `/brand/mcp` returns `collections` on `get_brand_identity` for the creators (`brand.collection_links`).

Holds are kept per caller and timed by the caller's sandbox clock, so two accounts that hold the same slot are queued at positions 1 and 2. These products carry hold policies:
Expand All @@ -122,7 +124,7 @@ Other products take the default: a hold that never contends.

`tools/list` includes `request_account` and `list_collections` only when the listing is pinned to the preview (`params._meta.adcp_version`, as `@adcp/sdk` sends it).

With `@adcp/sdk`, use 17.0.0-beta.24 or later, which negotiates exactly `3.3-beta.6`; with Python, use `adcp` 10.0.0b17 or later. Earlier 17.0.0 betas negotiate an older beta, so they settle on 3.2 with the test agent.
With `@adcp/sdk`, use 17.0.0-beta.29 or later, which negotiates exactly `3.3-rc.0`; with Python, use `adcp` 10.0.0b20 or later. Earlier 17.0.0 betas negotiate 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 3.3 prerelease that the current `@adcp/sdk` prerelease negotiates, so it can trail the latest published checkpoint, and it moves when the SDK does. 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.
Expand All @@ -148,11 +150,11 @@ SDK maintainers should report protocol ambiguities against the [AdCP repository]

## SDK guidance

**rc.0.** TypeScript and Python prereleases that adopt `3.3.0-rc.0` follow within days of the cut; see [Choose your SDK](/docs/building/by-layer/L4/choose-your-sdk). GA needs SDK support for the latest release candidate. Until a row there names rc.0, test rc.0 from its signed bundle and keep SDK-backed testing on beta.6.
**rc.0.** `@adcp/sdk` 17.0.0-beta.29 and Python `adcp` 10.0.0b20 bundle `3.3.0-rc.0` ([Choose your SDK](/docs/building/by-layer/L4/choose-your-sdk)). GA needs SDK support for the latest release candidate.

**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`, 17.0.0-beta.11 through 17.0.0-beta.17 bundle `3.3.0-beta.3`, 17.0.0-beta.18 through 17.0.0-beta.20 bundle `3.3.0-beta.4`, 17.0.0-beta.21 through 17.0.0-beta.23 bundle `3.3.0-beta.5`, and 17.0.0-beta.24 and later bundle `3.3.0-beta.6`. Each negotiates only its own prerelease, so a buyer and seller on different checkpoints 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.
**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`, 17.0.0-beta.11 through 17.0.0-beta.17 bundle `3.3.0-beta.3`, 17.0.0-beta.18 through 17.0.0-beta.20 bundle `3.3.0-beta.4`, 17.0.0-beta.21 through 17.0.0-beta.23 bundle `3.3.0-beta.5`, 17.0.0-beta.24 through 17.0.0-beta.28 bundle `3.3.0-beta.6`, and 17.0.0-beta.29 and later bundle `3.3.0-rc.0`. Each negotiates only its own prerelease, so a buyer and seller on different checkpoints 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.** `adcp` **10.0.0b17**, a PyPI prerelease (`pip install --pre "adcp==10.0.0b17"`), adopts the signed `3.3.0-beta.6` bundle and negotiates only `3.3-beta.6`; 10.0.0b13 through 10.0.0b16 adopt `3.3.0-beta.5`, and 10.0.0b12 adopts `3.3.0-beta.4`. 10.0.0b15 reads the `input` member of an [AdCP A2A profile](/docs/building/by-layer/L0/a2a-profile-extension) invocation, so a Python seller answers `@adcp/sdk` buyers over A2A 1.0, and it refuses `parameters` on an activated invocation. Keep production-line work on the 3.2 line: `adcp` 9.6.2 (AdCP 3.2.7) reads `input` too, and refuses only an activated invocation that carries both members.
**Python.** `adcp` **10.0.0b20**, a PyPI prerelease (`pip install --pre "adcp==10.0.0b20"`), adopts the signed `3.3.0-rc.0` bundle and negotiates only `3.3-rc.0`; 10.0.0b17 through 10.0.0b19 adopt `3.3.0-beta.6`, 10.0.0b13 through 10.0.0b16 adopt `3.3.0-beta.5`, and 10.0.0b12 adopts `3.3.0-beta.4`. 10.0.0b15 reads the `input` member of an [AdCP A2A profile](/docs/building/by-layer/L0/a2a-profile-extension) invocation, so a Python seller answers `@adcp/sdk` buyers over A2A 1.0, and it refuses `parameters` on an activated invocation. Keep production-line work on the 3.2 line: `adcp` 9.6.2 (AdCP 3.2.7) reads `input` too, and refuses only an activated invocation that carries both members.

**Go and Java.** Neither supports 3.3. No Go or Java release bundles a 3.3 prerelease, so test 3.3 from those languages through raw-wire calls against the signed bundle, and check the [adcp-go releases](https://github.com/adcontextprotocol/adcp-go/releases) for any later support statement.

Expand Down
Loading
Loading