A2A Protocol Versions

Choose which version of the A2A protocol your agent card advertises. A²D supports 0.3.0, 1.0, and dual (advertise both at the same time).

Why this matters

The A2A spec changed shape between 0.3.0 and 1.0. A card that picks the wrong version will fail discovery for clients that only speak the other one. A dual card gives you a smooth migration path — old and new clients both work — without forcing you to maintain two separate endpoints.

What changed between versions

Card envelope:

• 0.3.0 cards expose url and protocolVersion as top-level fields.
• 1.0 cards wrap them in a supportedInterfaces[] array, with one entry per (url, protocolBinding, protocolVersion) triple.

Message shape on message/send / SendMessage:

• 0.3.0 uses role: "user" and parts shaped as { kind: "text", text: "..." }.
• 1.0 uses role: "ROLE_USER" and unified parts shaped as { text: "...", mediaType: "text/plain" }.
• 1.0 also renames the JSON-RPC method from message/send to SendMessage.

Result / artifact shape:

• 0.3.0 returns Task and Message results with kind discriminators.
• 1.0 returns the same logical shape with ROLE_AGENT and unified part objects.

Response envelope on SendMessage (v1.0):

• 0.3.0 returns the Task (or Message) directly as the JSON-RPC result — contextId, status, and artifacts sit at the top of result.
• 1.0 wraps it in a SendMessageResponse, a proto oneof { Task task; Message message; }. The task is nested under result.task, not returned flat. Strict protojson consumers (for example the MuleSoft Agent Broker) reject a flat task because SendMessageResponse has no top-level contextId.

// 0.3.0 — Task returned flat
{ "jsonrpc": "2.0", "id": 1, "result": { "contextId": "ctx-1", "status": { "state": "completed" }, "artifacts": [] } }
 
// 1.0 — Task nested under `task`
{ "jsonrpc": "2.0", "id": 1, "result": { "task": { "contextId": "ctx-1", "status": { "state": "TASK_STATE_COMPLETED" }, "artifacts": [] } } }

Choosing a version

0.3.0 — older clients only

Pick this when you know every consumer of your card runs on the older A2A SDK. The card is the smallest and most compatible with existing tooling.

1.0 — modern clients only

Pick this for new agents where you control the consumers. 1.0 is the spec direction going forward.

dual — advertise both

A dual card uses the 1.0-shaped envelope and lists both versions inside supportedInterfaces:

{
  "supportedInterfaces": [
    {
      "url": "https://example.com/api/platform/abc/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "0.3.0"
    },
    {
      "url": "https://example.com/api/platform/abc/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ]
}

The agent’s mock endpoint accepts either dialect on the same URL. It routes by JSON-RPC method name (message/send → v0.3.0, SendMessage → v1.0) and by the optional A2A-Version request header.

Streaming over SSE (v1.0)

A2A 1.0 support includes streaming responses over Server-Sent Events (SSE). This matters for interop with the MuleSoft Agent Broker / Agent Network 2.0, whose A2A v1.0 support both calls streaming agents and acts as a streaming endpoint.

Streaming is opt-in per card and v1.0-only — it’s available on 1.0 and dual cards, not 0.3.0.

Turning it on: open the card, click Edit, and enable the Streaming (SSE) toggle (it appears only when the protocol version is 1.0 or dual). Saving sets capabilities.streaming: true, which the card’s .well-known/agent-card.json then advertises.

Calling a streaming card: clients POST a JSON-RPC request using a streaming method — SendStreamingMessage (v1.0 style) or message/stream (JSON-RPC style). The mock responds with Content-Type: text/event-stream and emits a synthesized sequence. Each frame’s result is a v1.0 StreamResponse, a proto oneof { task, message, statusUpdate, artifactUpdate }, so the interim event nests under statusUpdate and the terminal event nests under task:

data: {"jsonrpc":"2.0","id":1,"result":{"statusUpdate":{"taskId":"task-1","contextId":"ctx-1","status":{"state":"TASK_STATE_WORKING"},"final":false}}}

data: {"jsonrpc":"2.0","id":1,"result":{"task":{"contextId":"ctx-1","status":{"state":"TASK_STATE_COMPLETED"},"artifacts":[...]}}}

The terminal task frame carries the same result your mock scenario would return unary. The interim statusUpdate frame is flagged final: false; the stream closes after the terminal task frame.

If a streaming method is sent to a card that doesn’t advertise streaming, or to a 0.3.0 card, the endpoint returns a JSON-RPC error instead of a stream.

Testing it from the Protocol Tester: after discovering a streaming-capable 1.0 (or dual, with A2A 1.0 selected) card, a Stream response (SSE) checkbox appears next to the message input. Tick it and send — the tester issues SendStreamingMessage and shows the full event sequence (working → final) in the response view. The checkbox only appears when the discovered card advertises capabilities.streaming; unticked, the tester sends the unary SendMessage.

Where to set the version

When creating a card manually

1. Open Agent Cards in the sidebar.
2. Click + New Agent Card.
3. In the Protocol version dropdown, pick 0.3.0, 1.0, or dual.
4. Fill in the rest of the card and save.

When generating with AI

1. On the Agent Cards list, click Generate with AI.
2. Set Protocol version to your target version.
3. The AI generator emits mock scenarios in the matching shape — you don’t need to convert them by hand.

When importing from a JSON spec

The importer detects the version automatically:

• Top-level url + protocolVersion → 0.3.0.
• supportedInterfaces with one entry → 1.0.
• supportedInterfaces with two entries (one per version) → dual.

You can override the detected version on the import preview before confirming.

Testing a multi-version card

Open the card’s Test tab (or the Protocol Tester from the sidebar). When the discovered card has more than one entry in supportedInterfaces, a Send messages using picker appears above the message input — toggle between A2A 0.3.0 and A2A 1.0 to send each dialect. The picker rewrites both the URL and the JSON-RPC method/role used for the next request.

For automated suite runs against a dual card, pin the dialect per test with the A2A protocol version dropdown in the Testing Framework — the runner sends the matching envelope and unwraps the response the same way for both versions.

Where the version lives in storage

The card row in agent_cards carries a protocol_version column whose value is one of 0.3.0, 1.0, or dual. The .well-known/agent-card.json endpoint reads this column and emits the right envelope on every request.

Next Steps

• Creating Agent Cards — End-to-end agent card walkthrough
• Signed Agent Cards — Add JWS signing on top of any version
• Protocol Tester — Exercise the card’s endpoints

Pick the version that matches your consumers, or use dual to migrate without breakage.