Merge pull request #122 from kabir/agentcardproducer

maeste · web-flow · commit 0fa0ef40b50e · 2025-06-23T10:47:16.000+02:00
Add AgentCardProducer
diff --git a/core/src/main/java/io/a2a/client/A2ACardResolver.java b/core/src/main/java/io/a2a/client/A2ACardResolver.java
@@ -0,0 +1,104 @@
+package io.a2a.client;
+
+import static io.a2a.util.Utils.unmarshalFrom;
+
+import java.io.IOException;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.atomic.AtomicReference;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.core.type.TypeReference;
+import io.a2a.http.A2AHttpClient;
+import io.a2a.http.A2AHttpResponse;
+import io.a2a.spec.A2A;
+import io.a2a.spec.A2AClientError;
+import io.a2a.spec.A2AClientJSONError;
+import io.a2a.spec.AgentCard;
+
+public class A2ACardResolver {
+    private final A2AHttpClient httpClient;
+    private final String url;
+    private final Map<String, String> authHeaders;
+
+    static String DEFAULT_AGENT_CARD_PATH = "/.well-known/agent.json";
+
+    static final TypeReference<AgentCard> AGENT_CARD_TYPE_REFERENCE = new TypeReference<>() {};
+    /**
+     * @param httpClient the http client to use
+     * @param baseUrl the base URL for the agent whose agent card we want to retrieve
+     */
+    public A2ACardResolver(A2AHttpClient httpClient, String baseUrl) {
+        this(httpClient, baseUrl, null, null);
+    }
+
+    /**
+     * @param httpClient the http client to use
+     * @param baseUrl the base URL for the agent whose agent card we want to retrieve
+     * @param agentCardPath optional path to the agent card endpoint relative to the base
+     *                         agent URL, defaults to ".well-known/agent.json"
+     */
+    public A2ACardResolver(A2AHttpClient httpClient, String baseUrl, String agentCardPath) {
+        this(httpClient, baseUrl, agentCardPath, null);
+    }
+
+    /**
+     * @param httpClient the http client to use
+     * @param baseUrl the base URL for the agent whose agent card we want to retrieve
+     * @param agentCardPath optional path to the agent card endpoint relative to the base
+     *                         agent URL, defaults to ".well-known/agent.json"
+     * @param authHeaders the HTTP authentication headers to use. May be {@code null}
+     */
+    public A2ACardResolver(A2AHttpClient httpClient, String baseUrl, String agentCardPath, Map<String, String> authHeaders) {
+        this.httpClient = httpClient;
+        if (!baseUrl.endsWith("/")) {
+            baseUrl += "/";
+        }
+        agentCardPath = agentCardPath == null || agentCardPath.isEmpty() ? DEFAULT_AGENT_CARD_PATH : agentCardPath;
+        if (agentCardPath.startsWith("/")) {
+            agentCardPath = agentCardPath.substring(1);
+        }
+        this.url = baseUrl + agentCardPath;
+        this.authHeaders = authHeaders;
+    }
+
+    /**
+     * Get the agent card for the configured A2A agent.
+     *
+     * @return the agent card
+     * @throws A2AClientError If an HTTP error occurs fetching the card
+     * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
+     */
+    public AgentCard getAgentCard() throws A2AClientError, A2AClientJSONError {
+        A2AHttpClient.GetBuilder builder = httpClient.createGet()
+                .url(url)
+                .addHeader("Content-Type", "application/json");
+
+        if (authHeaders != null) {
+            for (Map.Entry<String, String> entry : authHeaders.entrySet()) {
+                builder.addHeader(entry.getKey(), entry.getValue());
+            }
+        }
+
+        String body;
+        try {
+            A2AHttpResponse response = builder.get();
+            if (!response.success()) {
+                throw new A2AClientError("Failed to obtain agent card: " + response.status());
+            }
+            body = response.body();
+        } catch (IOException | InterruptedException e) {
+            throw new A2AClientError("Failed to obtain agent card", e);
+        }
+
+        try {
+            return unmarshalFrom(body, AGENT_CARD_TYPE_REFERENCE);
+        } catch (JsonProcessingException e) {
+            throw new A2AClientJSONError("Could not unmarshal agent card response", e);
+        }
+
+    }
+
+
+}
diff --git a/core/src/main/java/io/a2a/client/A2AClient.java b/core/src/main/java/io/a2a/client/A2AClient.java
@@ -25,6 +25,8 @@
 import io.a2a.http.A2AHttpResponse;
 import io.a2a.http.JdkA2AHttpClient;
 import io.a2a.spec.A2A;
+import io.a2a.spec.A2AClientError;
+import io.a2a.spec.A2AClientJSONError;
 import io.a2a.spec.A2AServerException;
 import io.a2a.spec.AgentCard;
 import io.a2a.spec.CancelTaskRequest;
@@ -86,14 +88,33 @@ public A2AClient(String agentUrl) {
         this.httpClient = new JdkA2AHttpClient();
     }
 
