Spec: formalize the AdCP-over-A2A wire binding

[bokelley]

Context

AdCP 3.0 defines the transport-neutral envelope (`protocol-envelope.json`), request/response schemas per tool, and the `task_id` / `status: 'submitted'` pattern for async work. It does not define how an AdCP agent is exposed over A2A JSON-RPC specifically — only over MCP.

As A2A-native buyer agents emerge (Google's agent-to-agent tooling, Scope3 harnesses, others), AdCP sellers implementing both transports will diverge on three decisions that the spec doesn't pin:

1. How does a Message address a skill? A2A's `Message` carries free-form `parts[]`. AdCP tools need a routing discriminant. There is no de-facto convention across implementations.
2. Where does `task_id` live when an AdCP handler returns a Submitted arm over A2A? The AdCP payload has a `task_id` field. A2A also has its own `Task.id` generated by the server. Are they the same? Does the AdCP handle ride inside the DataPart `data`, inside `artifact.metadata`, or somewhere else?
3. What `Task.state` does the adapter emit when the AdCP work is async-pending? A2A 0.3.0 treats `submitted` as the INITIAL lifecycle state before `working`, not a terminal state. Emitting `state: 'submitted'` with `final: true` on a synchronous `message/send` that acknowledges a queued AdCP task is non-conformant per A2A's lifecycle, but it's the obvious-looking mapping.

`@adcp/client` just shipped an A2A adapter (adcontextprotocol/adcp-client#899) that made choices on all three. The choices matter: same-SDK client/server mismatch on (1) would have been a silent routing failure; wrong-choice on (3) would confuse Google's A2A tooling. Reviewers on that PR flagged that without a spec binding, other implementations will choose differently.

Proposal

Publish a normative AdCP-over-A2A binding in the spec alongside the MCP path. Proposed rules, matching what `@adcp/client`'s adapter ships:

Skill addressing

A client invokes an AdCP tool by sending a `Message` with exactly one `DataPart`:

```json
{ "kind": "data", "data": { "skill": "<tool_name>", "input": { ... } } }
```

• `skill` (required, string) matches an AdCP tool name (`get_products`, `create_media_buy`, etc.).
• `input` (required, object) carries the tool's typed AdCP request payload as defined by the existing per-tool request schemas.
• Multi-part Messages, text-only Messages, and Messages missing the `skill` field are routing errors (A2A JSON-RPC `-32602` or AdCP `VALIDATION_ERROR` inside a failed Task, per implementation).

Response mapping

Per handler-return → A2A surface:

AdCP return	A2A `Task.state`	Artifact
Success arm	`completed`	`DataPart` with the typed AdCP response
Submitted arm (`status: 'submitted'`)	`completed`	`DataPart` with the AdCP response; `artifact.metadata.adcp_task_id` = the AdCP-level `task_id`
Error arm (`errors[]`)	`failed`	`DataPart` with the Error arm payload
Framework error (`adcp_error`)	`failed`	`DataPart` with `adcp_error`

Rationale for Submitted → `completed`

A2A `Task.state` tracks the transport call lifecycle (did the JSON-RPC request complete?). AdCP `status` inside the artifact tracks the work (submitted / completed / failed). A Submitted AdCP arm on a synchronous `message/send` means the transport call finished; the ad-tech work is queued. Buyers resume the AdCP work via `artifact.metadata.adcp_task_id`. This keeps the A2A Task lifecycle clean and lets the two state machines compose without conflict.

Rationale for `artifact.metadata` (not `data`)

`artifact.data` should validate against the AdCP tool's response schema. Injecting transport-level metadata (`adcp_task_id`) into `data` pollutes that surface. `Artifact.metadata` is A2A 0.3.0's spec-sanctioned extension channel. Keeping the two clean means storyboards can `model_validate` the artifact payload against AdCP schemas without special-casing transport fields.

Adoption path

• Draft the binding as a new section under `schemas/cache//protocols/` (or as a sibling doc).
• Reference it from each protocol's existing bindings doc (currently MCP-implicit).
• Call out the `Task.state` lifecycle rationale explicitly so adapter authors don't re-derive it.

References

• feat(server): A2A transport adapter (preview) peer to MCP serve() adcp-client#899 — the A2A adapter that ships these choices in `@adcp/client`
• A2A 0.3.0 lifecycle — `submitted` as initial-only
• AdCP `protocol-envelope.json` — defines `status` / `task_id` / the transport-neutral AdCP envelope

Happy to iterate on the exact mapping language; the three decisions above are the axes that need pinning.

[bokelley]

Triage

Classification: Feature request / spec addition
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Decision 2 (Submitted → completed) is a blocker — conflicts with the shipped extraction algorithm (a2a-response-extraction.mdx) that maps submitted to TaskStatusUpdateEvent; if corrected, the artifact.metadata placement in Decision 3 evaporates. Decision 1's input vs parameters naming diverges from the existing guide; strict single-DataPart conflicts with hybrid-message examples already deployed.
• adtech-product-expert: The strict single-DataPart routing rule is a blocker — a2a-guide.mdx actively recommends hybrid messages (text intent + data skill); mandating a routing error breaks every shipped hybrid example. State-machine separation in Decision 2 is sound; resumption contract for buyers (SSE vs. polling vs. push) is absent.

My take: Both experts flagged the same two independent blockers. The binding doc is the right move and the timing is good — but these two decisions need resolution before going normative.

@bokelley, your call on two axes:

---

Axis 1 — Routing strictness

Option A (relax — recommended): DataPart containing skill is authoritative; additional parts are advisory context.

{
  "parts": [
    { "kind": "text", "text": "Find sports inventory for Q3" },
    { "kind": "data", "data": { "skill": "get_products", "input": { "...": "..." } } }
  ]
}

Zero migration cost; harmonizes with a2a-guide.mdx hybrid examples.

Option B (strict, as proposed): exactly one DataPart total, multi-part → -32602. Requires deprecating hybrid message examples in the guide first.

---

Axis 2 — Submitted arm lifecycle

Option A (align with existing extraction algorithm):

- Task { state: "completed", artifacts: [{ metadata: { adcp_task_id: "..." } }] }
+ TaskStatusUpdateEvent {
+   status: { state: "submitted",
+     message: { parts: [{ kind: "data",
+       data: { task_id: "...", status: "submitted" } }] } } }

Harmonizes with a2a-response-extraction.mdx; no artifact.metadata needed.

Option B (keep completed, as proposed — matches @adcp/client today):

{ "state": "completed",
  "artifacts": [{ "data": { "...adcp_response...": "..." },
                  "metadata": { "adcp_task_id": "<task_id>" } }] }

Requires updating the extraction doc to deprecate the TaskStatusUpdateEvent path, and adding a normative resumption clause (SSE / push / polling) to the binding doc.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01LDpzDT3vG9YrCioSDWCgkH

---

Generated by Claude Code