refactor: Add RESTful API Serving and refactor client code to support multi-transport #348

holtskinner · 2025-07-24T19:29:07Z

No description provided.

# Adding stand-alone support for RESTful API serving Though the RESTful API (JSON+HTTP) can be served from an envoy transcoding of the gRPC service that may not always make sense in all cases. Instead, this PR also adds the ability to serve the RESTful API stand-alone, without needing to also setup the gRPC service. --------- Co-authored-by: Holt Skinner <holtskinner@google.com> Co-authored-by: swapydapy <swapnilag@google.com>

…s and simplify client interfaces (#342) # Description Refactor the client codebase to support automated, configurable, client factory to generate a client based on the agent card details. Adds support for generation of clients based on JSONRPC, gRPC and RESTful interfaces. --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Co-authored-by: Holt Skinner <holtskinner@google.com>

gemini-code-assist

Summary of Changes

Hello @holtskinner, 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 refactors the client-side architecture to support multiple communication transports (JSON-RPC, gRPC, and a newly introduced RESTful API) for interacting with agents. It also adds the necessary server-side components to enable agents to serve their functionalities via a RESTful interface. These changes enhance the flexibility and interoperability of the system by allowing clients and agents to negotiate and utilize the most suitable communication protocol.

Highlights

Multi-Transport Client Refactor: Introduced an abstract Client interface and concrete implementations for JSON-RPC, gRPC, and a new RESTful API, enabling flexible communication with agents. The previous A2AClient is now aliased for backward compatibility.
New Client Factory: Added a ClientFactory to dynamically create the appropriate client instance based on the agent's advertised capabilities and the client's configured preferences, simplifying client instantiation and transport negotiation.
RESTful API Serving: Implemented a new RESTful API layer for agents, including RESTApplication and A2ARESTFastAPIApplication, allowing agents to expose their functionalities via standard HTTP/JSON endpoints. This new API leverages Protocol Buffers for data consistency.
Centralized Task Management: Introduced ClientTaskManager to standardize the handling and updating of Task objects and related events across different client transports, centralizing state management.
Transport Enumeration: A new Transports enum has been added to define standard protocol transport labels (GRPC, JSONRPC, RESTful), improving clarity and type safety.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 or fill out our survey to provide feedback.

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.

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 multi-transport support for the client, including a new RESTful API implementation. The introduction of a ClientFactory and a common Client interface is a great step towards a more maintainable and extensible client library. However, I've identified several critical issues, particularly in the new REST client and server implementations, as well as some regressions and incomplete features in the new transport clients. Please see my detailed comments below.

gemini-code-assist · 2025-07-24T19:33:58Z

src/a2a/client/client.py

+except ImportError:
+    # If grpc.aio is not available, define a dummy type for type checking.
+    # This dummy type will only be used by type checkers.
+    if TYPE_CHECKING:


TYPE_CHECKING is used here but it has not been imported. This will lead to a NameError at runtime.

Please import it from the typing module to resolve this issue.

from typing import TYPE_CHECKING

gemini-code-assist · 2025-07-24T19:33:59Z

src/a2a/server/request_handlers/rest_handler.py

+        try:
+            task_id = request.path_params['id']
+            history_length = request.query_params.get('historyLength', None)
+            if historyLength:


There is a NameError here because historyLength is not defined. The variable is named history_length (with an underscore).

Please correct the variable name.

if history_length:

gemini-code-assist · 2025-07-24T19:33:59Z

src/a2a/server/request_handlers/rest_handler.py

+            body = await request.body()
+            params = a2a_pb2.TaskPushNotificationConfig()
+            Parse(body, params)
+            params = TaskPushNotificationConfig.model_validate(body)
+            a2a_request = proto_utils.FromProto.task_push_notification_config(
+                params,
+            )
+            config = (
+                await self.request_handler.on_set_task_push_notification_config(
+                    a2a_request, context
+                )
+            )


The logic for parsing and validating the request body is incorrect and will fail at runtime.

TaskPushNotificationConfig.model_validate(body) will raise an error because body is a bytes object, but model_validate expects a dictionary. You should use request.json() to get the parsed dictionary.

The subsequent call to proto_utils.FromProto.task_push_notification_config is also incorrect as it expects a protobuf message, not a Pydantic model.

Please refactor this to correctly parse the JSON body into the TaskPushNotificationConfig Pydantic model and pass that to the request handler.

params = TaskPushNotificationConfig.model_validate(await request.json()) config = ( await self.request_handler.on_set_task_push_notification_config( params, context ) )

This is a bug. Shouldn't be using the model validate approach at all, instead line 260 should be deleted

src/a2a/client/client_factory.py

gemini-code-assist · 2025-07-24T19:34:00Z

src/a2a/client/rest_client.py

+        context: ClientCallContext | None = None,
+    ) -> AsyncIterator[Task | Message]:
+        if not self._config.streaming or not self._card.capabilities.streaming:
+            raise Exception(
+                'client and/or server do not support resubscription.'
+            )
+        async for event in self._transport_client.resubscribe(
+            request,
+            http_kwargs=self.get_http_args(context),
+            context=context,
+        ):
+            # Update task, check for errors, etc.
+            yield event
+
+    async def get_card(
+        self,
+        *,


This implementation of resubscribe appears to be incomplete. It yields raw events from the transport client, but it should process them to yield Task | Message objects as per the method signature.

The comment # Update task, check for errors, etc. also suggests this is a work in progress. Please complete this implementation.

This is a valid bug to be fixed

gemini-code-assist · 2025-07-24T19:34:00Z

src/a2a/client/grpc_client.py

+        context: ClientCallContext | None = None,
+    ) -> AsyncIterator[Task | Message]:
+        if not self._config.streaming or not self._card.capabilities.streaming:
+            raise Exception(
+                'client and/or server do not support resubscription.'
+            )
+        async for event in self._transport_client.resubscribe(
+            request,
+            context=context,
+        ):
+            # Update task, check for errors, etc.
+            yield event
+
+    async def get_card(
+        self,
+        *,


This implementation of resubscribe appears to be incomplete. It yields raw events from the transport client, but it should likely process them using ClientTaskManager to yield ClientEvent or Message objects, similar to how send_message is implemented for streaming.

The comment # Update task, check for errors, etc. also suggests this is a work in progress. Please complete this implementation to ensure consistent behavior across the client.

This is a valid bug to be fixed

src/a2a/client/grpc_client.py

gemini-code-assist · 2025-07-24T19:34:01Z

src/a2a/client/client.py

+    @abstractmethod
+    async def resubscribe(
+        self,
+        request: TaskIdParams,


This abstract method is implemented with yield, which is inconsistent with other abstract methods in this class that use pass. This can be confusing for developers implementing this interface.

For consistency, please use pass here as well. The -> AsyncIterator type hint is sufficient for type checkers.

pass

gemini-code-assist · 2025-07-24T19:34:01Z

src/a2a/client/client.py

+
+        This will automatically use the streaming or non-streaming approach
+        as supported by the server and the client config. Client will
+        aggregate update events and return an iterator of (`Task`,`Update`)


This abstract method is implemented with yield, which makes it a concrete method returning an empty async generator. This is inconsistent with other abstract methods in this class (like get_task) which use pass.

For consistency and to make it clearer that this method must be implemented by subclasses, please use pass instead of yield.

pass

Looks like a merge failure Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Lock file update with latest dev dependencies

…ad of global installations

…ase variable renaming and module name change for patches

pstephengoogle and others added 2 commits July 24, 2025 20:24

holtskinner requested a review from a team as a code owner July 24, 2025 19:29

gemini-code-assist bot reviewed Jul 24, 2025

View reviewed changes

holtskinner added 2 commits July 24, 2025 20:31

Formatting/linting

f2c4085

Update AgentCard path to AGENT_CARD_WELL_KNOWN_PATH

1fa0ec7

holtskinner added this to the 0.3.0 Release milestone Jul 24, 2025

gemini-code-assist bot reviewed Jul 24, 2025

View reviewed changes

holtskinner and others added 12 commits July 24, 2025 20:36

Lint errors

98e9fe1

Lint - Construct AgentInterfaces for minimal_agent_card

d1d9e49

Update src/a2a/server/apps/rest/rest_app.py

68ce59b

Looks like a merge failure Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Merge branch 'main' into restful

30bcaef

Merge branch 'main' into restful

2a24b5f

Refactor to use TransportProtocol class from types.py

33ba15e

Fix lint errors in rest_handler

11bb306

Fixed lint errors in rest_app

ab7ab08

Merge branch 'main' into restful

78d03ef

chore: update lock file (#353)

c3f1bbb

Lock file update with latest dev dependencies

chore: Update vscode PyTest launch.json to use workspace's venv inste…

da44c94

…ad of global installations

fix: Fix all the failing unit tests due to cyclic dependency, snake c…

0c3d717

…ase variable renaming and module name change for patches

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor: Add RESTful API Serving and refactor client code to support multi-transport #348

refactor: Add RESTful API Serving and refactor client code to support multi-transport #348

holtskinner commented Jul 24, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Jul 24, 2025

Uh oh!

gemini-code-assist bot Jul 24, 2025

Uh oh!

gemini-code-assist bot Jul 24, 2025

Uh oh!

pstephengoogle Jul 25, 2025

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist bot Jul 24, 2025

Uh oh!

pstephengoogle Jul 25, 2025

Uh oh!

gemini-code-assist bot Jul 24, 2025

Uh oh!

pstephengoogle Jul 25, 2025

Uh oh!

Uh oh!

gemini-code-assist bot Jul 24, 2025

Uh oh!

gemini-code-assist bot Jul 24, 2025

Uh oh!

Uh oh!

refactor: Add RESTful API Serving and refactor client code to support multi-transport #348

Are you sure you want to change the base?

refactor: Add RESTful API Serving and refactor client code to support multi-transport #348

Conversation

holtskinner commented Jul 24, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

pstephengoogle Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist bot Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

pstephengoogle Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

pstephengoogle Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gemini-code-assist bot Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!