# Migrate A2A v0.3 to v1.0: An Ordered Checklist for Clients and Servers

> An ordered checklist for moving an A2A client or server from v0.3 to v1.0: the A2A-Version header rule, method names, Part shape, a runnable grep check, and symptom-to-cause pointers.

Guide: A2A in practice: agent-to-agent interoperability — part 9
Published: 2026-11-07 · Updated: 2026-11-07 · 1070 words · ~1423 tokens (estimate)
Canonical: https://changegamer.ai/articles/a2a-v0-3-to-v1-0-migration
JSON: https://changegamer.ai/api/articles/a2a-v0-3-to-v1-0-migration.json
Access: free — editorial guide, not part of the licensed corpus
Pillar: https://changegamer.ai/articles/a2a-protocol-in-practice.md

## In short

- Migrating A2A from v0.3 to v1.0 means setting an explicit A2A-Version header, replacing message/send style method names with the PascalCase spellings the spec main branch lists, and rewriting every Part to the member-name shape that has no kind field.
- An A2A client that sends an empty A2A-Version header gets v0.3 semantics, because the specification says an empty value is interpreted as 0.3, so a v1.0 client must always send 1.0 explicitly.
- A2A version negotiation uses Major.Minor only: patch releases such as v1.0.1 are not negotiated, and a server answers an unsupported version with VersionNotSupportedError.
- The A2A v1.0 Part shape is breaking for v0.3 clients, because parts are discriminated by member name such as {"text": "..."} instead of an explicit kind field.
- As of the 27 October 2026 update of the ChangeGamer A2A reference, it records no official migration guide or deprecation timeline for v0.3, so any sunset date quoted elsewhere should be checked against the project itself.

---

Migrating A2A from v0.3 to v1.0 is a short ordered checklist: pin the version header, rename the methods, reshape the parts, then verify states and errors. This article is the walkthrough that [the A2A protocol in practice pillar](/articles/a2a-protocol-in-practice) promises; it links to the pillar's comparison table and does not reprint it. The contract lives in [the A2A protocol reference](/resources/a2a-protocol) (updated 27 October 2026).

Dated facts, per the project's releases page: v0.3.0 shipped on 30 July 2025, v1.0.0 on 12 March 2026, and v1.0.1 on 28 May 2026 as a bug-fix patch that prefers `application/a2a+json` in the HTTP binding. As of the reference's 27 October 2026 update it records no official migration guide, deprecation notice or sunset date for v0.3, so none is claimed here.

## What do you have to change between A2A v0.3 and v1.0?

Four code changes matter, and one is breaking by the reference's own wording; the pillar holds the full comparison table, so this list only names what you edit.

- **Method names.** The v0.3 era used `message/send` and `message/stream`; the spec main branch at fetch time lists PascalCase names such as `SendMessage` and `SendStreamingMessage`. The reference does not say those spellings date from v1.0.0, so confirm them against the version you target.
- **Parts.** Drop the explicit `kind` field and use the member name, for example `{"text": "..."}`. The reference calls this breaking for v0.3 clients.
- **Version signal.** Add the `A2A-Version` header, covered below.
- **New operation.** List Tasks arrived in v1.0.0; adopt it only if you need task listing.

Two items are one-liners. The card path moved from `agent.json` to `/.well-known/agent-card.json` in v0.3.0, so it is not a v1.0 step; see [designing an Agent Card](/articles/a2a-agent-card-design). The task-state spelling is `canceled` with one L; [task states and operations](/articles/a2a-task-lifecycle) covers the handlers.

## In what order should you migrate an A2A client and server?

Upgrade the server first, then the clients, and keep a v0.3 path only while a real caller needs it. That order is inference: the reference gives no upgrade sequence, and nothing in it confirms a v1.0 server accepts v0.3 calls.

1. **Inventory callers.** List every client that calls the server and the version each sends. Without that list you cannot decide when v0.3 can go.
2. **Run the grep check below** on client and server source to find v0.3 leftovers.
3. **Upgrade the server** to serve v1.0 method names and the member-name Part shape, and decide what it does for each requested version.
4. **Upgrade clients** to send an explicit `A2A-Version: 1.0`, the new method names and the new Part shape.
5. **Re-test states and errors** against v1.0, including the `TASK_STATE_*` strings.
6. **Remove the v0.3 branch** once the inventory shows no caller on it.

