@a2a-js/sdk 0.2.2 → 0.2.4

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(