fix: handle REST query params as per 1.0 spec

[ishymko]

Source: 11.5. Query Parameter Naming for Request Parameters:

Field Type Handling:

• Strings: Passed directly as query parameter values
• Booleans: Represented as lowercase strings (true, false)
• Numbers: Represented as decimal strings
• Enums: Represented using their string values (e.g., status=working)
• Repeated Fields: Multiple values MAY be passed by repeating the parameter name (e.g., ?tag=value1&tag=value2) or as comma-separated values (e.g., ?tag=value1,value2)
• Nested Objects: Not supported in query parameters; operations requiring nested objects MUST use POST with a request body
• Datetimes/Timestamps: Represented as ISO 8601 strings (e.g., 2025-11-09T10:30:00Z)

1. Using MessageToDict in combination with httpx client produces correct output (test is added).
2. Parsing has an extra addition on top of ParseDict to support repeated fields in both formats (?tag=value1&tag=value2 and ?tag=value1,value2).
3. test_client_server_integration.py is updated to dedupe gRPC and HTTP based tests and it also asserts params now.

[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 improves the handling of REST query parameters across both the client and server components to align with the 1.0 specification. By introducing a centralized and robust parsing utility, it ensures consistent interpretation of request parameters, including proper serialization of field names, boolean values, and repeated fields. The changes also streamline the client's request preparation and enhance the server's ability to process incoming REST calls correctly. Furthermore, the refactoring of integration tests provides more comprehensive validation of these changes across all supported transport layers.

Highlights

• Standardized REST Query Parameter Handling: Introduced a new utility function, proto_utils.parse_params, to consistently convert REST query parameters into Protobuf messages. This function handles A2A-specific requirements such as camelCase field names, boolean string conversion ('true'/'false'), and robust parsing of repeated fields (supporting both multiple keys and comma-separated values).
• Client-Side Query Parameter Refinement: Modified the REST client to correctly exclude fields like id, taskId, and tenant from query parameters when they are part of the URL path or handled by the context, ensuring adherence to the 1.0 specification for various task-related API calls.
• Server-Side Query Parameter Integration: Updated the REST request handler to utilize the new proto_utils.parse_params for processing incoming query parameters, replacing previous ad-hoc parsing logic. This ensures that the server correctly interprets REST requests according to the specification.
• Enhanced Integration Test Coverage: Refactored integration tests to use a single parametrized fixture that runs tests across all supported transports (JSON-RPC, REST, gRPC). This significantly improves test efficiency and ensures consistent behavior across different communication protocols, with new tests specifically validating REST URL serialization.

Changelog

• src/a2a/client/transports/rest.py
  • Removed 'tenant' from query parameters in get_task, list_tasks, get_task_push_notification_config, list_task_push_notification_configs, and delete_task_push_notification_config.
  • Changed task_id to taskId in query parameter deletion logic for push notification configurations.
  • Updated list_tasks to use a pre-processed params dictionary instead of direct MessageToDict(request).
• src/a2a/server/request_handlers/rest_handler.py
  • Removed unused imports ParseDict and GetTaskRequest.
  • Replaced direct ParseDict calls with proto_utils.parse_params for query parameter processing in on_get_task, list_tasks, and list_push_notifications.
  • Added logic to set tenant from context if not provided in query parameters for list_tasks and list_push_notifications.
• src/a2a/utils/proto_utils.py
  • Added imports for ParseDict, ProtobufMessage, and QueryParams (with type checking guard).
  • Introduced new function parse_params to convert REST query parameters to Protobuf messages, handling boolean conversion, repeated fields, and camelCase names.
• tests/client/transports/test_rest_client.py
  • Imported Timestamp and TaskState.
  • Added test_url_serialization to verify correct serialization of query parameters, including camelCase and tenant exclusion.
  • Updated an assertion in test_rest_get_task_prepend_empty_tenant for URL string formatting.
• tests/integration/test_client_server_integration.py
  • Imported Timestamp and reorganized protobuf imports.
  • Removed unused imports A2ACardResolver and cryptography.hazmat.primitives.asymmetric.
  • Updated agent_card fixture to include extended_agent_card=True capability.
  • Modified TransportSetup to allow handler to be RequestHandler | AsyncMock.
  • Updated rest_setup to pass extended_agent_card to A2ARESTFastAPIApplication.
  • Added grpc_setup fixture and transport_setups parametrized fixture to unify integration tests.
  • Refactored multiple HTTP/gRPC specific integration tests into generic test_transport_* functions.
  • Updated ListTasksRequest in test_transport_list_tasks to include more comprehensive query parameters.
  • Removed f-string formatting for task IDs in various test requests.
  • Adjusted assertions to use assert_awaited_once_with(params, ANY) for handler calls.
• tests/utils/test_proto_utils.py
  • Added imports for httpx, MessageToDict, Parse, ProtobufMessage, Timestamp, AgentCard, AgentSkill, ListTasksRequest, and QueryParams.
  • Added TestRestParams class with test_rest_params_roundtrip and test_repeated_fields_parsing to validate the new proto_utils.parse_params function.

Activity

• The pull request was created by ishymko.
• The changes primarily involve refactoring and adding new utility functions and tests, indicating a focused development effort without external comments or reviews yet.

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 a centralized parse_params utility function to improve REST query parameter handling according to the A2A specification, ensuring robust and spec-compliant parsing for boolean conversions, timestamps, and repeated fields. The RESTHandler has been refactored to use this new logic, and the test suite has been significantly improved.

I am having trouble creating individual review comments. Click here to see my feedback.

src/a2a/utils/proto_utils.py (148-191)

The parse_params function is a critical and well-implemented addition. It correctly handles A2A-specific pre-processing for booleans and robustly supports repeated fields, including both multiple parameter keys and comma-separated values. This significantly improves the flexibility and correctness of REST query parameter parsing according to the specification. The inline comments clearly explain the logic.

tests/utils/test_proto_utils.py (185-241)

The TestRestParams class provides excellent unit test coverage for the new proto_utils.parse_params function. The test_rest_params_roundtrip comprehensively validates the parsing of various data types and camelCase conversion, while test_repeated_fields_parsing specifically targets the complex logic for handling repeated fields in different formats. This ensures the robustness and correctness of the core parsing utility.

tests/integration/test_client_server_integration.py (338-359)

The updated test_transport_list_tasks is much more comprehensive. It now includes a Timestamp and a wider range of ListTasksRequest parameters, providing better coverage for the new query parameter parsing logic across all transports. This is a significant improvement in test quality.

tests/integration/test_client_server_integration.py (233-254)

The introduction of the grpc_setup fixture and its inclusion in the transport_setups parametrized fixture is a significant improvement. This allows for comprehensive testing of gRPC transport alongside JSON-RPC and REST, greatly expanding test coverage and reducing test code duplication.

tests/client/transports/test_rest_client.py (179-218)

The test_url_serialization test is an excellent addition. It thoroughly verifies that MessageToDict correctly serializes various protobuf field types (enum, boolean, timestamp) into REST query parameters as per the A2A specification. Crucially, it also confirms that the tenant field is correctly excluded from the query parameters, which is vital for proper URL construction.

tests/integration/test_client_server_integration.py (220-222)

Passing extended_agent_card=agent_card to A2ARESTFastAPIApplication ensures that the REST server is correctly configured to serve the extended agent card during integration tests, which is important for comprehensive testing of this feature.

tests/integration/test_client_server_integration.py (279-282)

Refactoring test_http_transport_sends_message_streaming into a generic test_transport_sends_message_streaming that uses the transport_setups fixture is an excellent example of reducing test duplication and improving maintainability. This single test now covers all supported transports.

src/a2a/server/request_handlers/rest_handler.py (40)

Excluding _parse_params from tracing is a sensible optimization. Internal helper methods that are frequently called and don't represent significant logical units often don't require their own spans, reducing telemetry overhead.

src/a2a/utils/proto_utils.py (20-32)

The conditional import of QueryParams using TYPE_CHECKING and a try-except block is an excellent pattern for handling optional dependencies. It ensures type hints are available during development without forcing a runtime dependency if starlette is not installed, improving flexibility and reducing potential import errors.

src/a2a/utils/proto_utils.py (22-23)

Importing ParseDict and ProtobufMessage directly into proto_utils.py is appropriate, as these are now core components used by the new parse_params function. This centralizes protobuf-related imports where they are most directly used.

src/a2a/server/request_handlers/rest_handler.py (10)

Removing ParseDict from the imports is a good cleanup, as its functionality is now encapsulated within the new proto_utils.parse_params function, centralizing the parsing logic.

tests/client/transports/test_rest_client.py (8)

Adding the Timestamp import is necessary for the new test_url_serialization test, which verifies the correct serialization of timestamp fields in query parameters.

tests/client/transports/test_rest_client.py (29)

Importing TaskState is required for the new test_url_serialization test, which uses TaskState.TASK_STATE_WORKING as a parameter.

src/a2a/client/transports/rest.py (246-249)

Consistent application of camelCase for taskId and removal of tenant from query parameters for delete_task_push_notification_config is a good practice for maintaining a clean and consistent REST interface.

tests/client/transports/test_rest_client.py (661)

Changing the f-string to a regular string for the assertion is a minor stylistic change. While functionally equivalent in this case, it can sometimes improve readability when no variables are actually being interpolated.

tests/integration/test_client_server_integration.py (11)

The import of Timestamp is essential for the expanded test_transport_list_tasks test, allowing it to include timestamp-based filtering in the request parameters.

tests/integration/test_client_server_integration.py (34)

Removing A2ACardResolver is a good cleanup, indicating that the functionality it provided is either no longer needed in this specific test file or has been refactored elsewhere.

tests/integration/test_client_server_integration.py (59)

Removing the asymmetric import is a good cleanup, suggesting that the specific asymmetric cryptography primitives are no longer directly used in this file.

tests/integration/test_client_server_integration.py (163-164)

Enabling extended_agent_card=True in the AgentCapabilities for the agent_card fixture is a necessary change to properly test the extended agent card functionality across all transports.

tests/integration/test_client_server_integration.py (184)

Updating the type hint for handler to RequestHandler | AsyncMock is a good improvement for type accuracy. It correctly reflects that the handler can be either a concrete RequestHandler instance or a mock object in the test setup.

src/a2a/client/transports/rest.py (112-113)

The addition of del params['tenant'] is a good change. It ensures that the tenant ID, which is already part of the URL path, is not inadvertently included as a query parameter, maintaining clean and correct REST API calls.

src/a2a/client/transports/rest.py (219-222)

Similar to get_task_push_notification_config, updating the parameter name from task_id to taskId and removing tenant ensures adherence to REST API conventions and prevents redundant query parameters.

src/a2a/server/request_handlers/rest_handler.py (29)

Removing GetTaskRequest from the imports is appropriate since the on_get_task method now instantiates it directly from a2a_pb2, which is already imported.

tests/integration/test_client_server_integration.py (295-297)

Simplifying the assertions and using assert_called_once_with(params, ANY) makes the test more robust to minor changes in the context object while still verifying that the correct parameters are passed to the handler. This is a good practice for integration tests.

tests/integration/test_client_server_integration.py (303-306)

Consolidating test_http_transport_sends_message_blocking into a generic test_transport_sends_message_blocking using the parametrized transport_setups fixture is a great improvement for test efficiency and readability.

tests/integration/test_client_server_integration.py (317-318)

Similar to the streaming test, using assert_awaited_once_with(params, ANY) for blocking calls improves the test's resilience to minor context variations while ensuring the core parameters are correct.

tests/integration/test_client_server_integration.py (324-333)

This refactoring of test_transport_get_task to use the transport_setups fixture is a good example of reducing test boilerplate and making the test suite more concise and maintainable.

src/a2a/client/transports/rest.py (194-197)

Changing task_id to taskId in the del params logic is important for consistency with REST API conventions, which typically use camelCase for query parameters. The addition of del params['tenant'] is also correct for the same reasons.

tests/integration/test_client_server_integration.py (364-373)

Refactoring test_transport_cancel_task to use the transport_setups fixture streamlines the test and ensures consistent coverage across all transports.

tests/integration/test_client_server_integration.py (378-394)

Consolidating the create_task_push_notification_config tests into a single parametrized function improves test efficiency and readability.

tests/integration/test_client_server_integration.py (398-415)

The refactored test_transport_get_task_push_notification_config test is more concise and effectively tests the functionality across all transports using the transport_setups fixture.

tests/integration/test_client_server_integration.py (419-435)

This refactoring of test_transport_list_task_push_notification_configs significantly reduces test code duplication while maintaining full coverage across all transports.

tests/integration/test_client_server_integration.py (439-455)

Consolidating the delete_task_push_notification_config tests into a single parametrized function improves test efficiency and readability.

tests/integration/test_client_server_integration.py (459-470)

The refactored test_transport_subscribe test is more concise and effectively tests the functionality across all transports using the transport_setups fixture.

tests/integration/test_client_server_integration.py (474-479)

This refactoring of test_transport_get_card significantly reduces test code duplication while maintaining full coverage across all transports.

tests/integration/test_client_server_integration.py (483-496)

The refactored test_transport_get_extended_agent_card test is more concise and effectively tests the functionality across all transports using the transport_setups fixture. The updated assertion result.name in [agent_card.name, 'Extended Agent Card'] is also more flexible for different mock setups.

tests/utils/test_proto_utils.py (6-10)

Adding imports for httpx, MessageToDict, Parse, ProtobufMessage, and Timestamp is necessary to support the new TestRestParams class and its comprehensive unit tests for query parameter parsing.

tests/utils/test_proto_utils.py (13-15)

Importing AgentCard, AgentSkill, and ListTasksRequest is crucial for setting up the protobuf messages used in the new TestRestParams unit tests, ensuring that the parse_params function is tested with relevant message types.

tests/utils/test_proto_utils.py (26)

The import of QueryParams is essential for constructing the input to the proto_utils.parse_params function in the unit tests, allowing for direct testing of the new parsing logic.

src/a2a/client/transports/rest.py (132-134)

This refactoring correctly applies the logic of removing the tenant parameter from the query parameters for list_tasks, aligning it with the get_task method. This ensures consistency in how path parameters are handled across different REST endpoints.