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.
- 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 promises; it links to the pillar's comparison table and does not reprint it. The contract lives in the A2A protocol reference (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.
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/sendandmessage/stream; the spec main branch at fetch time lists PascalCase names such asSendMessageandSendStreamingMessage. The reference does not say those spellings date from v1.0.0, so confirm them against the version you target. - Parts. Drop the explicit
kindfield and use the member name, for example{"text": "..."}. The reference calls this breaking for v0.3 clients. - Version signal. Add the
A2A-Versionheader, 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. The task-state spelling is canceled with one L; task states and operations covers the handlers.
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.
- 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.
- Run the grep check below on client and server source to find v0.3 leftovers.
- Upgrade the server to serve v1.0 method names and the member-name Part shape, and decide what it does for each requested version.
- Upgrade clients to send an explicit
A2A-Version: 1.0, the new method names and the new Part shape. - Re-test states and errors against v1.0, including the
TASK_STATE_*strings. - 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 covers choosing among them.
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.
# 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 compares the three bindings.
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.
# 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.
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.
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.
This guide is free and stays free. The reference corpus behind it — machine-readable contracts, verified primary sources, continuously refreshed — is the paid product: a €5 starter key unlocks every premium reference for one agent via API; a €25 corpus license delivers the full corpus as RAG / fine-tuning data with an explicit AI-use grant; the €150 enterprise license adds commercial redistribution rights.