feat: Provide a more friendly builder-based way to configure transpor… by brasseld · Pull Request #238 · a2aproject/a2a-java

brasseld · 2025-08-25T14:27:07Z

…t configuration

This PR is a proposal to make the transport configuration specific to a given transport implementation.

This one will ease developer experience by providing a builder for configuring a Client in a more stricter way compare to what exists today.

Also, this will help at getting rid of strong coupling with different transport implementations.
Two benefits:

Get rid of dependencies which may not be required (grpc dependencies if you only go for jsonrpc)
Easier to provide new transport implementation (such as HTTP+JSON).

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 pass
Appropriate READMEs were updated (if necessary)

Fixes #<issue_number_goes_here> 🦕

gemini-code-assist

Summary of Changes

Hello @brasseld, 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 introduces a significant enhancement to the client configuration process by implementing a new builder-based API. The primary goal is to provide a more user-friendly and fluent way to set up and customize client transports, moving away from the previous ClientFactory approach. This change simplifies client instantiation, improves modularity by centralizing transport configuration, and refactors core configuration classes for better maintainability. The update also includes necessary adjustments to module dependencies and documentation to reflect these architectural improvements.

Highlights

New Client Builder API: Introduced a new ClientBuilder class that provides a more intuitive and fluent API for constructing Client instances, simplifying the process of setting up client configurations and transports.
Removal of ClientFactory: The previous ClientFactory class has been removed, streamlining the client instantiation process and consolidating configuration logic within the new builder pattern.
Simplified Transport Configuration: Refactored how transport-specific settings are applied. Instead of passing a list of ClientTransportConfig objects to ClientConfig, transports are now configured directly on the ClientBuilder using dedicated methods like withJsonRpcTransport and withTransport.
ClientConfig Refactoring: The ClientConfig class has been updated to no longer directly manage ClientTransportConfig instances, reducing its complexity and focusing its role on general client settings.
Module and Package Restructuring: Core utility classes related to client configuration and interceptors, such as A2ACardResolver, ClientCallContext, ClientCallInterceptor, and PayloadAndHeaders, have been relocated to more appropriate modules and packages (http-client and client/transport/spi/interceptors) to improve modularity and organization.
Standardized Transport SPI: New abstract classes ClientTransportConfig and ClientTransportConfigBuilder have been added to the Service Provider Interface (SPI) module, providing a standardized and extensible framework for defining and building transport-specific configurations.
Dependency Updates: Updated pom.xml files across various modules to reflect the new dependency structure, including the removal of the dedicated client-config module and adjustments for the new builder-based approach.
Documentation and Example Updates: The README.md and example client code have been updated to demonstrate the usage of the new ClientBuilder API, providing clear guidance for developers adopting the new configuration approach.

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. 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.

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 significant and positive change by refactoring the client creation mechanism to a more intuitive and fluent builder-based API. The removal of ClientFactory in favor of ClientBuilder simplifies transport configuration and improves the overall developer experience. The changes are well-structured, including updates to documentation and tests to reflect the new API. I've identified a few areas for improvement, mainly concerning null-safety, deterministic behavior, and clarity in the documentation examples. Addressing these points will make the new API even more robust and user-friendly.

client/base/src/main/java/io/a2a/client/ClientBuilder.java

client/base/src/test/java/io/a2a/client/ClientBuilderTest.java

...nt/transport/spi/src/main/java/io/a2a/client/transport/spi/ClientTransportConfigBuilder.java

README.md

client/base/src/main/java/io/a2a/client/ClientBuilder.java

fjuma

Thanks @brasseld! Looks good, I've added some small comments.

README.md

...nt/transport/spi/src/main/java/io/a2a/client/transport/spi/ClientTransportConfigBuilder.java

client/transport/grpc/src/main/java/io/a2a/client/transport/grpc/GrpcTransportProvider.java

.../transport/jsonrpc/src/main/java/io/a2a/client/transport/jsonrpc/JSONRPCTransportConfig.java

