@a2a-js/sdk 0.2.2 → 0.2.3

package/README.md

@@ -28,19 +28,21 @@ You can also find JavaScript samples [here](https://github.com/google-a2a/a2a-sa
 This directory contains a TypeScript server implementation for the Agent-to-Agent (A2A) communication protocol, built using Express.js.
 
 ### 1. Define Agent Card
+
 ```typescript
-import { AgentCard } from "@a2a-js/sdk";
+import type { AgentCard } from "@a2a-js/sdk";
 
 const movieAgentCard: AgentCard = {
-  name: 'Movie Agent',
-  description: 'An agent that can answer questions about movies and actors using TMDB.',
+  name: "Movie Agent",
+  description:
+    "An agent that can answer questions about movies and actors using TMDB.",
   // Adjust the base URL and port as needed.
-  url: 'http://localhost:41241/',
+  url: "http://localhost:41241/",
   provider: {
-    organization: 'A2A Agents',
-    url: 'https://example.com/a2a-agents' // Added provider URL
+    organization: "A2A Agents",
+    url: "https://example.com/a2a-agents", // Added provider URL
   },
-  version: '0.0.2', // Incremented version
+  version: "0.0.2", // Incremented version
   capabilities: {
     streaming: true, // Supports streaming
     pushNotifications: false, // Assuming not implemented for this agent yet
@@ -48,24 +50,25 @@ const movieAgentCard: AgentCard = {
   },
   securitySchemes: undefined, // Or define actual security schemes if any
   security: undefined,
-  defaultInputModes: ['text/plain'],
-  defaultOutputModes: ['text/plain'],
+  defaultInputModes: ["text/plain"],
+  defaultOutputModes: ["text/plain"],
   skills: [
     {
-      id: 'general_movie_chat',
-      name: 'General Movie Chat',
-      description: 'Answer general questions or chat about movies, actors, directors.',
-      tags: ['movies', 'actors', 'directors'],
+      id: "general_movie_chat",
+      name: "General Movie Chat",
+      description:
+        "Answer general questions or chat about movies, actors, directors.",
+      tags: ["movies", "actors", "directors"],
       examples: [
-        'Tell me about the plot of Inception.',
-        'Recommend a good sci-fi movie.',
-        'Who directed The Matrix?',
-        'What other movies has Scarlett Johansson been in?',
-        'Find action movies starring Keanu Reeves',
-        'Which came out first, Jurassic Park or Terminator 2?',
+        "Tell me about the plot of Inception.",
+        "Recommend a good sci-fi movie.",
+        "Who directed The Matrix?",
+        "What other movies has Scarlett Johansson been in?",
+        "Find action movies starring Keanu Reeves",
+        "Which came out first, Jurassic Park or Terminator 2?",
       ],
-      inputModes: ['text/plain'], // Explicitly defining for skill
-      outputModes: ['text/plain'] // Explicitly defining for skill
+      inputModes: ["text/plain"], // Explicitly defining for skill
+      outputModes: ["text/plain"], // Explicitly defining for skill
     },
   ],
   supportsAuthenticatedExtendedCard: false,
@@ -73,6 +76,7 @@ const movieAgentCard: AgentCard = {
 ```
 
 ### 2. Define Agent Executor
+
 ```typescript
 import {
   InMemoryTaskStore,
@@ -82,19 +86,19 @@ import {
   RequestContext,
   ExecutionEventBus,
   DefaultRequestHandler,
-} from "@a2a-js/sdk";
+} from "@a2a-js/sdk/server";
 
 // 1. Define your agent's logic as a AgentExecutor
 class MyAgentExecutor implements AgentExecutor {
   private cancelledTasks = new Set<string>();
 
   public cancelTask = async (
-        taskId: string,
-        eventBus: ExecutionEventBus,
-    ): Promise<void> => {
-        this.cancelledTasks.add(taskId);
-        // The execute loop is responsible for publishing the final state
-    };
+    taskId: string,
+    eventBus: ExecutionEventBus
+  ): Promise<void> => {
+    this.cancelledTasks.add(taskId);
+    // The execute loop is responsible for publishing the final state
+  };
 
   async execute(
     requestContext: RequestContext,
@@ -114,11 +118,11 @@ class MyAgentExecutor implements AgentExecutor {
     // 1. Publish initial Task event if it's a new task
     if (!existingTask) {
       const initialTask: Task = {
-        kind: 'task',
+        kind: "task",
         id: taskId,
         contextId: contextId,
         status: {
-          state: 'submitted',
+          state: "submitted",
           timestamp: new Date().toISOString(),
         },
         history: [userMessage],
@@ -130,16 +134,16 @@ class MyAgentExecutor implements AgentExecutor {
 
     // 2. Publish "working" status update
     const workingStatusUpdate: TaskStatusUpdateEvent = {
-      kind: 'status-update',
+      kind: "status-update",
       taskId: taskId,
       contextId: contextId,
       status: {
-        state: 'working',
+        state: "working",
         message: {
-          kind: 'message',
-          role: 'agent',
+          kind: "message",
+          role: "agent",
           messageId: uuidv4(),
-          parts: [{ kind: 'text', text: 'Generating code...' }],
+          parts: [{ kind: "text", text: "Generating code..." }],
           taskId: taskId,
           contextId: contextId,
         },
@@ -156,11 +160,11 @@ class MyAgentExecutor implements AgentExecutor {
     if (this.cancelledTasks.has(taskId)) {
       console.log(`[MyAgentExecutor] Request cancelled for task: ${taskId}`);
       const cancelledUpdate: TaskStatusUpdateEvent = {
-        kind: 'status-update',
+        kind: "status-update",
         taskId: taskId,
         contextId: contextId,
         status: {
-          state: 'canceled',
+          state: "canceled",
           timestamp: new Date().toISOString(),
         },
         final: true,
@@ -172,7 +176,7 @@ class MyAgentExecutor implements AgentExecutor {
 
     // 3. Publish artifact update
     const artifactUpdate: TaskArtifactUpdateEvent = {
-      kind: 'artifact-update',
+      kind: "artifact-update",
       taskId: taskId,
       contextId: contextId,
       artifact: {
@@ -187,14 +191,14 @@ class MyAgentExecutor implements AgentExecutor {
 
     // 4. Publish final status update
     const finalUpdate: TaskStatusUpdateEvent = {
-      kind: 'status-update',
+      kind: "status-update",
       taskId: taskId,
       contextId: contextId,
       status: {
-        state: 'completed',
+        state: "completed",
         message: {
-          kind: 'message',
-          role: 'agent',
+          kind: "message",
+          role: "agent",
           messageId: uuidv4(),
           taskId: taskId,
           contextId: contextId,
@@ -210,6 +214,7 @@ class MyAgentExecutor implements AgentExecutor {
 ```
 
 ### 3. Start the server
+
 ```typescript
 const taskStore: TaskStore = new InMemoryTaskStore();
 const agentExecutor: AgentExecutor = new MyAgentExecutor();
@@ -221,19 +226,26 @@ const requestHandler = new DefaultRequestHandler(
 );
 
 const appBuilder = new A2AExpressApp(requestHandler);
-const expressApp = appBuilder.setupRoutes(express(), '');
+const expressApp = appBuilder.setupRoutes(express(), "");
 
 const PORT = process.env.CODER_AGENT_PORT || 41242; // Different port for coder agent
 expressApp.listen(PORT, () => {
-  console.log(`[MyAgent] Server using new framework started on http://localhost:${PORT}`);
-  console.log(`[MyAgent] Agent Card: http://localhost:${PORT}/.well-known/agent.json`);
-  console.log('[MyAgent] Press Ctrl+C to stop the server');
+  console.log(
+    `[MyAgent] Server using new framework started on http://localhost:${PORT}`
+  );
+  console.log(
+    `[MyAgent] Agent Card: http://localhost:${PORT}/.well-known/agent.json`
+  );
+  console.log("[MyAgent] Press Ctrl+C to stop the server");
 });
 ```
+
 ### Agent Executor
+
 Developers are expected to implement this interface and provide two methods: `execute` and `cancelTask`.
 
 #### `execute`
+
 - This method is provided with a `RequestContext` and an `EventBus` to publish execution events.
 - Executor can either respond by publishing a Message or Task.
 - For a task, check if there's an existing task in `RequestContext`. If not, publish an initial Task event using `taskId` & `contextId` from `RequestContext`.
@@ -242,9 +254,10 @@ Developers are expected to implement this interface and provide two methods: `ex
 - Executor should also check if an ongoing task has been cancelled. If yes, cancel the execution and emit an `TaskStatusUpdateEvent` with cancelled state.
 
 #### `cancelTask`