+    /**
+     * Fetches the agent card and initialises an A2A client.
+     *
+     * @param httpClient the {@link  A2AHttpClient} to use
+     * @param baseUrl the base URL of the agent's host
+     * @param agentCardPath the path to the agent card endpoint, relative to the {@code baseUrl}. If {@code null},  the
+     *                      value {@link A2ACardResolver#DEFAULT_AGENT_CARD_PATH} will be used
+     * @return an initialised {@code A2AClient} instance
+     * @throws A2AClientError If an HTTP error occurs fetching the card
+     * @throws A2AClientJSONError if the agent card response is invalid
+     */
+    public static A2AClient getClientFromAgentCardUrl(A2AHttpClient httpClient, String baseUrl,
+                                                      String agentCardPath) throws A2AClientError, A2AClientJSONError {
+        A2ACardResolver resolver = new A2ACardResolver(httpClient, baseUrl, agentCardPath);
+        AgentCard card = resolver.getAgentCard();
+        return new A2AClient(card);
+    }
+
     /**
      * Get the agent card for the A2A server this client will be communicating with from
      * the default public agent card endpoint.
      *
      * @return the agent card for the A2A server
-     * @throws {@code A2AServerException} if the agent card for the A2A server cannot be obtained
+     * @throws A2AClientError If an HTTP error occurs fetching the card
+     * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
      */