tests/server-common/src/test/java/io/a2a/server/apps/common/AbstractA2AServerTest.java

client/base/src/main/java/io/a2a/client/ClientBuilder.java

README.md

brasseld · 2025-08-26T10:21:47Z

@fjuma thanks for your comments.

Most (all !) the points you have raised should have been fixed now.

README.md

client/base/pom.xml

README.md

client/transport/grpc/src/main/java/io/a2a/client/transport/grpc/GrpcTransportConfig.java

...nt/transport/grpc/src/main/java/io/a2a/client/transport/grpc/GrpcTransportConfigBuilder.java

client/base/src/test/java/io/a2a/client/ClientBuilderTest.java

client/transport/grpc/src/main/java/io/a2a/client/transport/grpc/GrpcTransportProvider.java

http-client/pom.xml

...nt/transport/grpc/src/main/java/io/a2a/client/transport/grpc/GrpcTransportConfigBuilder.java

brasseld · 2025-08-26T15:27:10Z

I have pushed a new version to fix your previous comments, and also provided an implementation for this #238 (comment)

fjuma · 2025-08-27T12:26:42Z

README.md

+        .builder(agentCard)
+        .clientConfig(clientConfig)
+        .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
+        .addStreamConsumers(consumers)


.addConsumers(...)

fjuma · 2025-08-27T12:29:07Z

README.md

+Client client = Client
+        .builder(agentCard)
+        .clientConfig(clientConfig)
+        .withTransport(GrpcTransport.class, new GrpcTransportConfigBuilder(channelFactory))


new GrpcTransportConfig(channelFactory)

fjuma · 2025-08-27T12:35:35Z

Thanks very much for all the updates, @brasseld! I've just added a couple final comments for the README.

brasseld · 2025-08-27T13:11:42Z

Last updates puhsed @fjuma

fjuma

Thanks @brasseld!

fjuma · 2025-08-27T13:13:59Z

@kabir @ehsavoie Please review when you get a chance, thanks!

kabir

LGTM!

ehsavoie · 2025-08-27T15:34:50Z

I understand there is a 'global' ClientConfig to be shared across transports, but I'm wondering what would be the case if we want a different configuration per transport. It feels a bit strange to define a configuration for the client to then define one per transport.
Otherwise LGTM

kabir · 2025-08-27T15:45:17Z

@ehsavoie @fjuma Just throwing this out there without much thought. But I think perhaps if what you say becomes an issue, then an option in the future could be:

ClientConfig becomes the global/default setting
The transport configs are enhanced to allow setting the same stuff as in ClientConfig, so those become overrides

Then when constructing the client for each transport, we merge in the overrides with the global ClientConfig for each transport

brasseld · 2025-08-27T16:49:47Z

@kabir @fjuma @ehsavoie
I would say that, generally speaking, the transport configuration is something really specific to the transport itself while everything in the ClientConfig is more general but does only apply to the client iself (ClientConfig is no more passed to the Transport, and there is now a clear separation of concerns).

I quickly looked at how it's done for the MCP SDK, and it's somehow similar approach: https://modelcontextprotocol.io/sdk/java/mcp-client#sse-httpclient

ehsavoie · 2025-08-27T17:09:55Z

@brasseld It was more a theorical question, and we can rethink about it if this question is raised in the future.

client/base/src/main/java/io/a2a/client/config/ClientConfig.java

client/base/src/main/java/io/a2a/client/ClientBuilder.java

…t configuration

fjuma · 2025-08-27T17:59:30Z

Thanks @brasseld!

fjuma · 2025-08-27T18:01:08Z

@kabir @ehsavoie Thanks for the comments! I agree that we can always revisit the configuration if needed in the future. I'll go ahead and merge this.

