@a2a-js/sdk 0.3.2 → 0.3.3

package/dist/client/index.js

@@ -3,94 +3,80 @@ import {
 } from "../chunk-67JNQ6TZ.js";
 
 // src/client/client.ts
-var A2AClient = class {
+var A2AClient = class _A2AClient {
   agentCardPromise;
   requestIdCounter = 1;
   serviceEndpointUrl;
   // To be populated from AgentCard after fetching
-  fetchImpl;
+  customFetchImpl;
   /**
-   * Constructs an A2AClient instance.
-   * It initiates fetching the agent card from the provided agent baseUrl.
-   * The Agent Card is fetched from a path relative to the agentBaseUrl, which defaults to '.well-known/agent-card.json'.
-   * The `url` field from the Agent Card will be used as the RPC service endpoint.
-   * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
-   * @param options Optional. The options for the A2AClient including the fetch implementation, agent card path, and authentication handler.
-   */
-  constructor(agentBaseUrl, options) {
-    this.fetchImpl = options?.fetchImpl ?? fetch;
-    this.agentCardPromise = this._fetchAndCacheAgentCard(agentBaseUrl, options?.agentCardPath);
-  }
-  /**
-   * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
-   * This method is called by the constructor.
-   * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
-   * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
-   * @returns A Promise that resolves to the AgentCard.
+   * Constructs an A2AClient instance from an AgentCard.
+   * @param agentCard The AgentCard object.
+   * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
    */
-  async _fetchAndCacheAgentCard(agentBaseUrl, agentCardPath) {
-    try {
-      const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
-      const response = await this.fetchImpl(agentCardUrl, {
-        headers: { "Accept": "application/json" }
-      });
-      if (!response.ok) {
-        throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
-      }
-      const agentCard = await response.json();
+  constructor(agentCard, options) {
+    this.customFetchImpl = options?.fetchImpl;
+    if (typeof agentCard === "string") {
+      console.warn("Warning: Constructing A2AClient with a URL is deprecated. Please use A2AClient.fromCardUrl() instead.");
+      this.agentCardPromise = this._fetchAndCacheAgentCard(agentCard, options?.agentCardPath);
+    } else {
       if (!agentCard.url) {
-        throw new Error("Fetched Agent Card does not contain a valid 'url' for the service endpoint.");
+        throw new Error("Provided Agent Card does not contain a valid 'url' for the service endpoint.");
       }
       this.serviceEndpointUrl = agentCard.url;
-      return agentCard;
-    } catch (error) {
-      console.error("Error fetching or parsing Agent Card:", error);
-      throw error;
+      this.agentCardPromise = Promise.resolve(agentCard);
     }
   }
   /**
-   * Retrieves the Agent Card.
-   * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
-   * Otherwise, it returns the card fetched and cached during client construction.
-   * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
-   * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
-   * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
-   * @returns A Promise that resolves to the AgentCard.
+   * Dynamically resolves the fetch implementation to use for requests. 
+   * Prefers a custom implementation if provided, otherwise falls back to the global fetch.
+   * @returns The fetch implementation.
+   * @param args Arguments to pass to the fetch implementation.
+   * @throws If no fetch implementation is available.
    */
-  async getAgentCard(agentBaseUrl, agentCardPath) {
-    if (agentBaseUrl) {
-      const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
-      const response = await this.fetchImpl(agentCardUrl, {
-        headers: { "Accept": "application/json" }
-      });
-      if (!response.ok) {
-        throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
-      }
-      return await response.json();
+  _fetch(...args) {
+    if (this.customFetchImpl) {
+      return this.customFetchImpl(...args);
     }
-    return this.agentCardPromise;
-  }
-  /**
-   * Determines the agent card URL based on the agent URL.
-   * @param agentBaseUrl The agent URL.
-   * @param agentCardPath Optional relative path to the agent card, defaults to .well-known/agent-card.json
-   */
-  resolveAgentCardUrl(agentBaseUrl, agentCardPath = AGENT_CARD_PATH) {
-    return `${agentBaseUrl.replace(/\/$/, "")}/${agentCardPath.replace(/^\//, "")}`;
+    if (typeof fetch === "function") {
+      return fetch(...args);
+    }
+    throw new Error(
+      "A `fetch` implementation was not provided and is not available in the global scope. Please provide a `fetchImpl` in the A2AClientOptions. For earlier Node.js versions (pre-v18), you can use a library like `node-fetch`."
+    );
   }
   /**
-   * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
-   * @returns A Promise that resolves to the service endpoint URL string.
+   * Creates an A2AClient instance by fetching the AgentCard from a URL then constructing the A2AClient.
+   * @param agentCardUrl The URL of the agent card.
+   * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
+   * @returns A Promise that resolves to a new A2AClient instance.
    */
-  async _getServiceEndpoint() {
-    if (this.serviceEndpointUrl) {
-      return this.serviceEndpointUrl;
+  static async fromCardUrl(agentCardUrl, options) {
+    const fetchImpl = options?.fetchImpl;
+    const requestInit = {
+      headers: { "Accept": "application/json" }
+    };
+    let response;
+    if (fetchImpl) {
+      response = await fetchImpl(agentCardUrl, requestInit);
+    } else if (typeof fetch === "function") {
+      response = await fetch(agentCardUrl, requestInit);
+    } else {
+      throw new Error(
+        "A `fetch` implementation was not provided and is not available in the global scope. Please provide a `fetchImpl` in the A2AClientOptions. For earlier Node.js versions (pre-v18), you can use a library like `node-fetch`."
+      );
     }
-    await this.agentCardPromise;
-    if (!this.serviceEndpointUrl) {
-      throw new Error("Agent Card URL for RPC endpoint is not available. Fetching might have failed.");
+    if (!response.ok) {
+      throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
     }
-    return this.serviceEndpointUrl;
+    let agentCard;
+    try {
+      agentCard = await response.json();
+    } catch (error) {
+      console.error("Failed to parse Agent Card JSON:", error);
+      throw new Error(`Failed to parse Agent Card JSON from ${agentCardUrl}. Original error: ${error.message}`);
+    }
+    return new _A2AClient(agentCard, options);
   }
   /**
    * Helper method to make a generic JSON-RPC POST request.
@@ -149,7 +135,7 @@ var A2AClient = class {
       },
       body: JSON.stringify(rpcRequest)
     };
-    return this.fetchImpl(url, requestInit);
+    return this._fetch(url, requestInit);
   }
   /**
    * Sends a message to the agent.
@@ -269,7 +255,7 @@ var A2AClient = class {
       params,
       id: clientRequestId
     };
-    const response = await this.fetchImpl(endpoint, {
+    const response = await this._fetch(endpoint, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -384,6 +370,87 @@ var A2AClient = class {
   isErrorResponse(response) {
     return "error" in response;
   }
+  ////////////////////////////////////////////////////////////////////////////////
+  // Functions used to support old A2AClient Constructor to be deprecated soon
+  // TODOs:
+  // * remove `agentCardPromise`, and just use agentCard initialized
+  // * _getServiceEndpoint can be made synchronous or deleted and accessed via
+  //   agentCard.url
+  // * getAgentCard changed to this.agentCard
+  // * delete resolveAgentCardUrl(), _fetchAndCacheAgentCard(),
+  //   agentCardPath from A2AClientOptions
+  ////////////////////////////////////////////////////////////////////////////////
+  /**
+   * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
+   * This method is called by the constructor.
+   * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
+   * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
+   * @returns A Promise that resolves to the AgentCard.
+   */
+  async _fetchAndCacheAgentCard(agentBaseUrl, agentCardPath) {
+    try {
+      const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
+      const response = await this._fetch(agentCardUrl, {
+        headers: { "Accept": "application/json" }
+      });
+      if (!response.ok) {
+        throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
+      }
+      const agentCard = await response.json();
+      if (!agentCard.url) {
+        throw new Error("Fetched Agent Card does not contain a valid 'url' for the service endpoint.");
+      }
+      this.serviceEndpointUrl = agentCard.url;
+      return agentCard;
+    } catch (error) {
+      console.error("Error fetching or parsing Agent Card:", error);
+      throw error;
+    }
+  }
+  /**
+  * Retrieves the Agent Card.
+  * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
+  * Otherwise, it returns the card fetched and cached during client construction.
+  * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
+  * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
+  * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
+  * @returns A Promise that resolves to the AgentCard.
+  */
+  async getAgentCard(agentBaseUrl, agentCardPath) {
+    if (agentBaseUrl) {
+      const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
+      const response = await this._fetch(agentCardUrl, {
+        headers: { "Accept": "application/json" }
+      });
+      if (!response.ok) {
+        throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
+      }
+      return await response.json();
+    }
+    return this.agentCardPromise;
+  }
+  /**
+   * Determines the agent card URL based on the agent URL.
+   * @param agentBaseUrl The agent URL.
+   * @param agentCardPath Optional relative path to the agent card, defaults to .well-known/agent-card.json
+   */
+  resolveAgentCardUrl(agentBaseUrl, agentCardPath = AGENT_CARD_PATH) {
+    return `${agentBaseUrl.replace(/\/$/, "")}/${agentCardPath.replace(/^\//, "")}`;
+  }
+  /**
+   * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
+   * @returns A Promise that resolves to the service endpoint URL string.
+   */
+  async _getServiceEndpoint() {
+    if (this.serviceEndpointUrl) {
+      return this.serviceEndpointUrl;
+    }
+    await this.agentCardPromise;
+    if (!this.serviceEndpointUrl) {
+      throw new Error("Agent Card URL for RPC endpoint is not available. Fetching might have failed.");
+    }
+    return this.serviceEndpointUrl;
+  }
 };
 
 // src/client/auth-handler.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2a-js/sdk",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Server & Client SDK for Agent2Agent protocol",
   "repository": {
     "type": "git",
@@ -43,13 +43,13 @@
     "@genkit-ai/googleai": "^1.8.0",
     "@genkit-ai/vertexai": "^1.8.0",
     "@types/chai": "^5.2.2",
-    "@types/express": "^4.17.23",
+    "@types/express": "^5.0.3",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.13.14",
     "@types/sinon": "^17.0.4",
     "c8": "^10.1.3",
     "chai": "^5.2.0",
-    "express": "^4.21.2",
+    "express": "^5.1.0",
     "genkit": "^1.8.0",
     "gts": "^6.0.2",
     "json-schema-to-typescript": "^15.0.4",
@@ -73,7 +73,7 @@
     "uuid": "^11.1.0"
   },
   "peerDependencies": {
-    "express": "^4.21.2"
+    "express": "^4.21.2 || ^5.1.0"
   },
   "peerDependenciesMeta": {
     "express": {