On auth, the reference records that v1.0.0 modernised the OAuth 2.0 flows (device code, PKCE); it lists no other auth changes, and [the authentication schemes article](/articles/a2a-authentication-schemes) covers choosing among them.

## What is the A2A-Version header rule?

The rules (Major.Minor only, patch not negotiated, empty value read as `0.3`, `VersionNotSupportedError` for unsupported values) are stated in the pillar and the reference. The operational consequence: never let a client default the header to an empty string, and send `1.0` on every call.

```bash
# Send an explicit version on every call. Replace the URL with your agent's endpoint.
curl -sS https://agent.example.com/message:send \
  -H 'A2A-Version: 1.0' \
  -H 'Content-Type: application/a2a+json' \
  -d @request.json
```

The endpoint is a placeholder, and `request.json` is your own message body: build it from the specification, with each part in the member-name shape such as `{"text": "..."}`, because the reference does not record the full message schema. The HTTP+JSON binding uses `application/a2a+json` bodies; [the bindings article](/articles/a2a-bindings-json-rpc-grpc-rest) compares the three bindings.

## How do you find v0.3 leftovers in your code?

Grep your source for the v0.3-era method names and for the `kind` discriminator on parts. This is a first pass, designed by inference from the changes in the table above.

```bash
# v0.3-era JSON-RPC spellings
grep -rnE "message/(send|stream)['"]" src/ || echo "no v0.3 method names found"
# explicit kind discriminators on parts (noisy: review each hit)
grep -rnE "kind['\"]?\s*:\s*['\"](text|file|data)['\"]" src/ || echo "no kind-based parts found"
# is the version header ever sent?
grep -rniE "A2A-Version" src/ || echo "WARNING: no A2A-Version header anywhere"
```

What it does not prove: a clean run does not show that your messages are valid v1.0, that your states and errors are handled, or that generated code and SDK defaults send the right header. It cannot see other v0.3 to v1.0 differences the reference does not list. Treat it as a smell test, then run a real call against a v1.0 agent.

## What do common A2A migration failures usually mean?

Each symptom below maps to a likely cause; the mapping is inference, derived from the rules above, not from published error logs.

| Symptom | Likely cause (inference) |
|---|---|
| `VersionNotSupportedError` on every call | Client asks for a Major.Minor the server does not serve |
| v1.0 client behaves like v0.3 | Header sent with an empty value, read as `0.3` |
| Server rejects or ignores message content | Parts still carry `kind` and not the member-name shape |
| Method not found on JSON-RPC | Client calls `message/send` against a PascalCase server, or the reverse |
| Canceled tasks never match a handler | Code compares the state with a different spelling or casing than `TASK_STATE_*` and `canceled` |

When the cause is unclear, send one call with an explicit `A2A-Version` and compare the response to the specification, not to older blog posts.

## Which A2A v0.3 to v1.0 questions stay unanswered?

The reference leaves unanswered whether v0.3 is deprecated, whether a v1.0 server will accept v0.3 requests, what changed in streaming shapes, error codes or card fields beyond the items above, or which SDK release supports which version. The reference records none of those in its 27 October 2026 update, and no adoption figures for either version are claimed here. Before you cut over, read the specification's v1.0 pages and the releases page for anything newer than the v1.0.1 patch, because the specification's main branch may be ahead of the released version, and re-run the grep check and one live call after every change. Also, the reference describes Agent Card signing as optional and does not list it as a v1.0 change, so do not assume a migration adds card verification.

## Frequently asked questions

### How do I migrate from A2A v0.3 to v1.0?

Send an explicit A2A-Version: 1.0 header from every client, switch JSON-RPC method names from message/send style to the SendMessage style spellings on the spec main branch, rewrite Part objects to the member-name shape, then re-test task states and errors against v1.0 before removing any v0.3 code path.

### What happens if an A2A client sends no version or an empty version?

An empty A2A-Version value is interpreted as 0.3, so a v1.0 client that sends an empty header gets v0.3 semantics. A server answers a version it does not support with VersionNotSupportedError, so always send an explicit Major.Minor value.

### Is A2A v1.0 backward compatible with v0.3?

A2A v1.0 is not wholly backward compatible: the reference records the Part shape change as breaking for v0.3 clients. Whether a v1.0 server accepts v0.3 calls is not stated in the reference, so test that against your own server.

### Do I need to change my Agent Card path to move to v1.0?

No. The move from agent.json to /.well-known/agent-card.json was made in v0.3.0, not v1.0, so a card already published at the agent-card.json path needs no path change for the v1.0 migration.


