feat(compat): GRPC client compatible with 0.3 server

[bartek-w]

Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Follow the CONTRIBUTING Guide.
• Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
  • Important Prefixes for release-please:
    • fix: which represents bug fixes, and correlates to a SemVer patch.
    • feat: represents a new feature, and correlates to a SemVer minor.
    • feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.
• Ensure the tests and linter pass (Run bash scripts/format.sh from the repository root to format)
• Appropriate docs were updated (if necessary)

[gemini-code-assist]

Summary of Changes

Hello, 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 significantly enhances the A2A SDK's interoperability by introducing a gRPC client capable of communicating with older v0.3 servers. It establishes a robust mechanism for version-aware transport selection and provides comprehensive integration tests to ensure seamless cross-version communication, thereby broadening the client's compatibility landscape.

Highlights

• gRPC Client Compatibility: Introduced a new gRPC client (CompatGrpcTransport) specifically designed to be compatible with A2A v0.3 servers, allowing newer SDK versions to interact with older gRPC services.
• Version-Aware Transport Selection: Implemented logic within ClientFactory to dynamically select the appropriate gRPC transport (GrpcTransport for v1.0+ or CompatGrpcTransport for v0.3) based on the protocol version advertised by the agent's card.
• v0.3 gRPC Handler: Added a backward-compatible gRPC handler (CompatGrpcHandler) to process v0.3 gRPC requests on a v1.0 server, ensuring older clients can communicate with newer servers.
• Cross-Version Integration Tests: Included a comprehensive suite of integration tests to validate compatibility between different client and server versions (v0.3 and v1.0) across gRPC, JSON-RPC, and REST protocols.
• Conversion Logic Enhancements: Updated conversion utilities (conversions.py) to correctly map request and response types between v0.3 and v1.0 protobuf definitions, particularly for task push notification configurations and stream responses.

Changelog

• .github/actions/spelling/allow.txt
  • Added 'TResponse' to the spelling allow list.
• .gitignore
  • Added '.geminiignore' to the ignore list.
• src/a2a/client/client_factory.py
  • Imported InvalidVersion and Version for version parsing.
  • Imported PROTOCOL_VERSION_0_3 and PROTOCOL_VERSION_1_0 constants.
  • Dynamically imported CompatGrpcTransport.
  • Implemented grpc_transport_producer to select between GrpcTransport and CompatGrpcTransport based on protocol version.
  • Added _find_best_interface static method to prioritize agent interfaces by protocol version.
  • Modified the create method to utilize _find_best_interface for transport selection.
• src/a2a/compat/v0_3/conversions.py
  • Updated to_core_get_task_push_notification_config_request to correctly handle push_notification_config_id.
  • Updated to_compat_get_task_push_notification_config_request to convert based on core_req.id.
  • Added extensive new test cases for various conversion scenarios, including message types, error handling, and edge cases.
• src/a2a/compat/v0_3/grpc_handler.py
  • Added CompatGrpcHandler class, implementing a backward-compatible gRPC handler for A2A v0.3 services.
  • Included methods for handling unary and streaming gRPC calls, error management, and metadata setting.
  • Implemented conversion logic for various v0.3 gRPC methods to their v1.0 core counterparts.
• src/a2a/compat/v0_3/grpc_transport.py
  • Added CompatGrpcTransport class, providing a backward-compatible gRPC client transport for A2A v0.3.
  • Implemented error mapping for gRPC exceptions and metadata handling for extensions.
  • Provided methods for sending messages, subscribing to tasks, getting/canceling tasks, and managing push notification configurations for v0.3.
• src/a2a/compat/v0_3/proto_utils.py
  • Renamed internal regex constants _TASK_NAME_MATCH and _TASK_PUSH_CONFIG_NAME_MATCH to public TASK_NAME_MATCH and TASK_PUSH_CONFIG_NAME_MATCH.
  • Updated all internal references to the renamed constants.
  • Added list_task_push_notification_config_response to the FromProto class.
• src/a2a/utils/constants.py
  • Added PROTOCOL_VERSION_0_3 constant.
• tests/client/test_client_factory_grpc.py
  • Added new test cases to verify gRPC transport selection priority in ClientFactory based on protocol versions (1.0, >1.0, <0.3, invalid, unspecified).
• tests/compat/v0_3/test_conversions.py
  • Added comprehensive test cases for GetTaskPushNotificationConfigRequest conversion.
  • Added tests for SendMessageResponse and StreamResponse conversions for various event types.
  • Included tests for OAuth flows, part data with metadata, file parts, and handling of missing/unspecified fields in conversions.
• tests/compat/v0_3/test_grpc_handler.py
  • Added new test cases for CompatGrpcHandler, covering successful message sending (task and message responses), streaming messages, task operations (get, cancel, subscribe), and push notification config management (create, get, list, delete).
  • Included tests for error handling, task ID extraction, and extension metadata.
• tests/integration/cross_version/client_server/client_0_3.py
  • Added a new integration test client script for A2A v0.3, including tests for streaming and synchronous message sending, task operations, and agent card retrieval.
• tests/integration/cross_version/client_server/client_1_0.py
  • Added a new integration test client script for A2A v1.0, including tests for streaming and synchronous message sending, task operations, and agent card retrieval.
• tests/integration/cross_version/client_server/server_0_3.py
  • Added a new integration test server script for A2A v0.3, featuring a mock agent executor and handlers for JSON-RPC, REST, and gRPC.
• tests/integration/cross_version/client_server/server_1_0.py
  • Added a new integration test server script for A2A v1.0, featuring a mock agent executor and handlers for JSON-RPC, REST, and gRPC, including the new CompatGrpcHandler.
• tests/integration/cross_version/client_server/test_client_server.py
  • Added a new pytest file to orchestrate cross-version client-server integration tests, covering various combinations of v0.3 and v1.0 clients and servers across different protocols.

Activity

• The pull request was authored by bartek-w.
• The author confirmed adherence to the CONTRIBUTING guide, including conventional commit standards.
• The author verified that all tests and linter checks passed.
• The author confirmed that relevant documentation was updated.

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 introduces backward compatibility for the gRPC client to work with v0.3 servers. It achieves this by adding a compatibility layer that includes a CompatGrpcTransport for the client and a CompatGrpcHandler for the server, along with necessary type conversions and protocol version detection in the ClientFactory. The changes are well-structured and supported by an extensive set of new unit and integration tests, which is excellent. My review found no issues that require changes based on the repository's specific rules.

_{Note: Security Review did not run due to the size of the PR.}