+
 Executors should implement cancellation mechanism for an ongoing task.
 
-## A2A Client 
+## A2A Client
 
 There's a `A2AClient` class, which provides methods for interacting with an A2A server over HTTP using JSON-RPC.
 
@@ -259,8 +272,8 @@ There's a `A2AClient` class, which provides methods for interacting with an A2A
 ### Basic Usage
 
 ```typescript
-import {
-  A2AClient,
+import { A2AClient } from "@a2a-js/sdk/client";
+import type {
   Message,
   MessageSendParams,
   Task,
@@ -268,7 +281,7 @@ import {
   SendMessageResponse,
   GetTaskResponse,
   SendMessageSuccessResponse,
-  GetTaskSuccessResponse
+  GetTaskSuccessResponse,
 } from "@a2a-js/sdk";
 import { v4 as uuidv4 } from "uuid";
 
@@ -285,50 +298,50 @@ async function run() {
         messageId: messageId,
         role: "user",
         parts: [{ kind: "text", text: "Hello, agent!" }],
-        kind: "message"
+        kind: "message",
       },
       configuration: {
         blocking: true,
-        acceptedOutputModes: ['text/plain']
-      }
+        acceptedOutputModes: ["text/plain"],
+      },
     };
-    
-    const sendResponse: SendMessageResponse = await client.sendMessage(sendParams);
+
+    const sendResponse: SendMessageResponse =
+      await client.sendMessage(sendParams);
 
     if (sendResponse.error) {
-        console.error("Error sending message:", sendResponse.error);
-        return;
+      console.error("Error sending message:", sendResponse.error);
+      return;
     }
 
     // On success, the result can be a Task or a Message. Check which one it is.
     const result = (sendResponse as SendMessageSuccessResponse).result;
 
-    if (result.kind === 'task') {
-        // The agent created a task.
-        const taskResult = result as Task;
-        console.log("Send Message Result (Task):", taskResult);
-        taskId = taskResult.id; // Save the task ID for the next call
-    } else if (result.kind === 'message') {
-        // The agent responded with a direct message.
-        const messageResult = result as Message;
-        console.log("Send Message Result (Direct Message):", messageResult);
-        // No task was created, so we can't get task status.
+    if (result.kind === "task") {
+      // The agent created a task.
+      const taskResult = result as Task;
+      console.log("Send Message Result (Task):", taskResult);
+      taskId = taskResult.id; // Save the task ID for the next call
+    } else if (result.kind === "message") {
+      // The agent responded with a direct message.
+      const messageResult = result as Message;
+      console.log("Send Message Result (Direct Message):", messageResult);
+      // No task was created, so we can't get task status.
     }
 
     // 2. If a task was created, get its status.
     if (taskId) {
-        const getParams: TaskQueryParams = { id: taskId };
-        const getResponse: GetTaskResponse = await client.getTask(getParams);
+      const getParams: TaskQueryParams = { id: taskId };
+      const getResponse: GetTaskResponse = await client.getTask(getParams);
 
-        if (getResponse.error) {
-            console.error(`Error getting task ${taskId}:`, getResponse.error);
-            return;
-        }
-        
-        const getTaskResult = (getResponse as GetTaskSuccessResponse).result;
-        console.log("Get Task Result:", getTaskResult);
-    }
+      if (getResponse.error) {
+        console.error(`Error getting task ${taskId}:`, getResponse.error);
+        return;
+      }
 
+      const getTaskResult = (getResponse as GetTaskSuccessResponse).result;
+      console.log("Get Task Result:", getTaskResult);
+    }
   } catch (error) {
     console.error("A2A Client Communication Error:", error);
   }
@@ -340,8 +353,8 @@ run();
 ### Streaming Usage
 
 ```typescript