---

## The rest of this guide

- [The A2A Protocol in Practice: Agent Cards, Tasks, Auth and When You Need It](https://changegamer.ai/articles/a2a-protocol-in-practice.md): A practical guide to the A2A (Agent2Agent) protocol: what it standardizes, when it beats in-process subagents, how Agent Cards, task states, bindings and authentication work, how credentials cross agent hops, and how to launch it.
- [Do You Need A2A for a Multi-Agent System? A Decision Rule](https://changegamer.ai/articles/do-you-need-a2a.md): A decision rule for choosing between in-process subagents and the A2A protocol: start with one agent, add more only for a named failure, and cross the network with A2A only when a remote party, framework or trust boundary demands it.
- [Designing an Agent Card: What Goes in the Public Card and What Waits](https://changegamer.ai/articles/a2a-agent-card-design.md): How to design an A2A Agent Card: the field groups, the well-known path, optional signing, and a rule for splitting what the public card advertises from what an authenticated client fetches in the extended card.
- [A2A Task States and Operations: What Each State Means for an Orchestrator](https://changegamer.ai/articles/a2a-task-lifecycle.md): The eight A2A task states, the eleven operations that act on tasks, the difference between interrupted and terminal states, and an inference-labelled handler matrix for an orchestrator.
- [A2A JSON-RPC vs gRPC vs REST: What Differs Between the Three Bindings](https://changegamer.ai/articles/a2a-bindings-json-rpc-grpc-rest.md): The three A2A protocol bindings (JSON-RPC, gRPC, HTTP+JSON/REST): what the specification keeps identical, what differs on the wire, and an inference-labelled guide to picking one.
- [A2A Authentication Schemes: Which to Declare in Your Agent Card](https://changegamer.ai/articles/a2a-authentication-schemes.md): The five security scheme families an A2A Agent Card can declare (API key, HTTP auth, OAuth 2.0, OpenID Connect, mutual TLS), an inference-labelled rule for choosing one, and how a client handles auth-required tasks.
- [Credential Propagation Across Agent Hops: Exchange, Audience and Depth](https://changegamer.ai/articles/credential-propagation-across-agent-hops.md): How to carry authority through a chain of delegating agents: why forwarding a token fails, per-hop RFC 8693 exchange with act and may_act, RFC 8707 audience binding, a worked sequence and a failure walk-through.
- [How to Verify a Remote A2A Agent Before Delegating](https://changegamer.ai/articles/trusting-a-remote-agent.md): What a signed Agent Card proves and does not, how domain, key and ERC-8004 identity differ, where Web Bot Auth fits, and why card text and returned artifacts are untrusted input, ending in an ordered checklist.
- [How Do Agents Discover A2A Agents Without a Standard Registry?](https://changegamer.ai/articles/a2a-agent-discovery-without-a-registry.md): The three discovery strategies in the A2A documentation, why the spec prescribes no registry API, what vendor registries fill the gap, and how to choose between a well-known URI, a registry and direct configuration.
- [Does Your Agent Framework Really Support A2A? How to Read the Claim and What to Test](https://changegamer.ai/articles/agent-frameworks-with-a2a-support.md): Which agent frameworks list A2A support, what native, add-on, platform-gated and unrecorded mean, a short test checklist to run before you rely on it, and how that differs from the protocol's own SDKs.
- [Failed or Rejected Remote A2A Task: Retry, Degrade or Surface?](https://changegamer.ai/articles/failure-handling-across-agent-boundaries.md): How to decide what happens after a remote A2A task ends badly: the side-effects test that splits failed into retry or surface, why rejected is not a retry case, why input-required is not a failure, and a structured result for the caller.
- [A2A Production Launch Checklist: Gates to Pass Before You Ship](https://changegamer.ai/articles/a2a-production-launch-checklist.md): A go/no-go checklist for launching A2A agent-to-agent delegation, one line per gate, each pointing to the article that owns the detail: need, card, states, binding, auth, trust, versioning, failure.

## Reference resources

- https://changegamer.ai/resources/a2a-protocol.md

All guides: https://changegamer.ai/api/articles.json · Reference corpus: https://changegamer.ai/llms.txt
Licensing: https://changegamer.ai/api/pricing.json (offer catalog) · https://changegamer.ai/api/payment.json (payment methods, HTTP 402 flow) · access guide: https://changegamer.ai/resources/access-and-pricing.md
