feat: Provide a more friendly builder-based way to configure transpor… (#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> 🦕

Author: brasseld

README.md

@@ -225,7 +225,7 @@ To make use of the Java `Client`:
 
 ### 1. Add the A2A Java SDK Client dependency to your project
 
-Adding a dependency on `a2a-java-sdk-client` will provide access to a `ClientFactory`
+Adding a dependency on `a2a-java-sdk-client` will provide access to a `ClientBuilder`
 that you can use to create your A2A `Client`.
 
 ----
@@ -243,21 +243,16 @@ that you can use to create your A2A `Client`.
 
 ### 2. Add one or more dependencies on the A2A Java SDK Client Transport(s) you'd like to use
 
-You need to add a dependency on at least one of the following client transport modules:
+By default, the sdk-client is coming with the JSONRPC transport dependency. Despite the fact that the JSONRPC transport 
+dependency is included by default, you still need to add the transport to the Client as described in [JSON-RPC Transport section](#json-rpc-transport-configuration).
+
+
+If you want to use another transport (such as GRPC or HTTP+JSON), you'll need to add a relevant dependency:
 
 ----
 > *⚠️ The `io.github.a2asdk` `groupId` below is temporary and will likely change for future releases.*
 ----
 
-```xml
-<dependency>
-    <groupId>io.github.a2asdk</groupId>
-    <artifactId>a2a-java-sdk-client-transport-jsonrpc</artifactId>
-    <!-- Use a released version from https://github.com/a2aproject/a2a-java/releases -->
-    <version>${io.a2a.sdk.version}</version>
-</dependency>
-```
-
 ```xml
 <dependency>
     <groupId>io.github.a2asdk</groupId>
@@ -271,13 +266,13 @@ Support for the HTTP+JSON/REST transport will be coming soon.
 
 ### Sample Usage
 
-#### Create a Client using the ClientFactory
+#### Create a Client using the ClientBuilder
 
 ```java
 // First, get the agent card for the A2A server agent you want to connect to
 AgentCard agentCard = new A2ACardResolver("http://localhost:1234").getAgentCard();
 
-// Specify configuration for the ClientFactory
+// Specify configuration for the ClientBuilder
 ClientConfig clientConfig = new ClientConfig.Builder()
         .setAcceptedOutputModes(List.of("text"))
         .build();
@@ -305,32 +300,39 @@ Consumer<Throwable> errorHandler = error -> {
     ...
 };
 
-// Create the client using ClientFactory
-ClientFactory clientFactory = new ClientFactory(clientConfig);
-Client client = clientFactory.create(agentCard, consumers, errorHandler);
+// Create the client using the builder
+Client client = Client
+        .builder(agentCard)
+        .clientConfig(clientConfig)
+        .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
+        .addConsumers(consumers)
+        .streamingErrorHandler(errorHandler)
+        .build();
 ```
 
 #### Configuring Transport-Specific Settings
 
-Different transport protocols can be configured with specific settings using `ClientTransportConfig` implementations. The A2A Java SDK provides `JSONRPCTransportConfig` for the JSON-RPC transport and `GrpcTransportConfig` for the gRPC transport.
+Different transport protocols can be configured with specific settings using specific `ClientTransportConfig` implementations. The A2A Java SDK provides `JSONRPCTransportConfig` for the JSON-RPC transport and `GrpcTransportConfig` for the gRPC transport.
 
 ##### JSON-RPC Transport Configuration
 
 For the JSON-RPC transport, if you'd like to use the default `JdkA2AHttpClient`, no additional
-configuration is needed. To use a custom HTTP client instead, simply create a `JSONRPCTransportConfig`
+configuration is needed. To use a custom HTTP client implementation, simply create a `JSONRPCTransportConfig`
 as follows:
 
 ```java
 // Create a custom HTTP client
 A2AHttpClient customHttpClient = ...
 
-// Create JSON-RPC transport configuration
-JSONRPCTransportConfig jsonrpcConfig = new JSONRPCTransportConfig(customHttpClient);
-
-// Configure the client with transport-specific settings
+// Configure the client settings
 ClientConfig clientConfig = new ClientConfig.Builder()
         .setAcceptedOutputModes(List.of("text"))
-        .setClientTransportConfigs(List.of(jsonrpcConfig))
+        .build();
+
+Client client = Client
+        .builder(agentCard)
+        .clientConfig(clientConfig)
+        .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig(customHttpClient))
         .build();
 ```
 
@@ -346,13 +348,15 @@ Function<String, Channel> channelFactory = agentUrl -> {
             .build();
 };
 
-// Create gRPC transport configuration
-GrpcTransportConfig grpcConfig = new GrpcTransportConfig(channelFactory);
-
 // Configure the client with transport-specific settings
 ClientConfig clientConfig = new ClientConfig.Builder()
         .setAcceptedOutputModes(List.of("text"))
-        .setClientTransportConfigs(List.of(grpcConfig))
+        .build();
+
+Client client = Client
+        .builder(agentCard)
+        .clientConfig(clientConfig)
+        .withTransport(GrpcTransport.class, new GrpcTransportConfig(channelFactory))
         .build();
 ```
 
@@ -363,15 +367,11 @@ will be used based on the selected transport:
 
 ```java
 // Configure both JSON-RPC and gRPC transports
-List<ClientTransportConfig> transportConfigs = List.of(
-    new JSONRPCTransportConfig(...),
-    new GrpcTransportConfig(...)
-);
-
-ClientConfig clientConfig = new ClientConfig.Builder()
-        .setAcceptedOutputModes(List.of("text"))
-        .setClientTransportConfigs(transportConfigs)
-        .build();
+Client client = Client
+                .builder(agentCard)
+                .withTransport(GrpcTransport.class, new GrpcTransportConfig(channelFactory))
+                .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
+                .build();
 ```
 
 #### Send a message to the A2A server agent

client/base/pom.xml

@@ -20,15 +20,20 @@
     <dependencies>
         <dependency>
             <groupId>${project.groupId}</groupId>
-            <artifactId>a2a-java-sdk-client-config</artifactId>
+            <artifactId>a2a-java-sdk-http-client</artifactId>
         </dependency>
         <dependency>
             <groupId>${project.groupId}</groupId>
-            <artifactId>a2a-java-sdk-http-client</artifactId>
+            <artifactId>a2a-java-sdk-client-transport-spi</artifactId>
         </dependency>
         <dependency>
             <groupId>${project.groupId}</groupId>
-            <artifactId>a2a-java-sdk-client-transport-spi</artifactId>
+            <artifactId>a2a-java-sdk-client-transport-jsonrpc</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>a2a-java-sdk-client-transport-grpc</artifactId>
+            <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>${project.groupId}</groupId>

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

@@ -3,7 +3,7 @@
 import java.util.Collections;
 import java.util.Map;
 
-import io.a2a.client.A2ACardResolver;
+import io.a2a.client.http.A2ACardResolver;
 import io.a2a.client.http.A2AHttpClient;
 import io.a2a.client.http.JdkA2AHttpClient;
 import io.a2a.spec.A2AClientError;

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

@@ -7,7 +7,7 @@
 import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
-import io.a2a.client.config.ClientCallContext;
+import io.a2a.client.transport.spi.interceptors.ClientCallContext;
 import io.a2a.spec.A2AClientException;
 import io.a2a.spec.AgentCard;
 import io.a2a.spec.DeleteTaskPushNotificationConfigParams;
@@ -387,4 +387,4 @@ public Consumer<Throwable> getStreamingErrorHandler() {
         return streamingErrorHandler;
     }
 
-}
+}

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

