@a2a-js/sdk 0.3.1 → 0.3.3

package/dist/client/index.d.ts

@@ -1,46 +1,39 @@
 import { ac as AgentCard, w as MessageSendParams, S as SendMessageResponse, B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, Z as TaskPushNotificationConfig, b as SetTaskPushNotificationConfigResponse, X as TaskIdParams, c as GetTaskPushNotificationConfigResponse, V as TaskQueryParams, G as GetTaskResponse, C as CancelTaskResponse, i as JSONRPCResponse, J as JSONRPCErrorResponse } from '../types-DNKcmF0f.js';
 
 type A2AStreamEventData = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+interface A2AClientOptions {
+    agentCardPath?: string;
+    fetchImpl?: typeof fetch;
+}
 /**
  * A2AClient is a TypeScript HTTP client for interacting with A2A-compliant agents.
  */
 declare class A2AClient {
-    private agentBaseUrl;
-    private agentCardPath;
     private agentCardPromise;
-    private static readonly DEFAULT_AGENT_CARD_PATH;
     private requestIdCounter;
     private serviceEndpointUrl?;
+    private 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.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 agentCardPath path to the agent card, defaults to .well-known/agent.json
+     * 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.
      */
-    constructor(agentBaseUrl: string, agentCardPath?: string);
+    constructor(agentCard: AgentCard | string, options?: 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.
-     * @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.
      */
-    private _fetchAndCacheAgentCard;
+    private _fetch;
     /**
-     * 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.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.
-     */
-    getAgentCard(agentBaseUrl?: string, agentCardPath?: string): Promise<AgentCard>;
-    /**
-     * 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.
      */
-    private _getServiceEndpoint;
+    static fromCardUrl(agentCardUrl: string, options?: A2AClientOptions): Promise<A2AClient>;
     /**
      * Helper method to make a generic JSON-RPC POST request.
      * @param method The RPC method name.
@@ -48,6 +41,14 @@ declare class A2AClient {
      * @returns A Promise that resolves to the RPC response.
      */
     private _postRpcRequest;
+    /**
+     * Internal helper method to fetch the RPC service endpoint.
+     * @param url The URL to fetch.
+     * @param rpcRequest The JSON-RPC request to send.
+     * @param acceptHeader The Accept header to use.  Defaults to "application/json".
+     * @returns A Promise that resolves to the fetch HTTP response.
+     */
+    private _fetchRpc;
     /**
      * Sends a message to the agent.
      * The behavior (blocking/non-blocking) and push notification configuration
@@ -119,6 +120,97 @@ declare class A2AClient {
      */
     private _processSseEventData;
     isErrorResponse(response: JSONRPCResponse): response is JSONRPCErrorResponse;
+    /**
+     * 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.
+     */
+    private _fetchAndCacheAgentCard;
+    /**
+   * 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.
+   */
+    getAgentCard(agentBaseUrl?: string, agentCardPath?: string): Promise<AgentCard>;
+    /**
+     * 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
+     */
+    private resolveAgentCardUrl;
+    /**
+     * 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.
+     */
+    private _getServiceEndpoint;
+}
+
+interface HttpHeaders {
+    [key: string]: string;
 }
+/**
+ * Generic interface for handling authentication for HTTP requests.
+ *
+ * - For each HTTP request, this handler is called to provide additional headers to the request through
+ *   the headers() function.
+ * - After the server returns a response, the shouldRetryWithHeaders() function is called.  Usually this
+ *   function responds to a 401 or 403 response or JSON-RPC codes, but can respond to any other signal -
+ *   that is an implementation detail of the AuthenticationHandler.
+ * - If the shouldRetryWithHeaders() function returns new headers, then the request should retried with the provided
+ *   revised headers.  These provisional headers may, or may not, be optimistically stored for subsequent requests -
+ *   that is an implementation detail of the AuthenticationHandler.
+ * - If the request is successful and the onSuccessfulRetry() is defined, then the onSuccessfulRetry() function is
+ *   called with the headers that were used to successfully complete the request.  This callback provides an
+ *   opportunity to save the headers for subsequent requests if they were not already saved.
+ *
+ */
+interface AuthenticationHandler {
+    /**
+     * Provides additional HTTP request headers.
+     * @returns HTTP headers which may include Authorization if available.
+     */
+    headers: () => Promise<HttpHeaders>;
+    /**
+     * For every HTTP response (even 200s) the shouldRetryWithHeaders() method is called.
+     * This method is supposed to check if the request needs to be retried and if, yes,
+     * return a set of headers. An A2A server might indicate auth failures in its response
+     * by JSON-rpc codes, HTTP codes like 401, 403 or headers like WWW-Authenticate.
+     *
+     * @param req The RequestInit object used to invoke fetch()
+     * @param res The fetch Response object
+     * @returns If the HTTP request should be retried then returns the HTTP headers to use,
+     * 	or returns undefined if no retry should be made.
+     */
+    shouldRetryWithHeaders: (req: RequestInit, res: Response) => Promise<HttpHeaders | undefined>;
+    /**
+     * If the last HTTP request using the headers from shouldRetryWithHeaders() was successful, and
+     * this function is implemented, then it will be called with the headers provided from
+     * shouldRetryWithHeaders().
+     *
+     * This callback allows transient headers to be saved for subsequent requests only when they
+     * are validated by the server.
+    */
+    onSuccessfulRetry?: (headers: HttpHeaders) => Promise<void>;
+}
+/**
+ * Higher-order function that wraps fetch with authentication handling logic.
+ * Returns a new fetch function that automatically handles authentication retries for 401/403 responses.
+ *
+ * @param fetchImpl The underlying fetch implementation to wrap
+ * @param authHandler Authentication handler for managing auth headers and retries
+ * @returns A new fetch function with authentication handling capabilities
+ *
+ * Usage examples:
+ * - const authFetch = createAuthHandlingFetch(fetch, authHandler);
+ * - const response = await authFetch(url, options);
+ * - const response = await authFetch(url); // Direct function call
+ */
+declare function createAuthenticatingFetchWithRetry(fetchImpl: typeof fetch, authHandler: AuthenticationHandler): typeof fetch;
 
-export { A2AClient };
+export { A2AClient, type A2AClientOptions, type AuthenticationHandler, type HttpHeaders, createAuthenticatingFetchWithRetry };

package/dist/client/index.js

@@ -1,85 +1,82 @@
+import {
+  AGENT_CARD_PATH
+} from "../chunk-67JNQ6TZ.js";
+
 // src/client/client.ts
 var A2AClient = class _A2AClient {
-  agentBaseUrl;
-  agentCardPath;
   agentCardPromise;
-  static DEFAULT_AGENT_CARD_PATH = ".well-known/agent.json";
   requestIdCounter = 1;
   serviceEndpointUrl;
   // To be populated from AgentCard after fetching
+  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.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 agentCardPath path to the agent card, defaults to .well-known/agent.json
-   */
-  constructor(agentBaseUrl, agentCardPath = _A2AClient.DEFAULT_AGENT_CARD_PATH) {
-    this.agentBaseUrl = agentBaseUrl.replace(/\/$/, "");
-    this.agentCardPath = agentCardPath.replace(/^\//, "");
-    this.agentCardPromise = this._fetchAndCacheAgentCard();
-  }
-  /**
-   * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
-   * This method is called by the constructor.
-   * @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() {
-    const agentCardUrl = `${this.agentBaseUrl}/${this.agentCardPath}`;
-    try {
-      const response = await 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();
+  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:");
-      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.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 = _A2AClient.DEFAULT_AGENT_CARD_PATH) {
-    if (agentBaseUrl) {
-      const agentCardUrl = `${agentBaseUrl.replace(/\/$/, "")}/${agentCardPath.replace(/^\//, "")}`;
-      const response = await 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();
+  _fetch(...args) {
+    if (this.customFetchImpl) {
+      return this.customFetchImpl(...args);
     }
-    return this.agentCardPromise;
+    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.
@@ -97,21 +94,15 @@ var A2AClient = class _A2AClient {
       // Cast because TParams structure varies per method
       id: requestId
     };
-    const httpResponse = await fetch(endpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Accept": "application/json"
-        // Expect JSON response for non-streaming requests
-      },
-      body: JSON.stringify(rpcRequest)
-    });
+    const httpResponse = await this._fetchRpc(endpoint, rpcRequest);
     if (!httpResponse.ok) {
       let errorBodyText = "(empty or non-JSON response)";
       try {
         errorBodyText = await httpResponse.text();
         const errorJson = JSON.parse(errorBodyText);
-        if (!errorJson.jsonrpc && errorJson.error) {
+        if (errorJson.jsonrpc && errorJson.error) {
+          return errorJson;
+        } else if (!errorJson.jsonrpc && errorJson.error) {
           throw new Error(`RPC error for ${method}: ${errorJson.error.message} (Code: ${errorJson.error.code}, HTTP Status: ${httpResponse.status}) Data: ${JSON.stringify(errorJson.error.data || {})}`);
         } else if (!errorJson.jsonrpc) {
           throw new Error(`HTTP error for ${method}! Status: ${httpResponse.status} ${httpResponse.statusText}. Response: ${errorBodyText}`);
@@ -127,6 +118,25 @@ var A2AClient = class _A2AClient {
     }
     return rpcResponse;
   }
+  /**
+   * Internal helper method to fetch the RPC service endpoint.
+   * @param url The URL to fetch.
+   * @param rpcRequest The JSON-RPC request to send.
+   * @param acceptHeader The Accept header to use.  Defaults to "application/json".
+   * @returns A Promise that resolves to the fetch HTTP response.
+   */
+  async _fetchRpc(url, rpcRequest, acceptHeader = "application/json") {
+    const requestInit = {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Accept": acceptHeader
+        // Expect JSON response for non-streaming requests
+      },
+      body: JSON.stringify(rpcRequest)
+    };
+    return this._fetch(url, requestInit);
+  }
   /**
    * Sends a message to the agent.
    * The behavior (blocking/non-blocking) and push notification configuration
@@ -161,15 +171,7 @@ var A2AClient = class _A2AClient {
       params,
       id: clientRequestId
     };
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Accept": "text/event-stream"
-        // Crucial for SSE
-      },
-      body: JSON.stringify(rpcRequest)
-    });
+    const response = await this._fetchRpc(endpoint, rpcRequest, "text/event-stream");
     if (!response.ok) {
       let errorBody = "";
       try {
@@ -253,7 +255,7 @@ var A2AClient = class _A2AClient {
       params,
       id: clientRequestId
     };
-    const response = await fetch(endpoint, {
+    const response = await this._fetch(endpoint, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -368,7 +370,122 @@ var A2AClient = class _A2AClient {
   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
+function createAuthenticatingFetchWithRetry(fetchImpl, authHandler) {
+  async function authFetch(url, init) {
+    const authHeaders = await authHandler.headers() || {};
+    const mergedInit = {
+      ...init || {},
+      headers: {
+        ...authHeaders,
+        ...init?.headers || {}
+      }
+    };
+    let response = await fetchImpl(url, mergedInit);
+    const updatedHeaders = await authHandler.shouldRetryWithHeaders(mergedInit, response);
+    if (updatedHeaders) {
+      const retryInit = {
+        ...init || {},
+        headers: {
+          ...updatedHeaders,
+          ...init?.headers || {}
+        }
+      };
+      response = await fetchImpl(url, retryInit);
+      if (response.ok && authHandler.onSuccessfulRetry) {
+        await authHandler.onSuccessfulRetry(updatedHeaders);
+      }
+    }
+    return response;
+  }
+  Object.setPrototypeOf(authFetch, Object.getPrototypeOf(fetchImpl));
+  Object.defineProperties(authFetch, Object.getOwnPropertyDescriptors(fetchImpl));
+  return authFetch;
+}
 export {
-  A2AClient
+  A2AClient,
+  createAuthenticatingFetchWithRetry
 };

package/dist/index.cjs

@@ -2,6 +2,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -14,4 +18,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/index.ts
 var index_exports = {};
+__export(index_exports, {
+  AGENT_CARD_PATH: () => AGENT_CARD_PATH
+});
 module.exports = __toCommonJS(index_exports);
+
+// src/constants.ts
+var AGENT_CARD_PATH = ".well-known/agent-card.json";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AGENT_CARD_PATH
+});

package/dist/index.d.cts

@@ -6,4 +6,12 @@ export { A as A2AError, e as A2ARequest, a9 as APIKeySecurityScheme, aa as Agent
  */
 type A2AResponse = SendMessageResponse | SendStreamingMessageResponse | GetTaskResponse | CancelTaskResponse | SetTaskPushNotificationConfigResponse | GetTaskPushNotificationConfigResponse | ListTaskPushNotificationConfigSuccessResponse | DeleteTaskPushNotificationConfigSuccessResponse | GetAuthenticatedExtendedCardSuccessResponse | JSONRPCErrorResponse;
 
-export { type A2AResponse, CancelTaskResponse, DeleteTaskPushNotificationConfigSuccessResponse, GetAuthenticatedExtendedCardSuccessResponse, GetTaskPushNotificationConfigResponse, GetTaskResponse, JSONRPCErrorResponse, ListTaskPushNotificationConfigSuccessResponse, SendMessageResponse, SendStreamingMessageResponse, SetTaskPushNotificationConfigResponse };
+/**
+ * Shared constants for the A2A library
+ */
+/**
+ * The well-known path for the agent card
+ */
+declare const AGENT_CARD_PATH = ".well-known/agent-card.json";
+
+export { type A2AResponse, AGENT_CARD_PATH, CancelTaskResponse, DeleteTaskPushNotificationConfigSuccessResponse, GetAuthenticatedExtendedCardSuccessResponse, GetTaskPushNotificationConfigResponse, GetTaskResponse, JSONRPCErrorResponse, ListTaskPushNotificationConfigSuccessResponse, SendMessageResponse, SendStreamingMessageResponse, SetTaskPushNotificationConfigResponse };

package/dist/index.d.ts

@@ -6,4 +6,12 @@ export { A as A2AError, e as A2ARequest, a9 as APIKeySecurityScheme, aa as Agent
  */
 type A2AResponse = SendMessageResponse | SendStreamingMessageResponse | GetTaskResponse | CancelTaskResponse | SetTaskPushNotificationConfigResponse | GetTaskPushNotificationConfigResponse | ListTaskPushNotificationConfigSuccessResponse | DeleteTaskPushNotificationConfigSuccessResponse | GetAuthenticatedExtendedCardSuccessResponse | JSONRPCErrorResponse;
 
-export { type A2AResponse, CancelTaskResponse, DeleteTaskPushNotificationConfigSuccessResponse, GetAuthenticatedExtendedCardSuccessResponse, GetTaskPushNotificationConfigResponse, GetTaskResponse, JSONRPCErrorResponse, ListTaskPushNotificationConfigSuccessResponse, SendMessageResponse, SendStreamingMessageResponse, SetTaskPushNotificationConfigResponse };
+/**
+ * Shared constants for the A2A library
+ */
+/**
+ * The well-known path for the agent card
+ */
+declare const AGENT_CARD_PATH = ".well-known/agent-card.json";
+
+export { type A2AResponse, AGENT_CARD_PATH, CancelTaskResponse, DeleteTaskPushNotificationConfigSuccessResponse, GetAuthenticatedExtendedCardSuccessResponse, GetTaskPushNotificationConfigResponse, GetTaskResponse, JSONRPCErrorResponse, ListTaskPushNotificationConfigSuccessResponse, SendMessageResponse, SendStreamingMessageResponse, SetTaskPushNotificationConfigResponse };

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  AGENT_CARD_PATH
+} from "./chunk-67JNQ6TZ.js";
+export {
+  AGENT_CARD_PATH
+};

package/dist/server/express/index.cjs

@@ -239,6 +239,9 @@ var JsonRpcTransportHandler = class {
   }
 };
 
+// src/constants.ts
+var AGENT_CARD_PATH = ".well-known/agent-card.json";
+
 // src/server/express/a2a_express_app.ts
 var A2AExpressApp = class {
   requestHandler;
@@ -253,12 +256,13 @@ var A2AExpressApp = class {
    * @param app Optional existing Express app.
    * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
    * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
+   * @param agentCardPath Optional custom path for the agent card endpoint (defaults to /.well-known/agent-card.json).
    * @returns The Express app with A2A routes.
    */
-  setupRoutes(app, baseUrl = "", middlewares) {
+  setupRoutes(app, baseUrl = "", middlewares, agentCardPath = AGENT_CARD_PATH) {
     const router = import_express.default.Router();
     router.use(import_express.default.json(), ...middlewares ?? []);
-    router.get("/.well-known/agent.json", async (req, res) => {
+    router.get(`/${agentCardPath}`, async (req, res) => {
       try {
         const agentCard = await this.requestHandler.getAgentCard();
         res.json(agentCard);

package/dist/server/express/index.d.cts

@@ -11,9 +11,10 @@ declare class A2AExpressApp {
      * @param app Optional existing Express app.
      * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
      * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
+     * @param agentCardPath Optional custom path for the agent card endpoint (defaults to /.well-known/agent-card.json).
      * @returns The Express app with A2A routes.
      */
-    setupRoutes(app: Express, baseUrl?: string, middlewares?: Array<RequestHandler | ErrorRequestHandler>): Express;
+    setupRoutes(app: Express, baseUrl?: string, middlewares?: Array<RequestHandler | ErrorRequestHandler>, agentCardPath?: string): Express;
 }
 
 export { A2AExpressApp };

package/dist/server/express/index.d.ts

@@ -11,9 +11,10 @@ declare class A2AExpressApp {
      * @param app Optional existing Express app.
      * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
      * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
+     * @param agentCardPath Optional custom path for the agent card endpoint (defaults to /.well-known/agent-card.json).
      * @returns The Express app with A2A routes.
      */
-    setupRoutes(app: Express, baseUrl?: string, middlewares?: Array<RequestHandler | ErrorRequestHandler>): Express;
+    setupRoutes(app: Express, baseUrl?: string, middlewares?: Array<RequestHandler | ErrorRequestHandler>, agentCardPath?: string): Express;
 }
 
 export { A2AExpressApp };