From 0.3 to 1.0

The kit's error scenario sends two requests that a 0.3 client would send today. One omits A2A-Version and gets VersionNotSupportedError. The other calls message/send and gets MethodNotFoundError. When you finish this section, you can map a 0.3 request to its 1.0 form, and turn on the 0.3 layer in the reference SDK.

POST /a2a/jsonrpc HTTP/1.1
Host: localhost:41241
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "message/send",
  …
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Before and after

The project's migration guide lists the changes, because a major breaking change must come with migration guidance in a separate document. The table keeps the changes that reach code.

{
  "protocolVersion": "0.3",
  "url": "https://agent.example.com/a2a",
  "preferredTransport": "JSONRPC",
  "supportsAuthenticatedExtendedCard": true,
  "additionalInterfaces": [...]
}

The guide misses one change. The 0.3 flag blocking was false by default, so a send returned at once. Its replacement returnImmediately is also false by default, so a send now waits. SendMessage shows both modes.

The missing header

An agent must read an empty value as version 0.3. A 1.0-only interface must then answer VersionNotSupportedError, as the kit does.

The SDKs differ. JS and Java treat a missing header as 0.3 and reject it on every binding. Python does so on JSON-RPC and REST, and Rust on JSON-RPC only. Go never reads the header, and .NET accepts a missing one. The version header has the full table.

The 0.3 layer in each SDK

During the overlap period, a server can accept both the old and the current forms of a request message.

• a2a-python 1.2.2. Pass enable_v0_3_compat=True to create_jsonrpc_routes and create_rest_routes, and add an AgentInterface with protocolVersion 0.3 to the card. The dispatcher routes by method name, so message/send reaches JSONRPC03Adapter before the version check. For gRPC it adds CompatGrpcHandler on the old package a2a.v1. The client needs no switch: ClientFactory picks a compat transport for an interface below 1.0.
• a2a-js 1.3.0. Set legacyCompat: { enabled: true } on each handler. It routes by A2A-Version, with an absent header as 0.3.
• a2a-go 2.6.0. Mount a second handler from a2acompat/a2av0 under its own URL and advertise a second interface. It routes by URL, never by header.
• a2a-java 1.4.0.Final. Add the multiversion-jsonrpc or multiversion-rest reference module. Its VersionRouter sends 0.3 or an absent header to the 0.3 handler.
• a2a-dotnet 1.0.0-preview2. Call MapA2AWithV03Compat instead of MapA2A. It routes by A2A-Version.
• a2a-rs 0.5.1. None.

Where the migration guide is wrong

The proto is normative, so follow it where the guide names a field or a value the proto lacks.

• The guide named the stream members taskStatusUpdate and taskArtifactUpdate. The proto has statusUpdate and artifactUpdate (conflict D9). PR #2056 fixed it on main after v1.0.1, not yet released.
• The guide added Task.createdAt, Task.lastModified, configId, and an artifact index that the proto lacks (conflict D10). The same PR removed all but index.
• Appendix A.2.2 calls the old flag supportsExtendedAgentCard. The guide and the SDK say supportsAuthenticatedExtendedCard (conflict D40), and main has no fix.
• The guide puts extensions at agentCard.extensions. The proto puts them at capabilities.extensions, as extensions explains.

After v1.0.1

No tag newer than v1.0.1 exists. Main has one proto change since the tag: the gRPC url comment, now hostname:port (PR #1997), which closes D34. It is the only entry in the pending 1.0.2 release (PR #2072). Documentation commits on main close D8, D9, D12, and D32, and part of D4, D5, D6, D10, and D23 (the conflict register). Main also adds §7.6.4 on in-task authorization scope (PR #2081), which security schemes quotes.

Branch dev-1.1 changes the task record. Task.generation counts every state change, and GetTaskRequest.currentGeneration lets a client wait for the next one. SendMessageConfiguration.ifGenerationMatch makes a send conditional, and a stale value gets TaskGenerationMismatchError, -32010 (PR #1810). Task.history is deprecated for a timeline of messages and statuses (PR #2129). None of this is released, and no 1.1 date is published.