@@ -5,8 +5,8 @@
 import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
-import io.a2a.client.config.ClientCallContext;
 import io.a2a.client.config.ClientConfig;
+import io.a2a.client.transport.spi.interceptors.ClientCallContext;
 import io.a2a.client.transport.spi.ClientTransport;
 import io.a2a.spec.A2AClientError;
 import io.a2a.spec.A2AClientException;
@@ -28,20 +28,27 @@
 import io.a2a.spec.TaskQueryParams;
 import io.a2a.spec.TaskStatusUpdateEvent;
 
+import static io.a2a.util.Assert.checkNotNullParam;
+
 public class Client extends AbstractClient {
 
     private final ClientConfig clientConfig;
     private final ClientTransport clientTransport;
     private AgentCard agentCard;
 
-    public Client(AgentCard agentCard, ClientConfig clientConfig, ClientTransport clientTransport,
+    Client(AgentCard agentCard, ClientConfig clientConfig, ClientTransport clientTransport,
                   List<BiConsumer<ClientEvent, AgentCard>> consumers, Consumer<Throwable> streamingErrorHandler) {
         super(consumers, streamingErrorHandler);
+        checkNotNullParam("agentCard", agentCard);
+
         this.agentCard = agentCard;
         this.clientConfig = clientConfig;
         this.clientTransport = clientTransport;
     }
 
+    public static ClientBuilder builder(AgentCard agentCard) {
+        return new ClientBuilder(agentCard);
+    }
 
     @Override
     public void sendMessage(Message request, ClientCallContext context) throws A2AClientException {

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

@@ -0,0 +1,164 @@
+package io.a2a.client;
+
+import io.a2a.client.config.ClientConfig;
+import io.a2a.client.transport.spi.ClientTransport;
+import io.a2a.client.transport.spi.ClientTransportConfig;
+import io.a2a.client.transport.spi.ClientTransportConfigBuilder;
+import io.a2a.client.transport.spi.ClientTransportProvider;
+import io.a2a.spec.A2AClientException;
+import io.a2a.spec.AgentCard;
+import io.a2a.spec.AgentInterface;
+import io.a2a.spec.TransportProtocol;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.ServiceLoader;
+import java.util.function.BiConsumer;
+import java.util.function.Consumer;
+
+public class ClientBuilder {
+
+    private static final Map<String, ClientTransportProvider<? extends ClientTransport, ? extends ClientTransportConfig<?>>> transportProviderRegistry = new HashMap<>();
+    private static final Map<Class<? extends ClientTransport>, String> transportProtocolMapping = new HashMap<>();
+
+    static {
+        ServiceLoader<ClientTransportProvider> loader = ServiceLoader.load(ClientTransportProvider.class);
+        for (ClientTransportProvider<?, ?> transport : loader) {
+            transportProviderRegistry.put(transport.getTransportProtocol(), transport);
+            transportProtocolMapping.put(transport.getTransportProtocolClass(), transport.getTransportProtocol());
+        }
+    }
+
+    private final AgentCard agentCard;
+
+    private final List<BiConsumer<ClientEvent, AgentCard>> consumers = new ArrayList<>();
+    private Consumer<Throwable> streamErrorHandler;
+    private ClientConfig clientConfig;
+
+    private final Map<Class<? extends ClientTransport>, ClientTransportConfig<? extends ClientTransport>> clientTransports = new LinkedHashMap<>();
+
+    ClientBuilder(AgentCard agentCard) {
+        this.agentCard = agentCard;
+    }
+
+    public <T extends ClientTransport> ClientBuilder withTransport(Class<T> clazz, ClientTransportConfigBuilder<? extends ClientTransportConfig<T>, ?> configBuilder) {
+        return withTransport(clazz, configBuilder.build());
+    }
+
+    public <T extends ClientTransport> ClientBuilder withTransport(Class<T> clazz, ClientTransportConfig<T> config) {
+        clientTransports.put(clazz, config);
+
+        return this;
+    }
+
+    public ClientBuilder addConsumer(BiConsumer<ClientEvent, AgentCard> consumer) {
+        this.consumers.add(consumer);
+        return this;
+    }
+
+    public ClientBuilder addConsumers(List<BiConsumer<ClientEvent, AgentCard>> consumers) {
+        this.consumers.addAll(consumers);
+        return this;
+    }
+
+    public ClientBuilder streamingErrorHandler(Consumer<Throwable> streamErrorHandler) {
+        this.streamErrorHandler = streamErrorHandler;
+        return this;
+    }
+
+    public ClientBuilder clientConfig(ClientConfig clientConfig) {
+        this.clientConfig = clientConfig;
+        return this;
+    }
+
+    public Client build() throws A2AClientException {
+        if (this.clientConfig == null) {
+            this.clientConfig = new ClientConfig.Builder().build();
+        }
+
+        ClientTransport clientTransport = buildClientTransport();
+
+        return new Client(agentCard, clientConfig, clientTransport, consumers, streamErrorHandler);
+    }
+
+    @SuppressWarnings("unchecked")
+    private ClientTransport buildClientTransport() throws A2AClientException {
+        // Get the preferred transport
+        AgentInterface agentInterface = findBestClientTransport();
+        Class<? extends ClientTransport> transportProtocolClass = transportProviderRegistry.get(agentInterface.transport()).getTransportProtocolClass();
+
+        // Get the transport provider associated to the protocol
+        ClientTransportProvider clientTransportProvider = transportProviderRegistry.get(agentInterface.transport());
+
+        // Retrieve the configuration associated to the preferred transport
+        ClientTransportConfig<? extends ClientTransport> clientTransportConfig = clientTransports.get(transportProtocolClass);
+
+        if (clientTransportConfig == null) {
+            throw new A2AClientException("Missing required TransportConfig for " + agentInterface.transport());
+        }
+
+        return clientTransportProvider.create(clientTransportConfig, agentCard, agentInterface.url());
+    }
+
+    private Map<String, String> getServerPreferredTransports() {
+        Map<String, String> serverPreferredTransports = new LinkedHashMap<>();
+        serverPreferredTransports.put(agentCard.preferredTransport(), agentCard.url());
+        if (agentCard.additionalInterfaces() != null) {
+            for (AgentInterface agentInterface : agentCard.additionalInterfaces()) {
+                serverPreferredTransports.putIfAbsent(agentInterface.transport(), agentInterface.url());
+            }
+        }
+        return serverPreferredTransports;
+    }
+
+    private List<String> getClientPreferredTransports() {
+        List<String> supportedClientTransports = new ArrayList<>();
+
+        if (clientTransports.isEmpty()) {
+            // default to JSONRPC if not specified
+            supportedClientTransports.add(TransportProtocol.JSONRPC.asString());
+        } else {
+            clientTransports.forEach((aClass, clientTransportConfig) -> supportedClientTransports.add(transportProtocolMapping.get(aClass)));
+        }
+        return supportedClientTransports;
+    }
+
+    private AgentInterface findBestClientTransport() throws A2AClientException {
+        // Retrieve transport supported by the A2A server
+        Map<String, String> serverPreferredTransports = getServerPreferredTransports();
+
+        // Retrieve transport configured for this client (using withTransport methods)
+        List<String> clientPreferredTransports = getClientPreferredTransports();
+
+        String transportProtocol = null;
+        String transportUrl = null;
+        if (clientConfig.isUseClientPreference()) {
+            for (String clientPreferredTransport : clientPreferredTransports) {
+                if (serverPreferredTransports.containsKey(clientPreferredTransport)) {
+                    transportProtocol = clientPreferredTransport;
+                    transportUrl = serverPreferredTransports.get(transportProtocol);
+                    break;
+                }
+            }
+        } else {
+            for (Map.Entry<String, String> transport : serverPreferredTransports.entrySet()) {
+                if (clientPreferredTransports.contains(transport.getKey())) {
+                    transportProtocol = transport.getKey();
+                    transportUrl = transport.getValue();
+                    break;
+                }
+            }
+        }
+        if (transportProtocol == null || transportUrl == null) {
+            throw new A2AClientException("No compatible transport found");
+        }
+        if (! transportProviderRegistry.containsKey(transportProtocol)) {
+            throw new A2AClientException("No client available for " + transportProtocol);
+        }
+
+        return new AgentInterface(transportProtocol, transportUrl);
+    }
+}