fix(spec): Clarify versioning strategy and client responsibilities in protocol specification

[darrelmiller]

Fixes #1258

High level summary of changes:

• protocolVersion in AgentCard is now an array called protocolVersions
• Servers are expected to return UnsupportedVersionError if they get a request with an A2A-Version header higher than they support.
• Clients are expected to fallback to a supported version if that is acceptable to them. Tooling should help here.
• Not every minor version needs to be enumerated in the protocolVersions array. 2.2 infers support for 2.1 and 2.0.

[gemini-code-assist]

Summary of Changes

Hello @darrelmiller, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines the A2A protocol specification by providing a more detailed and structured explanation of its versioning strategy. It clearly delineates the responsibilities of clients and servers regarding protocol version negotiation, error handling, and introduces guidance for client fallback mechanisms and tooling support to enhance compatibility and robustness across different protocol versions.

Highlights

• Versioning Strategy Clarification: The specification now explicitly clarifies that patch version numbers should not be used in requests, responses, or Agent Cards, and should not be considered during protocol version negotiation.
• Structured Responsibilities: The versioning section has been reorganized into distinct sub-sections: Client Responsibilities, Server Responsibilities, Client Fallback, and Tooling Support, providing a clearer delineation of roles.
• Client Guidance: Detailed recommendations for clients on sending the A2A-Version header and handling VersionNotSupportedError have been added, including options for retrying with earlier versions.
• Server Requirements: Specific requirements for agents (servers) on processing requests with a supported A2A-Version and returning VersionNotSupportedError for unsupported versions are now defined.
• Tooling Support Recommendations: New guidance for tooling libraries and SDKs is included, suggesting mechanisms to help clients manage protocol versioning, such as automatic fallback configuration.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly clarifies the A2A protocol's versioning strategy by restructuring the documentation and adding explicit responsibilities for clients and servers, as well as guidance on client fallback and tooling support. The changes are a great improvement to the specification. I've added a couple of minor suggestions to further improve the clarity of the wording in the new sections.

[darrelmiller]

/vote

[git-vote]

DEPRECATED
#1259 (comment) has the vote

Vote created