-import {
-  A2AClient,
+import { A2AClient } from "@a2a-js/sdk/client";
+import type {
   TaskStatusUpdateEvent,
   TaskArtifactUpdateEvent,
   MessageSendParams,
@@ -356,31 +369,33 @@ async function streamTask() {
   const messageId = uuidv4();
   try {
     console.log(`\n--- Starting streaming task for message ${messageId} ---`);
-    
+
     // Construct the `MessageSendParams` object.
     const streamParams: MessageSendParams = {
       message: {
         messageId: messageId,
         role: "user",
         parts: [{ kind: "text", text: "Stream me some updates!" }],
-        kind: "message"
+        kind: "message",
       },
     };
-    
+
     // Use the `sendMessageStream` method.
     const stream = client.sendMessageStream(streamParams);
     let currentTaskId: string | undefined;
 
     for await (const event of stream) {
       // The first event is often the Task object itself, establishing the ID.
-      if ((event as Task).kind === 'task') {
-          currentTaskId = (event as Task).id;
-          console.log(`[${currentTaskId}] Task created. Status: ${(event as Task).status.state}`);
-          continue;
+      if ((event as Task).kind === "task") {
+        currentTaskId = (event as Task).id;
+        console.log(
+          `[${currentTaskId}] Task created. Status: ${(event as Task).status.state}`
+        );
+        continue;
       }
-      
+
       // Differentiate subsequent stream events.
-      if ((event as TaskStatusUpdateEvent).kind === 'status-update') {
+      if ((event as TaskStatusUpdateEvent).kind === "status-update") {
         const statusEvent = event as TaskStatusUpdateEvent;
         console.log(
           `[${statusEvent.taskId}] Status Update: ${statusEvent.status.state} - ${
@@ -391,7 +406,9 @@ async function streamTask() {
           console.log(`[${statusEvent.taskId}] Stream marked as final.`);
           break; // Exit loop when server signals completion
         }
-      } else if ((event as TaskArtifactUpdateEvent).kind === 'artifact-update') {
+      } else if (
+        (event as TaskArtifactUpdateEvent).kind === "artifact-update"
+      ) {
         const artifactEvent = event as TaskArtifactUpdateEvent;
         // Use artifact.name or artifact.artifactId for identification
         console.log(

package/package.json

@@ -1,17 +1,34 @@
 {
   "name": "@a2a-js/sdk",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Server & Client SDK for Agent2Agent protocol",
   "repository": "google-a2a/a2a-js.git",
   "engines": {
     "node": ">=18"
   },
-  "main": "build/src/index.js",
-  "types": "build/src/index.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.cjs"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "require": "./dist/client/index.cjs"
+    }
+  },
   "files": [
-    "build/src",
-    "!build/src/**/*.map",
+    "dist",
+    "!dist/**/*.map",
     "README.md"
   ],
   "devDependencies": {
@@ -28,12 +45,13 @@
     "json-schema-to-typescript": "^15.0.4",
     "mocha": "^11.6.0",
     "sinon": "^20.0.0",
+    "tsup": "^8.5.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2"
   },
   "scripts": {
     "clean": "gts clean",
-    "build": "tsc -p .",
+    "build": "tsup",
     "pretest": "npm run build",
     "test": "mocha build/test/**/*.js",
     "coverage": "c8 npm run test",
@@ -43,7 +61,7 @@
   },
   "dependencies": {
     "@types/cors": "^2.8.17",
-    "@types/express": "^5.0.1",
+    "@types/express": "^4.17.23",
     "body-parser": "^2.2.0",
     "cors": "^2.8.5",
     "express": "^4.21.2",

package/build/src/a2a_response.d.ts

@@ -1,5 +0,0 @@
-import { SendMessageResponse, SendStreamingMessageResponse, GetTaskResponse, CancelTaskResponse, SetTaskPushNotificationConfigResponse, GetTaskPushNotificationConfigResponse, JSONRPCErrorResponse } from "./types.js";
-/**
- * Represents any valid JSON-RPC response defined in the A2A protocol.
- */
-export type A2AResponse = SendMessageResponse | SendStreamingMessageResponse | GetTaskResponse | CancelTaskResponse | SetTaskPushNotificationConfigResponse | GetTaskPushNotificationConfigResponse | JSONRPCErrorResponse;

package/build/src/a2a_response.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=a2a_response.js.map

package/build/src/client/client.d.ts

@@ -1,118 +0,0 @@
-import { AgentCard, JSONRPCResponse, JSONRPCErrorResponse, Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, MessageSendParams, SendMessageResponse, TaskQueryParams, GetTaskResponse, TaskIdParams, CancelTaskResponse, TaskPushNotificationConfig, SetTaskPushNotificationConfigResponse, GetTaskPushNotificationConfigResponse } from '../types.js';
-type A2AStreamEventData = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
-/**
- * A2AClient is a TypeScript HTTP client for interacting with A2A-compliant agents.
- */
-export declare class A2AClient {
-    private agentBaseUrl;
-    private agentCardPromise;
-    private requestIdCounter;
-    private serviceEndpointUrl?;
-    /**
-     * Constructs an A2AClient instance.
-     * It initiates fetching the agent card from the provided agent baseUrl.
-     * The Agent Card is expected at `${agentBaseUrl}/.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).
-     */
-    constructor(agentBaseUrl: string);
-    /**
-     * 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.
-     */
-    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.
-     * 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): 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.
-     */
-    private _getServiceEndpoint;
-    /**
-     * Helper method to make a generic JSON-RPC POST request.
-     * @param method The RPC method name.
-     * @param params The parameters for the RPC method.
-     * @returns A Promise that resolves to the RPC response.
-     */
-    private _postRpcRequest;
-    /**
-     * Sends a message to the agent.
-     * The behavior (blocking/non-blocking) and push notification configuration
-     * are specified within the `params.configuration` object.
-     * Optionally, `params.message.contextId` or `params.message.taskId` can be provided.
-     * @param params The parameters for sending the message, including the message content and configuration.
-     * @returns A Promise resolving to SendMessageResponse, which can be a Message, Task, or an error.
-     */
-    sendMessage(params: MessageSendParams): Promise<SendMessageResponse>;
-    /**
-     * Sends a message to the agent and streams back responses using Server-Sent Events (SSE).
-     * Push notification configuration can be specified in `params.configuration`.
-     * Optionally, `params.message.contextId` or `params.message.taskId` can be provided.
-     * Requires the agent to support streaming (`capabilities.streaming: true` in AgentCard).
-     * @param params The parameters for sending the message.
-     * @returns An AsyncGenerator yielding A2AStreamEventData (Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent).
-     * The generator throws an error if streaming is not supported or if an HTTP/SSE error occurs.
-     */
-    sendMessageStream(params: MessageSendParams): AsyncGenerator<A2AStreamEventData, void, undefined>;
-    /**
-     * Sets or updates the push notification configuration for a given task.
-     * Requires the agent to support push notifications (`capabilities.pushNotifications: true` in AgentCard).
-     * @param params Parameters containing the taskId and the TaskPushNotificationConfig.
-     * @returns A Promise resolving to SetTaskPushNotificationConfigResponse.
-     */
-    setTaskPushNotificationConfig(params: TaskPushNotificationConfig): Promise<SetTaskPushNotificationConfigResponse>;
-    /**
-     * Gets the push notification configuration for a given task.
-     * @param params Parameters containing the taskId.
-     * @returns A Promise resolving to GetTaskPushNotificationConfigResponse.
-     */
-    getTaskPushNotificationConfig(params: TaskIdParams): Promise<GetTaskPushNotificationConfigResponse>;
-    /**
-     * Retrieves a task by its ID.
-     * @param params Parameters containing the taskId and optional historyLength.
-     * @returns A Promise resolving to GetTaskResponse, which contains the Task object or an error.
-     */
-    getTask(params: TaskQueryParams): Promise<GetTaskResponse>;
-    /**
-     * Cancels a task by its ID.
-     * @param params Parameters containing the taskId.
-     * @returns A Promise resolving to CancelTaskResponse, which contains the updated Task object or an error.
-     */
-    cancelTask(params: TaskIdParams): Promise<CancelTaskResponse>;
-    /**
-     * Resubscribes to a task's event stream using Server-Sent Events (SSE).
-     * This is used if a previous SSE connection for an active task was broken.
-     * Requires the agent to support streaming (`capabilities.streaming: true` in AgentCard).
-     * @param params Parameters containing the taskId.
-     * @returns An AsyncGenerator yielding A2AStreamEventData (Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent).
-     */
-    resubscribeTask(params: TaskIdParams): AsyncGenerator<A2AStreamEventData, void, undefined>;
-    /**
-     * Parses an HTTP response body as an A2A Server-Sent Event stream.
-     * Each 'data' field of an SSE event is expected to be a JSON-RPC 2.0 Response object,
-     * specifically a SendStreamingMessageResponse (or similar structure for resubscribe).
-     * @param response The HTTP Response object whose body is the SSE stream.
-     * @param originalRequestId The ID of the client's JSON-RPC request that initiated this stream.
-     * Used to validate the `id` in the streamed JSON-RPC responses.
-     * @returns An AsyncGenerator yielding the `result` field of each valid JSON-RPC success response from the stream.
-     */
-    private _parseA2ASseStream;
-    /**
-     * Processes a single SSE event's data string, expecting it to be a JSON-RPC response.
-     * @param jsonData The string content from one or more 'data:' lines of an SSE event.
-     * @param originalRequestId The ID of the client's request that initiated the stream.
-     * @returns The `result` field of the parsed JSON-RPC success response.
-     * @throws Error if data is not valid JSON, not a valid JSON-RPC response, an error response, or ID mismatch.
-     */
-    private _processSseEventData;
-    isErrorResponse(response: JSONRPCResponse): response is JSONRPCErrorResponse;
-}
-export {};