@a2a-js/sdk 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +406 -315
  2. package/dist/client/index.cjs +138 -71
  3. package/dist/client/index.d.cts +45 -33
  4. package/dist/client/index.d.ts +45 -33
  5. package/dist/client/index.js +138 -71
  6. package/package.json +4 -4
package/dist/client/index.cjs CHANGED
@@ -28,94 +28,80 @@ module.exports = __toCommonJS(client_exports);
28
28
  var AGENT_CARD_PATH = ".well-known/agent-card.json";
29
29
 
30
30
  // src/client/client.ts
31
- var A2AClient = class {
31
+ var A2AClient = class _A2AClient {
32
32
  agentCardPromise;
33
33
  requestIdCounter = 1;
34
34
  serviceEndpointUrl;
35
35
  // To be populated from AgentCard after fetching
36
- fetchImpl;
36
+ customFetchImpl;
37
37
  /**
38
- * Constructs an A2AClient instance.
39
- * It initiates fetching the agent card from the provided agent baseUrl.
40
- * The Agent Card is fetched from a path relative to the agentBaseUrl, which defaults to '.well-known/agent-card.json'.
41
- * The `url` field from the Agent Card will be used as the RPC service endpoint.
42
- * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
43
- * @param options Optional. The options for the A2AClient including the fetch implementation, agent card path, and authentication handler.
44
- */
45
- constructor(agentBaseUrl, options) {
46
- this.fetchImpl = options?.fetchImpl ?? fetch;
47
- this.agentCardPromise = this._fetchAndCacheAgentCard(agentBaseUrl, options?.agentCardPath);
48
- }
49
- /**
50
- * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
51
- * This method is called by the constructor.
52
- * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
53
- * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
54
- * @returns A Promise that resolves to the AgentCard.
38
+ * Constructs an A2AClient instance from an AgentCard.
39
+ * @param agentCard The AgentCard object.
40
+ * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
55
41
  */
56
- async _fetchAndCacheAgentCard(agentBaseUrl, agentCardPath) {
57
- try {
58
- const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
59
- const response = await this.fetchImpl(agentCardUrl, {
60
- headers: { "Accept": "application/json" }
61
- });
62
- if (!response.ok) {
63
- throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
64
- }
65
- const agentCard = await response.json();
42
+ constructor(agentCard, options) {
43
+ this.customFetchImpl = options?.fetchImpl;
44
+ if (typeof agentCard === "string") {
45
+ console.warn("Warning: Constructing A2AClient with a URL is deprecated. Please use A2AClient.fromCardUrl() instead.");
46
+ this.agentCardPromise = this._fetchAndCacheAgentCard(agentCard, options?.agentCardPath);
47
+ } else {
66
48
  if (!agentCard.url) {
67
- throw new Error("Fetched Agent Card does not contain a valid 'url' for the service endpoint.");
49
+ throw new Error("Provided Agent Card does not contain a valid 'url' for the service endpoint.");
68
50
  }
69
51
  this.serviceEndpointUrl = agentCard.url;
70
- return agentCard;
71
- } catch (error) {
72
- console.error("Error fetching or parsing Agent Card:", error);
73
- throw error;
52
+ this.agentCardPromise = Promise.resolve(agentCard);
74
53
  }
75
54
  }
76
55
  /**
77
- * Retrieves the Agent Card.
78
- * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
79
- * Otherwise, it returns the card fetched and cached during client construction.
80
- * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
81
- * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
82
- * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
83
- * @returns A Promise that resolves to the AgentCard.
56
+ * Dynamically resolves the fetch implementation to use for requests.
57
+ * Prefers a custom implementation if provided, otherwise falls back to the global fetch.
58
+ * @returns The fetch implementation.
59
+ * @param args Arguments to pass to the fetch implementation.
60
+ * @throws If no fetch implementation is available.
84
61
  */
85
- async getAgentCard(agentBaseUrl, agentCardPath) {
86
- if (agentBaseUrl) {
87
- const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
88
- const response = await this.fetchImpl(agentCardUrl, {
89
- headers: { "Accept": "application/json" }
90
- });
91
- if (!response.ok) {
92
- throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
93
- }
94
- return await response.json();
62
+ _fetch(...args) {
63
+ if (this.customFetchImpl) {
64
+ return this.customFetchImpl(...args);
95
65
  }
96
- return this.agentCardPromise;
97
- }
98
- /**
99
- * Determines the agent card URL based on the agent URL.
100
- * @param agentBaseUrl The agent URL.
101
- * @param agentCardPath Optional relative path to the agent card, defaults to .well-known/agent-card.json
102
- */
103
- resolveAgentCardUrl(agentBaseUrl, agentCardPath = AGENT_CARD_PATH) {
104
- return `${agentBaseUrl.replace(/\/$/, "")}/${agentCardPath.replace(/^\//, "")}`;
66
+ if (typeof fetch === "function") {
67
+ return fetch(...args);
68
+ }
69
+ throw new Error(
70
+ "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`."
71
+ );
105
72
  }
106
73
  /**
107
- * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
108
- * @returns A Promise that resolves to the service endpoint URL string.
74
+ * Creates an A2AClient instance by fetching the AgentCard from a URL then constructing the A2AClient.
75
+ * @param agentCardUrl The URL of the agent card.
76
+ * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
77
+ * @returns A Promise that resolves to a new A2AClient instance.
109
78
  */
110
- async _getServiceEndpoint() {
111
- if (this.serviceEndpointUrl) {
112
- return this.serviceEndpointUrl;
79
+ static async fromCardUrl(agentCardUrl, options) {
80
+ const fetchImpl = options?.fetchImpl;
81
+ const requestInit = {
82
+ headers: { "Accept": "application/json" }
83
+ };
84
+ let response;
85
+ if (fetchImpl) {
86
+ response = await fetchImpl(agentCardUrl, requestInit);
87
+ } else if (typeof fetch === "function") {
88
+ response = await fetch(agentCardUrl, requestInit);
89
+ } else {
90
+ throw new Error(
91
+ "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`."
92
+ );
113
93
  }
114
- await this.agentCardPromise;
115
- if (!this.serviceEndpointUrl) {
116
- throw new Error("Agent Card URL for RPC endpoint is not available. Fetching might have failed.");
94
+ if (!response.ok) {
95
+ throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
117
96
  }
118
- return this.serviceEndpointUrl;
97
+ let agentCard;
98
+ try {
99
+ agentCard = await response.json();
100
+ } catch (error) {
101
+ console.error("Failed to parse Agent Card JSON:", error);
102
+ throw new Error(`Failed to parse Agent Card JSON from ${agentCardUrl}. Original error: ${error.message}`);
103
+ }
104
+ return new _A2AClient(agentCard, options);
119
105
  }
120
106
  /**
121
107
  * Helper method to make a generic JSON-RPC POST request.
@@ -174,7 +160,7 @@ var A2AClient = class {
174
160
  },
175
161
  body: JSON.stringify(rpcRequest)
176
162
  };
177
- return this.fetchImpl(url, requestInit);
163
+ return this._fetch(url, requestInit);
178
164
  }
179
165
  /**
180
166
  * Sends a message to the agent.
@@ -294,7 +280,7 @@ var A2AClient = class {
294
280
  params,
295
281
  id: clientRequestId
296
282
  };
297
- const response = await this.fetchImpl(endpoint, {
283
+ const response = await this._fetch(endpoint, {
298
284
  method: "POST",
299
285
  headers: {
300
286
  "Content-Type": "application/json",
@@ -409,6 +395,87 @@ var A2AClient = class {
409
395
  isErrorResponse(response) {
410
396
  return "error" in response;
411
397
  }
398
+ ////////////////////////////////////////////////////////////////////////////////
399
+ // Functions used to support old A2AClient Constructor to be deprecated soon
400
+ // TODOs:
401
+ // * remove `agentCardPromise`, and just use agentCard initialized
402
+ // * _getServiceEndpoint can be made synchronous or deleted and accessed via
403
+ // agentCard.url
404
+ // * getAgentCard changed to this.agentCard
405
+ // * delete resolveAgentCardUrl(), _fetchAndCacheAgentCard(),
406
+ // agentCardPath from A2AClientOptions
407
+ ////////////////////////////////////////////////////////////////////////////////
408
+ /**
409
+ * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
410
+ * This method is called by the constructor.
411
+ * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
412
+ * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
413
+ * @returns A Promise that resolves to the AgentCard.
414
+ */
415
+ async _fetchAndCacheAgentCard(agentBaseUrl, agentCardPath) {
416
+ try {
417
+ const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
418
+ const response = await this._fetch(agentCardUrl, {
419
+ headers: { "Accept": "application/json" }
420
+ });
421
+ if (!response.ok) {
422
+ throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
423
+ }
424
+ const agentCard = await response.json();
425
+ if (!agentCard.url) {
426
+ throw new Error("Fetched Agent Card does not contain a valid 'url' for the service endpoint.");
427
+ }
428
+ this.serviceEndpointUrl = agentCard.url;
429
+ return agentCard;
430
+ } catch (error) {
431
+ console.error("Error fetching or parsing Agent Card:", error);
432
+ throw error;
433
+ }
434
+ }
435
+ /**
436
+ * Retrieves the Agent Card.
437
+ * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
438
+ * Otherwise, it returns the card fetched and cached during client construction.
439
+ * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
440
+ * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
441
+ * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
442
+ * @returns A Promise that resolves to the AgentCard.
443
+ */
444
+ async getAgentCard(agentBaseUrl, agentCardPath) {
445
+ if (agentBaseUrl) {
446
+ const agentCardUrl = this.resolveAgentCardUrl(agentBaseUrl, agentCardPath);
447
+ const response = await this._fetch(agentCardUrl, {
448
+ headers: { "Accept": "application/json" }
449
+ });
450
+ if (!response.ok) {
451
+ throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status} ${response.statusText}`);
452
+ }
453
+ return await response.json();
454
+ }
455
+ return this.agentCardPromise;
456
+ }
457
+ /**
458
+ * Determines the agent card URL based on the agent URL.
459
+ * @param agentBaseUrl The agent URL.
460
+ * @param agentCardPath Optional relative path to the agent card, defaults to .well-known/agent-card.json
461
+ */
462
+ resolveAgentCardUrl(agentBaseUrl, agentCardPath = AGENT_CARD_PATH) {
463
+ return `${agentBaseUrl.replace(/\/$/, "")}/${agentCardPath.replace(/^\//, "")}`;
464
+ }
465
+ /**
466
+ * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
467
+ * @returns A Promise that resolves to the service endpoint URL string.
468
+ */
469
+ async _getServiceEndpoint() {
470
+ if (this.serviceEndpointUrl) {
471
+ return this.serviceEndpointUrl;
472
+ }
473
+ await this.agentCardPromise;
474
+ if (!this.serviceEndpointUrl) {
475
+ throw new Error("Agent Card URL for RPC endpoint is not available. Fetching might have failed.");
476
+ }
477
+ return this.serviceEndpointUrl;
478
+ }
412
479
  };
413
480
 
414
481
  // src/client/auth-handler.ts
package/dist/client/index.d.cts CHANGED
@@ -12,45 +12,28 @@ declare class A2AClient {
12
12
  private agentCardPromise;
13
13
  private requestIdCounter;
14
14
  private serviceEndpointUrl?;
15
- private fetchImpl;
15
+ private customFetchImpl?;
16
16
  /**
17
- * Constructs an A2AClient instance.
18
- * It initiates fetching the agent card from the provided agent baseUrl.
19
- * The Agent Card is fetched from a path relative to the agentBaseUrl, which defaults to '.well-known/agent-card.json'.
20
- * The `url` field from the Agent Card will be used as the RPC service endpoint.
21
- * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
22
- * @param options Optional. The options for the A2AClient including the fetch implementation, agent card path, and authentication handler.
17
+ * Constructs an A2AClient instance from an AgentCard.
18
+ * @param agentCard The AgentCard object.
19
+ * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
23
20
  */
24
- constructor(agentBaseUrl: string, options?: A2AClientOptions);
21
+ constructor(agentCard: AgentCard | string, options?: A2AClientOptions);
25
22
  /**
26
- * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
27
- * This method is called by the constructor.
28
- * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
29
- * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
30
- * @returns A Promise that resolves to the AgentCard.
23
+ * Dynamically resolves the fetch implementation to use for requests.
24
+ * Prefers a custom implementation if provided, otherwise falls back to the global fetch.
25
+ * @returns The fetch implementation.
26
+ * @param args Arguments to pass to the fetch implementation.
27
+ * @throws If no fetch implementation is available.
31
28
  */
32
- private _fetchAndCacheAgentCard;
29
+ private _fetch;
33
30
  /**
34
- * Retrieves the Agent Card.
35
- * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
36
- * Otherwise, it returns the card fetched and cached during client construction.
37
- * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
38
- * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
39
- * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
40
- * @returns A Promise that resolves to the AgentCard.
31
+ * Creates an A2AClient instance by fetching the AgentCard from a URL then constructing the A2AClient.
32
+ * @param agentCardUrl The URL of the agent card.
33
+ * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
34
+ * @returns A Promise that resolves to a new A2AClient instance.
41
35
  */
42
- getAgentCard(agentBaseUrl?: string, agentCardPath?: string): Promise<AgentCard>;
43
- /**
44
- * Determines the agent card URL based on the agent URL.
45
- * @param agentBaseUrl The agent URL.
46
- * @param agentCardPath Optional relative path to the agent card, defaults to .well-known/agent-card.json
47
- */
48
- private resolveAgentCardUrl;
49
- /**
50
- * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
51
- * @returns A Promise that resolves to the service endpoint URL string.
52
- */
53
- private _getServiceEndpoint;
36
+ static fromCardUrl(agentCardUrl: string, options?: A2AClientOptions): Promise<A2AClient>;
54
37
  /**
55
38
  * Helper method to make a generic JSON-RPC POST request.
56
39
  * @param method The RPC method name.
@@ -137,6 +120,35 @@ declare class A2AClient {
137
120
  */
138
121
  private _processSseEventData;
139
122
  isErrorResponse(response: JSONRPCResponse): response is JSONRPCErrorResponse;
123
+ /**
124
+ * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
125
+ * This method is called by the constructor.
126
+ * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
127
+ * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
128
+ * @returns A Promise that resolves to the AgentCard.
129
+ */
130
+ private _fetchAndCacheAgentCard;
131
+ /**
132
+ * Retrieves the Agent Card.
133
+ * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
134
+ * Otherwise, it returns the card fetched and cached during client construction.
135
+ * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
136
+ * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
137
+ * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
138
+ * @returns A Promise that resolves to the AgentCard.
139
+ */
140
+ getAgentCard(agentBaseUrl?: string, agentCardPath?: string): Promise<AgentCard>;
141
+ /**
142
+ * Determines the agent card URL based on the agent URL.
143
+ * @param agentBaseUrl The agent URL.
144
+ * @param agentCardPath Optional relative path to the agent card, defaults to .well-known/agent-card.json
145
+ */
146
+ private resolveAgentCardUrl;
147
+ /**
148
+ * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
149
+ * @returns A Promise that resolves to the service endpoint URL string.
150
+ */
151
+ private _getServiceEndpoint;
140
152
  }
141
153
 
142
154
  interface HttpHeaders {
package/dist/client/index.d.ts CHANGED
@@ -12,45 +12,28 @@ declare class A2AClient {
12
12
  private agentCardPromise;
13
13
  private requestIdCounter;
14
14
  private serviceEndpointUrl?;
15
- private fetchImpl;
15
+ private customFetchImpl?;
16
16
  /**
17
- * Constructs an A2AClient instance.
18
- * It initiates fetching the agent card from the provided agent baseUrl.
19
- * The Agent Card is fetched from a path relative to the agentBaseUrl, which defaults to '.well-known/agent-card.json'.
20
- * The `url` field from the Agent Card will be used as the RPC service endpoint.
21
- * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
22
- * @param options Optional. The options for the A2AClient including the fetch implementation, agent card path, and authentication handler.
17
+ * Constructs an A2AClient instance from an AgentCard.
18
+ * @param agentCard The AgentCard object.
19
+ * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
23
20
  */
24
- constructor(agentBaseUrl: string, options?: A2AClientOptions);
21
+ constructor(agentCard: AgentCard | string, options?: A2AClientOptions);
25
22
  /**
26
- * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
27
- * This method is called by the constructor.
28
- * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
29
- * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
30
- * @returns A Promise that resolves to the AgentCard.
23
+ * Dynamically resolves the fetch implementation to use for requests.
24
+ * Prefers a custom implementation if provided, otherwise falls back to the global fetch.
25
+ * @returns The fetch implementation.
26
+ * @param args Arguments to pass to the fetch implementation.
27
+ * @throws If no fetch implementation is available.
31
28
  */
32
- private _fetchAndCacheAgentCard;
29
+ private _fetch;
33
30
  /**
34
- * Retrieves the Agent Card.
35
- * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
36
- * Otherwise, it returns the card fetched and cached during client construction.
37
- * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
38
- * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
39
- * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
40
- * @returns A Promise that resolves to the AgentCard.
31
+ * Creates an A2AClient instance by fetching the AgentCard from a URL then constructing the A2AClient.
32
+ * @param agentCardUrl The URL of the agent card.
33
+ * @param options Optional. The options for the A2AClient including the fetch/auth implementation.
34
+ * @returns A Promise that resolves to a new A2AClient instance.
41
35
  */
42
- getAgentCard(agentBaseUrl?: string, agentCardPath?: string): Promise<AgentCard>;
43
- /**
44
- * Determines the agent card URL based on the agent URL.
45
- * @param agentBaseUrl The agent URL.
46
- * @param agentCardPath Optional relative path to the agent card, defaults to .well-known/agent-card.json
47
- */
48
- private resolveAgentCardUrl;
49
- /**
50
- * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
51
- * @returns A Promise that resolves to the service endpoint URL string.
52
- */
53
- private _getServiceEndpoint;
36
+ static fromCardUrl(agentCardUrl: string, options?: A2AClientOptions): Promise<A2AClient>;
54
37
  /**
55
38
  * Helper method to make a generic JSON-RPC POST request.
56
39
  * @param method The RPC method name.
@@ -137,6 +120,35 @@ declare class A2AClient {
137
120
  */
138
121
  private _processSseEventData;
139
122
  isErrorResponse(response: JSONRPCResponse): response is JSONRPCErrorResponse;
123
+ /**
124
+ * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
125
+ * This method is called by the constructor.
126
+ * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com)
127
+ * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
128
+ * @returns A Promise that resolves to the AgentCard.
129
+ */
130
+ private _fetchAndCacheAgentCard;
131
+ /**
132
+ * Retrieves the Agent Card.
133
+ * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
134
+ * Otherwise, it returns the card fetched and cached during client construction.
135
+ * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
136
+ * @param agentCardPath path to the agent card, defaults to .well-known/agent-card.json
137
+ * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
138
+ * @returns A Promise that resolves to the AgentCard.
139
+ */
140
+ getAgentCard(agentBaseUrl?: string, agentCardPath?: string): Promise<AgentCard>;
141
+ /**
142
+ * Determines the agent card URL based on the agent URL.
143
+ * @param agentBaseUrl The agent URL.
144
+ * @param agentCardPath Optional relative path to the agent card, defaults to .well-known/agent-card.json
145
+ */
146
+ private resolveAgentCardUrl;
147
+ /**
148
+ * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
149
+ * @returns A Promise that resolves to the service endpoint URL string.
150
+ */
151
+ private _getServiceEndpoint;
140
152
  }
141
153
 
142
154
  interface HttpHeaders {