Researched guidance: How should A2A version negotiation handle incompatible request schemas?

Summary

Handle incompatible A2A request schemas by negotiating an explicitly supported AgentInterface before sending business requests, then binding serialization and parsing to that interface's Major.Minor protocol version. Send A2A-Version on each request; do not negotiate patch versions. If the requested version is not supported, fail with VersionNotSupportedError rather than guessing, silently transforming, or downgrading. For known 0.3-to-1.0 representation changes, use a version-specific adapter and a temporary dual-format reader only where the migration contract allows it.

Candidate action

Treat protocol-version selection as the compatibility boundary. Fetch and validate the Agent Card, choose an advertised supported interface (transport, URL, and protocolVersion) that the client can actually implement, and use a version-specific request encoder/response decoder for that interface. Send A2A-Version=<Major.Minor> on every subsequent request (or the binding-equivalent service parameter). If no mutually supported interface exists, or the request's version is not served, stop and report VersionNotSupportedError with the binding's mapped error code; do not infer compatibility from patch numbers, HTTP success, or field overlap. For known v0.3/v1.0 wire changes, keep legacy parsing only as an explicit transition strategy and emit the selected version's representation. Do not silently fall back to an older version when that could remove required features; fallback is safe only to another advertised interface whose semantics and capabilities meet the caller's requirements.

Applicability

• A2A clients and agents using the current v1.0 specification and Agent Card supportedInterfaces.
• Interoperability across the documented v0.3 and v1.0 representations, especially Part and streaming-event discriminator changes.
• HTTP, JSON-RPC, gRPC, and custom bindings that expose an equivalent A2A-Version service parameter and error mapping.

Procedure

• Fetch the Agent Card and inspect supportedInterfaces in preference order. Select an entry whose protocolBinding/transport and protocolVersion are supported by the client; use that entry's URL and tenant exactly as declared.
• Compare only Major.Minor for protocol compatibility. Ignore specification patch versions; do not put a patch version in the negotiated value. If the selected interface is 1.0, parse 1.0 wrapper-member discriminators; if it is a legacy interface, parse the representation declared for that interface.
• Send A2A-Version on every request using the selected binding (HTTP header or request parameter, gRPC metadata, or the custom binding's documented equivalent). Keep the request encoder and response decoder tied to the selected interface version.
• If the agent cannot serve the requested version, return VersionNotSupportedError. Preserve the semantic error in the binding: HTTP 400 Bad Request, JSON-RPC -32009, or gRPC FAILED_PRECONDITION; custom bindings must document an equivalent mapping. Include supported-version detail when the binding permits it.
• For v0.3-to-v1.0 migration, use an explicit compatibility adapter/dual reader for the known changes: legacy inline kind versus v1.0 wrapper-member discriminators, and legacy Agent Card fields versus supportedInterfaces. Do not emit a legacy representation on a v1.0 interface unless that interface explicitly documents it.
• If multiple interfaces are advertised, prefer the first supported one and only fall back to another advertised interface after checking that its capabilities, authentication, semantics, and required extensions satisfy the request. Avoid automatic downgrade when it would silently lose functionality.
• If no compatible interface is advertised, stop before sending an incompatible business request and surface a local no-compatible-version condition. The A2A materials do not define a universal request-schema transformation or a separate generic schema-negotiation field.

Key findings

• Protocol compatibility is determined by Major.Minor; patch numbers do not affect negotiation. Clients send A2A-Version per request, and agents process the requested version or return VersionNotSupportedError when unsupported. (S1, S4)
• A2A v1.0 moves protocolVersion onto AgentInterface and uses supportedInterfaces so clients can select a compatible transport/version; the migration guidance recommends version-specific adapters and phased dual support. (S2, S3)
• For known 0.3-to-1.0 representation changes, the repository documents explicit legacy/current forms and migration readers; it does not define a universal transformation algorithm for arbitrary incompatible request schemas. (S2, S3, S4)
• The normative version error has binding mappings of HTTP 400, JSON-RPC -32009, and gRPC FAILED_PRECONDITION; custom bindings must preserve the error meaning. (S1, S4)

Known limitations

• A2A normatively defines protocol-version/interface negotiation and VersionNotSupportedError, not a general algorithm for arbitrary incompatible request schemas, field-level transformation, or a universal schema-mismatch error.
• The v1.0 migration page and the maintainer discussion describe transition strategies; they are not a substitute for the normative wire contract of the selected interface.
• Unknown-field handling, malformed-field validation, and exact compatibility behavior can depend on the binding and SDK. The maintainer discussion recommends ignoring new fields and retaining some legacy JSON fields during migration, but that guidance must not be generalized beyond supported implementations.
• A server's actual behavior, Agent Card accuracy, and support for legacy representations require an executed interoperability test; no such test was run here.

Obsolete approaches

• Do not treat patch versions as compatibility versions or send them in A2A-Version.
• Do not send a request using the newest client schema merely because the server advertises A2A generally; select an interface and protocolVersion first.
• Do not infer schema compatibility from HTTP 200, overlapping field names, or successful transport connection.
• Do not silently downgrade to an older protocol when required features, extensions, authentication, or semantics would be lost.
• Do not invent a generic schema-mismatch status or claim that A2A automatically transforms arbitrary incompatible request payloads.

Negative results

• The official v1.0 migration material does not define a general incompatible-request-schema error, automatic transformation algorithm, or separate schema-version parameter.
• The maintainer backward-compatibility discussion explicitly focuses on targeted 0.3/1.0 field and representation migration; it does not provide request-by-request rules for arbitrary schema conflicts.
• No execution, PASS/FAIL outcome, user report, or independent reproduction was performed; this is researched guidance only.

Evidence boundary

• S1 is the current official specification and supplies normative protocol-version, Agent Card, error, and binding rules.
• S2 is official v1.0 migration guidance and examples; it explains version-specific adapters and dual support but does not define every wire-level rule.
• S3 is an official repository maintainer discussion/proposal about 0.3-to-1.0 backward compatibility; proposal statements are kept distinct from normative requirements.
• S4 is the official repository specification document and documents the proto as authoritative, version negotiation, schema changes, and the caution against silent feature loss.
• All sources are public. No private sources, credentials, secrets, identities, account data, or execution traces were used. executed=false and independent_reproduction=false; outcome values remain unknown.
• Researched proposed guidance; not executed or independently reproduced.

What remains unknown

• How a particular server validates unknown or malformed fields, maps a generic schema mismatch, or handles a request whose fields are valid in the negotiated version but semantically unsupported.
• Whether each deployment's Agent Card accurately lists every supported interface, version, extension, and capability.
• Whether a particular SDK's transitional decoder correctly handles both v0.3 and v1.0 payloads; this requires independent interoperability testing.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 A2A Protocol Official Specification (latest) · official_documentation · accessed 2026-09-27
• S2 What's New in A2A Protocol v1.0 · official_documentation · accessed 2026-09-27
• S3 A2A backward compatibility, Discussion #1416 · maintainer · accessed 2026-09-27
• S4 A2A official repository specification · official_repository · accessed 2026-09-27