@darrelmiller has called for a vote on fix(spec): Clarify versioning strategy and client responsibilities in protocol specification (#1259).

The members of the following teams have binding votes:

Team
@a2aproject/a2a-tsc

Non-binding votes are also appreciated as a sign of support!

How to vote

You can cast your vote by reacting to this comment. The following reactions are supported:

In favor	Against	Abstain
👍	👎	👀

Please note that voting for multiple options is not allowed and those votes won't be counted.

The vote will be open for 7days. It will pass if at least 51% of the users with binding votes vote In favor 👍. Once it's closed, results will be published here as a new comment.

[git-vote]

Vote status

So far 25.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
2	0	0	6

Binding votes (2)

User	Vote	Timestamp
geneknit	In favor	2025-12-02 17:59:14.0 +00:00:00
muscariello	In favor	2025-12-02 7:40:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 25.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
2	0	0	6

Binding votes (2)

User	Vote	Timestamp
geneknit	In favor	2025-12-02 17:59:14.0 +00:00:00
muscariello	In favor	2025-12-02 7:40:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 25.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
2	0	0	6

Binding votes (2)

User	Vote	Timestamp
geneknit	In favor	2025-12-02 17:59:14.0 +00:00:00
muscariello	In favor	2025-12-02 7:40:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 25.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
2	0	0	6

Binding votes (2)

User	Vote	Timestamp
geneknit	In favor	2025-12-02 17:59:14.0 +00:00:00
muscariello	In favor	2025-12-02 7:40:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 25.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
2	0	0	6

Binding votes (2)

User	Vote	Timestamp
geneknit	In favor	2025-12-02 17:59:14.0 +00:00:00
muscariello	In favor	2025-12-02 7:40:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 25.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
2	0	0	6

Binding votes (2)

User	Vote	Timestamp
geneknit	In favor	2025-12-02 17:59:14.0 +00:00:00
muscariello	In favor	2025-12-02 7:40:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote closed

The vote did not pass.

25.00% of the users with binding vote were in favor and 0.00% were against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
2	0	0	6

Binding votes (2)

User	Vote	Timestamp
@geneknit	In favor	2025-12-02 17:59:14.0 +00:00:00
@muscariello	In favor	2025-12-02 7:40:23.0 +00:00:00

[amye]

/vote

[git-vote]

Vote created

@amye has called for a vote on fix(spec): Clarify versioning strategy and client responsibilities in protocol specification (#1259).

The members of the following teams have binding votes:

Team
@a2aproject/a2a-tsc

Non-binding votes are also appreciated as a sign of support!

How to vote

You can cast your vote by reacting to this comment. The following reactions are supported:

In favor	Against	Abstain
👍	👎	👀

Please note that voting for multiple options is not allowed and those votes won't be counted.

The vote will be open for 11months 29days 3h 50m 24s. It will pass if at least 51% of the users with binding votes vote In favor 👍. Once it's closed, results will be published here as a new comment.

[git-vote]

Vote status

So far 25.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
2	0	0	6

Binding votes (2)

User	Vote	Timestamp
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 25.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
2	0	0	6

Binding votes (2)

User	Vote	Timestamp
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 37.50% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
3	0	0	5

Binding votes (3)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 37.50% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
3	0	0	5

Binding votes (3)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 37.50% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
3	0	0	5

Binding votes (3)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@darrelmiller	Pending
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

[Tehsmash]

Patch version numbers SHOULD NOT be used in requests, responses and Agent Cards, and MUST not be considered when clients and servers negotiate protocol versions.

From a security perspective it could be useful for a client to know the exact patch version the server is running assuming that we use patch versions to include that kind of bug fix in the spec.

So perhaps:

Patch version numbers SHOULD NOT be used in requests and Agent Cards, and MUST not be considered when clients and servers negotiate protocol versions. Responses should include the complete negotiated version number providing clients information about the exact protocol version running on the Agent side.

Actually as a separate issue I don't want to derail this PR, this makes me wonder whether we should allow clients to specify a minimum patch version requirement to ensure they can say something like >=1.0.4 (where 1.0.4 contains a security fix).

[darrelmiller]

In previous discussions on this topic, we had said that SDKs would leverage the patch version to identify updates to the SDK. e.g. Python SDK might be at 1.0.34 and .NET at 1.0.11 and they both support the 1.0 protocol.
If we allow using the specification version to indicate security fixes, then it is going to get confusing to say Python SDK 1.0.35 includes Specification 1.0.1 security fix. I would guess most security fixes are going to be in the SDK rather than the specification, and if there is a security bug in the specification that needs closing, then I'm fine with us using a minor version for that.

[Tehsmash]

Does that mean that the spec should have no patch versions for any reason?

I'm not 100% sure keeping the SDK's version in sync with the spec's version is a good idea. In python for example the ecosystem uses semantic versioning pretty heavily to indicate bug fixes only, compatible and incompatible changes. Many people will pin to a Major.Minor but allow for patch releases through ~ operator in requirements. Using patch number for all releases breaks that assumption and also will prevent SDKs from making breaking API changes without a major spec release happening at the same time.

Also if SDKs start to support multiple versions of the spec so that clients can talk to agents on different versions, having the SDK version in sync with the spec adds to the confusion. i.e. Python SDK 1.0.34 supports 1.0 and 0.3 but Python SDK 2.0.3 supports 2.0 and 1.0 but not 0.3.

[Tehsmash]

As discussed in the TSC call, patch releases for the spec repo should only be for non-functional changes to the spec text / comments in the proto etc. As soon as functional changes to the a2a.proto are made this requires a minor release. Do we need to put this in the spec somewhere?

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

Non-binding votes (1)

User	Vote	Timestamp
Tehsmash	In favor	2026-01-05 13:18:59.0 +00:00:00

[git-vote]

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
ToddSegal	In favor	2025-12-22 20:03:30.0 +00:00:00
darrelmiller	In favor	2025-12-24 22:22:43.0 +00:00:00
geneknit	In favor	2025-12-10 17:23:04.0 +00:00:00
muscariello	In favor	2025-12-11 9:41:23.0 +00:00:00
@lerhaupt	Pending
@hughesthe1st	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

Non-binding votes (1)

User	Vote	Timestamp
Tehsmash	In favor	2026-01-05 13:18:59.0 +00:00:00