A2A-Version header

A2A-Version is the HTTP request header, and in gRPC the a2a-version metadata key, in which an A2A client states the protocol version it is using so the agent applies that version’s rules.

Format. The value is Major.Minor, such as 1.0 or 0.3. Patch numbers do not affect compatibility, must not be used in version negotiation, and should not appear in requests or Agent Cards. That is why the v1.0.1 specification release still uses 1.0.

Client rules. Section 3.6.1 says clients must send the header on every request, so that an agent’s later upgrade does not silently change behaviour. The one exception is v0.3 clients, which predate the header. A client may instead pass the version as a query parameter, for example GET /tasks/task-123?A2A-Version=1.0.

Server rules. The agent must process the request with the semantics of the requested version and must treat a missing or empty value as 0.3. If the version is not supported on that interface, it returns VersionNotSupportedError: JSON-RPC -32009, HTTP 400, or gRPC FAILED_PRECONDITION. An agent can serve several versions by listing one supportedInterfaces entry per protocolVersion, on the same URL or on different ones. Section 3.6.3 asks SDKs to help clients manage versions, and advises clients that need newer features to request a specific version and avoid automatic fallback to an older one.

A live example. A SendMessage request sent on 26 September 2026 to Emissar’s public agent at https://emissar.ai/a2a/v1, with the header A2A-Version: 0.5, returned HTTP 200 and this JSON-RPC error, formatted for reading:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32009,
    "message": "Protocol version 0.5 is not supported. Supported: 1.0, 0.3",
    "data": [
      {"@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "VERSION_NOT_SUPPORTED", "domain": "a2a-protocol.org"}
    ]
  }
}

The data array follows section 9.5, which puts error details in google.rpc objects keyed by @type.

Neighbouring terms. A2A-Extensions is the other standard service parameter. The protocolVersion in each supportedInterfaces entry tells clients which values to send.