-    public AgentCard getAgentCard() throws A2AServerException {
+    public AgentCard getAgentCard() throws A2AClientError, A2AClientJSONError {
         if (this.agentCard == null) {
             this.agentCard = A2A.getAgentCard(this.httpClient, this.agentUrl);
         }
@@ -106,9 +127,10 @@ public AgentCard getAgentCard() throws A2AServerException {
      * @param relativeCardPath the path to the agent card endpoint relative to the base URL of the A2A server
      * @param authHeaders the HTTP authentication headers to use
      * @return the agent card for the A2A server
-     * @throws {@code A2AServerException} if the agent card for the A2A server cannot be obtained
+     * @throws A2AClientError If an HTTP error occurs fetching the card
+     * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
      */
-    public AgentCard getAgentCard(String relativeCardPath, Map<String, String> authHeaders) throws A2AServerException {
+    public AgentCard getAgentCard(String relativeCardPath, Map<String, String> authHeaders) throws A2AClientError, A2AClientJSONError {
         if (this.agentCard == null) {
             this.agentCard = A2A.getAgentCard(this.httpClient, this.agentUrl, relativeCardPath, authHeaders);
         }
diff --git a/core/src/main/java/io/a2a/spec/A2A.java b/core/src/main/java/io/a2a/spec/A2A.java
@@ -1,14 +1,10 @@
 package io.a2a.spec;
 
-import static io.a2a.util.Utils.unmarshalFrom;
-
-import java.io.IOException;
 import java.util.Collections;
 import java.util.Map;
 
-import com.fasterxml.jackson.core.type.TypeReference;
+import io.a2a.client.A2ACardResolver;
 import io.a2a.http.A2AHttpClient;
-import io.a2a.http.A2AHttpResponse;
 import io.a2a.http.JdkA2AHttpClient;
 
 
@@ -27,13 +23,6 @@ public class A2A {
 
     public static final String JSONRPC_VERSION = "2.0";
 
-    public static final String AGENT_CARD_REQUEST = ".well-known/agent.json";
-
-    private static final TypeReference<AgentCard> AGENT_CARD_TYPE_REFERENCE = new TypeReference<>() {};
-
-    public static String getRequestEndpoint(String agentUrl, String request) {
-        return agentUrl.endsWith("/") ? agentUrl + request : agentUrl + "/" + request;
-    }
 
     /**
      * Convert the given text to a user message.
@@ -93,9 +82,10 @@ private static Message toMessage(String text, Message.Role role, String messageI
      *
      * @param agentUrl the base URL for the agent whose agent card we want to retrieve
      * @return the agent card
-     * @throws A2AServerException if the agent card cannot be retrieved for any reason
+     * @throws A2AClientError If an HTTP error occurs fetching the card
+     * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
      */
-    public static AgentCard getAgentCard(String agentUrl) throws A2AServerException {
+    public static AgentCard getAgentCard(String agentUrl) throws A2AClientError, A2AClientJSONError {
         return getAgentCard(new JdkA2AHttpClient(), agentUrl);
     }
 
@@ -105,9 +95,10 @@ public static AgentCard getAgentCard(String agentUrl) throws A2AServerException
      * @param httpClient the http client to use
      * @param agentUrl the base URL for the agent whose agent card we want to retrieve
      * @return the agent card
-     * @throws A2AServerException if the agent card cannot be retrieved for any reason
+     * @throws A2AClientError If an HTTP error occurs fetching the card
+     * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
      */
-    public static AgentCard getAgentCard(A2AHttpClient httpClient, String agentUrl) throws A2AServerException {
+    public static AgentCard getAgentCard(A2AHttpClient httpClient, String agentUrl) throws A2AClientError, A2AClientJSONError  {
         return getAgentCard(httpClient, agentUrl, null, null);
     }
 
@@ -119,9 +110,10 @@ public static AgentCard getAgentCard(A2AHttpClient httpClient, String agentUrl)
      *                         agent URL, defaults to ".well-known/agent.json"
      * @param authHeaders the HTTP authentication headers to use
      * @return the agent card
-     * @throws A2AServerException if the agent card cannot be retrieved for any reason
+     * @throws A2AClientError If an HTTP error occurs fetching the card
+     * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
      */
-    public static AgentCard getAgentCard(String agentUrl, String relativeCardPath, Map<String, String> authHeaders) throws A2AServerException {
+    public static AgentCard getAgentCard(String agentUrl, String relativeCardPath, Map<String, String> authHeaders) throws A2AClientError, A2AClientJSONError {
         return getAgentCard(new JdkA2AHttpClient(), agentUrl, relativeCardPath, authHeaders);
     }
 
@@ -134,38 +126,12 @@ public static AgentCard getAgentCard(String agentUrl, String relativeCardPath, M
      *                         agent URL, defaults to ".well-known/agent.json"
      * @param authHeaders the HTTP authentication headers to use
      * @return the agent card
-     * @throws A2AServerException if the agent card cannot be retrieved for any reason
+     * @throws A2AClientError If an HTTP error occurs fetching the card
+     * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
      */
-    public static AgentCard getAgentCard(A2AHttpClient httpClient, String agentUrl, String relativeCardPath, Map<String, String> authHeaders) throws A2AServerException {
-        if (relativeCardPath == null || relativeCardPath.isEmpty()) {
-            relativeCardPath = AGENT_CARD_REQUEST;
-        } else {
-            if (relativeCardPath.startsWith("/")) {
-                relativeCardPath = relativeCardPath.substring(1);
-            }
-        }
-        A2AHttpClient.GetBuilder builder = httpClient.createGet()
-                .url(getRequestEndpoint(agentUrl, relativeCardPath))
-                .addHeader("Content-Type", "application/json");
-
-        if (authHeaders != null) {
-            for (Map.Entry<String, String> entry : authHeaders.entrySet()) {
-                builder.addHeader(entry.getKey(), entry.getValue());
-            }
-        }
-
-        try {
-            A2AHttpResponse response = builder.get();
-            if (!response.success()) {
-                throw new A2AServerException("Failed to obtain agent card: " + response.status());
-            }
-            String body = response.body();
-            return unmarshalFrom(body, AGENT_CARD_TYPE_REFERENCE);
-        } catch (IOException e) {
-            throw new A2AServerException("Failed to obtain agent card", e);
-        } catch (InterruptedException e) {
-            throw new A2AServerException("Timed out obtaining agent card", e);
-        }
+    public static AgentCard getAgentCard(A2AHttpClient httpClient, String agentUrl, String relativeCardPath, Map<String, String> authHeaders) throws A2AClientError, A2AClientJSONError  {
+        A2ACardResolver resolver = new A2ACardResolver(httpClient, agentUrl, relativeCardPath, authHeaders);
+        return resolver.getAgentCard();
     }
 
     protected static boolean isValidMethodName(String methodName) {
diff --git a/core/src/main/java/io/a2a/spec/A2AClientError.java b/core/src/main/java/io/a2a/spec/A2AClientError.java
@@ -7,4 +7,8 @@ public A2AClientError() {
     public A2AClientError(String message) {
         super(message);
     }
+
+    public A2AClientError(String message, Throwable cause) {
+        super(message, cause);
+    }
 }
diff --git a/core/src/main/java/io/a2a/spec/A2AClientJSONError.java b/core/src/main/java/io/a2a/spec/A2AClientJSONError.java
@@ -1,4 +1,15 @@
 package io.a2a.spec;
 
 public class A2AClientJSONError extends A2AClientError {
+
+    public A2AClientJSONError() {
+    }
+
+    public A2AClientJSONError(String message) {
+        super(message);
+    }
+
+    public A2AClientJSONError(String message, Throwable cause) {
+        super(message, cause);
+    }
 }
diff --git a/core/src/test/java/io/a2a/client/A2ACardResolverTest.java b/core/src/test/java/io/a2a/client/A2ACardResolverTest.java

Original file line number	Diff line number	Diff line change
`@@ -7,4 +7,8 @@ public A2AClientError() {`
`7`	`7`	`public A2AClientError(String message) {`
`8`	`8`	`super(message);`
`9`	`9`	`}`
	`10`	`+`
	`11`	`+ public A2AClientError(String message, Throwable cause) {`
	`12`	`+ super(message, cause);`
	`13`	`+ }`
`10`	`14`	`}`