a2aproject#238) …t configuration This PR is a proposal to make the transport configuration specific to a given transport implementation. This one will ease developer experience by providing a builder for configuring a Client in a more stricter way compare to what exists today. Also, this will help at getting rid of strong coupling with different transport implementations. Two benefits: Get rid of dependencies which may not be required (grpc dependencies if you only go for jsonrpc) Easier to provide new transport implementation (such as HTTP+JSON). # 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: - [x] Follow the [`CONTRIBUTING` Guide](../CONTRIBUTING.md). - [x] Make your Pull Request title in the <https://www.conventionalcommits.org/> specification. - Important Prefixes for [release-please](https://github.com/googleapis/release-please): - `fix:` which represents bug fixes, and correlates to a [SemVer](https://semver.org/) 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. - [x] Ensure the tests pass - [x] Appropriate READMEs were updated (if necessary) Fixes #<issue_number_goes_here> 🦕

gemini-code-assist bot reviewed Aug 25, 2025

View reviewed changes

brasseld force-pushed the agnostic_client_config branch 2 times, most recently from db67c38 to 5e01ede Compare August 25, 2025 14:39

fjuma requested changes Aug 25, 2025

View reviewed changes

fjuma reviewed Aug 25, 2025

View reviewed changes

README.md Show resolved Hide resolved

brasseld force-pushed the agnostic_client_config branch from 5e01ede to 623ba51 Compare August 26, 2025 10:21

brasseld requested a review from fjuma August 26, 2025 10:38

fjuma requested changes Aug 26, 2025

View reviewed changes

fjuma requested a review from kabir August 26, 2025 14:22

fjuma reviewed Aug 26, 2025

View reviewed changes

...nt/transport/grpc/src/main/java/io/a2a/client/transport/grpc/GrpcTransportConfigBuilder.java Show resolved Hide resolved

brasseld force-pushed the agnostic_client_config branch from 623ba51 to 7af5e84 Compare August 26, 2025 15:26

brasseld force-pushed the agnostic_client_config branch from 7af5e84 to ac72101 Compare August 27, 2025 06:43

brasseld requested a review from fjuma August 27, 2025 06:44

fjuma reviewed Aug 27, 2025

View reviewed changes

brasseld force-pushed the agnostic_client_config branch from ac72101 to d811eac Compare August 27, 2025 13:11

fjuma approved these changes Aug 27, 2025

View reviewed changes

kabir approved these changes Aug 27, 2025

View reviewed changes

fjuma mentioned this pull request Aug 27, 2025

feat: add support for JSON+HTTP/REST #229

Merged

fjuma reviewed Aug 27, 2025

View reviewed changes

client/base/src/main/java/io/a2a/client/config/ClientConfig.java Outdated Show resolved Hide resolved

fjuma reviewed Aug 27, 2025

View reviewed changes

client/base/src/main/java/io/a2a/client/ClientBuilder.java Show resolved Hide resolved

feat: Provide a more friendly builder-based way to configure transpor…

21939d0

…t configuration

brasseld force-pushed the agnostic_client_config branch from d811eac to 21939d0 Compare August 27, 2025 17:53

fjuma merged commit 5686c8e into a2aproject:main Aug 27, 2025
3 checks passed

brasseld deleted the agnostic_client_config branch August 27, 2025 18:03

kabir mentioned this pull request Aug 28, 2025

[Bug]: JSONDecodeError When trying A2AClient in Java to python A2A agent #204

Open

1 task

Conversation

brasseld commented Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fjuma left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brasseld commented Aug 26, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brasseld commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fjuma Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

fjuma Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

fjuma commented Aug 27, 2025

Uh oh!

brasseld commented Aug 27, 2025

Uh oh!

fjuma left a comment

Choose a reason for hiding this comment

Uh oh!

fjuma commented Aug 27, 2025

Uh oh!

kabir left a comment

Choose a reason for hiding this comment

Uh oh!

ehsavoie commented Aug 27, 2025

Uh oh!

kabir commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brasseld commented Aug 27, 2025

Uh oh!

ehsavoie commented Aug 27, 2025

Uh oh!

Uh oh!

brasseld commented Aug 25, 2025 •

edited

Loading

brasseld commented Aug 26, 2025 •

edited

Loading

kabir commented Aug 27, 2025 •

edited

Loading