docs: update docs for 0.3.6 (#246)

# Description

1. Update README.md, sample agents and sample CLI to use new APIs
introduced in #162 (extract middlewares from `A2AExpressApp`) and #198
(transport-agnostic client).
2. Mark `A2AExpressApp` and `A2AClient` as deprecated.
3. Ensure samples and TCK import via index files only to "test" that all
required types are exported.
4.  Consolidate all `@example` tags to use ` ```ts `.

Author: ishymko

README.md

@@ -45,29 +45,33 @@ The core of an A2A server is the `AgentExecutor`, which contains your agent's lo
 // server.ts
 import express from 'express';
 import { v4 as uuidv4 } from 'uuid';
-import type { AgentCard, Message } from '@a2a-js/sdk';
+import { AgentCard, Message, AGENT_CARD_PATH } from '@a2a-js/sdk';
 import {
   AgentExecutor,
   RequestContext,
   ExecutionEventBus,
   DefaultRequestHandler,
   InMemoryTaskStore,
 } from '@a2a-js/sdk/server';
-import { A2AExpressApp } from '@a2a-js/sdk/server/express';
+import { agentCardHandler, jsonRpcHandler, restHandler, UserBuilder } from '@a2a-js/sdk/server/express';
 
 // 1. Define your agent's identity card.
 const helloAgentCard: AgentCard = {
   name: 'Hello Agent',
   description: 'A simple agent that says hello.',
   protocolVersion: '0.3.0',
   version: '0.1.0',
-  url: 'http://localhost:4000/', // The public URL of your agent server
+  url: 'http://localhost:4000/a2a/jsonrpc', // The public URL of your agent server
   skills: [{ id: 'chat', name: 'Chat', description: 'Say hello', tags: ['chat'] }],
   capabilities: {
     pushNotifications: false,
   },
   defaultInputModes: ['text'],
   defaultOutputModes: ['text'],
+  additionalInterfaces: [
+    { url: 'http://localhost:4000/a2a/jsonrpc', transport: 'JSONRPC' }, // Default JSON-RPC transport
+    { url: 'http://localhost:4000/a2a/rest', transport: 'HTTP+JSON' }, // HTTP+JSON/REST transport
+  ],
 };
 
 // 2. Implement the agent's logic.
@@ -100,27 +104,33 @@ const requestHandler = new DefaultRequestHandler(
   agentExecutor
 );
 
-const appBuilder = new A2AExpressApp(requestHandler);
-const expressApp = appBuilder.setupRoutes(express());
+const app = express();
 
-expressApp.listen(4000, () => {
+app.use(`/${AGENT_CARD_PATH}`, agentCardHandler({ agentCardProvider: requestHandler }));
+app.use('/a2a/jsonrpc', jsonRpcHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+app.use('/a2a/rest', restHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+
+app.listen(4000, () => {
   console.log(`🚀 Server started on http://localhost:4000`);
 });
 ```
 
 ### Client: Sending a Message
 
-The `A2AClient` makes it easy to communicate with any A2A-compliant agent.
+The [`ClientFactory`](src/client/factory.ts) makes it easy to communicate with any A2A-compliant agent.
 
 ```typescript
 // client.ts
-import { A2AClient, SendMessageSuccessResponse } from '@a2a-js/sdk/client';
+import { ClientFactory, SendMessageSuccessResponse } from '@a2a-js/sdk/client';
 import { Message, MessageSendParams } from '@a2a-js/sdk';
 import { v4 as uuidv4 } from 'uuid';
 
 async function run() {
-  // Create a client pointing to the agent's Agent Card URL.
-  const client = await A2AClient.fromCardUrl('http://localhost:4000/.well-known/agent-card.json');
+  const factory = new ClientFactory();
+
+  // createFromUrl accepts baseUrl and optional path,
+  // (the default path is /.well-known/agent-card.json)
+  const client = await factory.createFromUrl('http://localhost:4000');
 
   const sendParams: MessageSendParams = {
     message: {
@@ -131,13 +141,12 @@ async function run() {
     },
   };
 
-  const response = await client.sendMessage(sendParams);
-
-  if ('error' in response) {
-    console.error('Error:', response.error.message);
-  } else {
-    const result = (response as SendMessageSuccessResponse).result as Message;
+  try {
+    const response = await client.sendMessage(sendParams);
+    const result = response as Message;
     console.log('Agent response:', result.parts[0].text); // "Hello, world!"
+  } catch(e) {
+    console.error('Error:', e);
   }
 }
 
@@ -213,25 +222,25 @@ The client sends a message and receives a `Task` object as the result.
 
 ```typescript
 // client.ts
-import { A2AClient, SendMessageSuccessResponse } from '@a2a-js/sdk/client';
+import { ClientFactory, SendMessageSuccessResponse } from '@a2a-js/sdk/client';
 import { Message, MessageSendParams, Task } from '@a2a-js/sdk';
 // ... other imports ...
 
-const client = await A2AClient.fromCardUrl('http://localhost:4000/.well-known/agent-card.json');
+const factory = new ClientFactory();
 
-const response = await client.sendMessage({
-  message: {
-    messageId: uuidv4(),
-    role: 'user',
-    parts: [{ kind: 'text', text: 'Do something.' }],
-    kind: 'message',
-  },
-});
+// createFromUrl accepts baseUrl and optional path,
+// (the default path is /.well-known/agent-card.json)
+const client = await factory.createFromUrl('http://localhost:4000');
 
-if ('error' in response) {
-  console.error('Error:', response.error.message);
-} else {
-  const result = (response as SendMessageSuccessResponse).result;
+try {
+  const result = await client.sendMessage({
+    message: {
+      messageId: uuidv4(),
+      role: 'user',
+      parts: [{ kind: 'text', text: 'Do something.' }],
+      kind: 'message',
+    },
+  });
 
   // Check if the agent's response is a Task or a direct Message.
   if (result.kind === 'task') {
@@ -246,45 +255,58 @@ if ('error' in response) {
     const message = result as Message;
     console.log('Received direct message:', message.parts[0].text);
   }
+} catch (e) {
+  console.error('Error:', e);
 }
 ```
 
 ---
 
 ## Client Customization
 
-You can provide a custom `fetch` implementation to the `A2AClient` to modify its HTTP request behavior. Common use cases include:
+Client can be customized via [`CallInterceptor`'s](src/client/interceptors.ts) which is a recommended way as it's transport-agnostic.
+
+Common use cases include:
 
 - **Request Interception**: Log outgoing requests or collect metrics.
 - **Header Injection**: Add custom headers for authentication, tracing, or routing.
-- **Retry Mechanisms**: Implement custom logic for retrying failed requests.
+- **A2A Extensions**: Modifying payloads to include protocol extension data.
 
 ### Example: Injecting a Custom Header
 
-This example creates a `fetch` wrapper that adds a unique `X-Request-ID` to every outgoing request.
+This example defines a `CallInterceptor` to update `serviceParameters` which are passed as HTTP headers.
 
 ```typescript
-import { A2AClient } from '@a2a-js/sdk/client';
 import { v4 as uuidv4 } from 'uuid';
+import { AfterArgs, BeforeArgs, CallInterceptor, ClientFactory, ClientFactoryOptions } from '@a2a-js/sdk/client';
+
+// 1. Define an interceptor
+class RequestIdInterceptor implements CallInterceptor {
+  before(args: BeforeArgs): Promise<void> {
+    args.options = {
+      ...args.options,
+      serviceParameters: {
+        ...args.options.serviceParameters,
+        ['X-Request-ID']: uuidv4(),
+      },
+    };
+    return Promise.resolve();
+  }
 
-// 1. Create a wrapper around the global fetch function.
-const fetchWithCustomHeader: typeof fetch = async (url, init) => {
-  const headers = new Headers(init?.headers);
-  headers.set('X-Request-ID', uuidv4());
-
-  const newInit = { ...init, headers };
-
-  console.log(`Sending request to ${url} with X-Request-ID: ${headers.get('X-Request-ID')}`);
-
-  return fetch(url, newInit);
-};
+  after(): Promise<void> {
+    return Promise.resolve();
+  }
+}
 
-// 2. Provide the custom fetch implementation to the client.
-const client = await A2AClient.fromCardUrl('http://localhost:4000/.well-known/agent-card.json', {
-  fetchImpl: fetchWithCustomHeader,
-});
+// 2. Register the interceptor in the client factory
+const factory = new ClientFactory(ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+  clientConfig: {
+    interceptors: [new RequestIdInterceptor()]
+  }
+}))
+const client = await factory.createFromAgentCardUrl('http://localhost:4000');
 
-// Now, all requests made by this client instance will include the X-Request-ID header.
+// Now, all requests made by clients created by this factory will include the X-Request-ID header.
 await client.sendMessage({
   message: {
     messageId: uuidv4(),
@@ -297,41 +319,43 @@ await client.sendMessage({
 
 ### Example: Specifying a Timeout
 
-This example creates a `fetch` wrapper that sets a timeout for every outgoing request.
+Each client method can be configured with an optional `signal` field.
 
 ```typescript
-import { A2AClient } from '@a2a-js/sdk/client';
+import { ClientFactory } from '@a2a-js/sdk/client';
 
-// 1. Create a wrapper around the global fetch function.
-const fetchWithTimeout: typeof fetch = async (url, init) => {
-  return fetch(url, { ...init, signal: AbortSignal.timeout(5000) });
-};
+const factory = new ClientFactory();
 
-// 2. Provide the custom fetch implementation to the client.
-const client = await A2AClient.fromCardUrl('http://localhost:4000/.well-known/agent-card.json', {
-  fetchImpl: fetchWithTimeout,
-});
+// createFromUrl accepts baseUrl and optional path,
+// (the default path is /.well-known/agent-card.json)
+const client = await factory.createFromUrl('http://localhost:4000');
 
-// Now, all requests made by this client instance will have a configured timeout.
-await client.sendMessage({
-  message: {
-    messageId: uuidv4(),
-    role: 'user',
-    parts: [{ kind: 'text', text: 'A message requiring custom headers.' }],
-    kind: 'message',
+await client.sendMessage(
+  {
+    message: {
+      messageId: uuidv4(),
+      role: 'user',
+      parts: [{ kind: 'text', text: 'A long-running message.' }],
+      kind: 'message',
+    },
   },
-});
+  {
+    signal: AbortSignal.timeout(5000), // 5 seconds timeout
+  }
+);
 ```
 
-### Using the Provided `AuthenticationHandler`
+### Customizing Transports: Using the Provided `AuthenticationHandler`
 
 For advanced authentication scenarios, the SDK includes a higher-order function `createAuthenticatingFetchWithRetry` and an `AuthenticationHandler` interface. This utility automatically adds authorization headers and can retry requests that fail with authentication errors (e.g., 401 Unauthorized).
 
 Here's how to use it to manage a Bearer token:
 
 ```typescript
 import {
-  A2AClient,
+  ClientFactory,
+  ClientFactoryOptions
+  JsonRpcTransportFactory,
   AuthenticationHandler,
   createAuthenticatingFetchWithRetry,
 } from '@a2a-js/sdk/client';
@@ -371,10 +395,15 @@ const handler: AuthenticationHandler = {
 // 2. Create the authenticated fetch function.
 const authFetch = createAuthenticatingFetchWithRetry(fetch, handler);
 
-// 3. Initialize the client with the new fetch implementation.
-const client = await A2AClient.fromCardUrl('http://localhost:4000/.well-known/agent-card.json', {
-  fetchImpl: authFetch,
-});
+// 3. Inject new fetch implementation into a client factory.
+const factory = new ClientFactory(ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+  transports: [
+    new JsonRpcTransportFactory({ fetchImpl: authFetch })
+  ]
+}))
+
+// 4. Clients created from the factory are going to have custom fetch attached.
+const client = await factory.createFromUrl('http://localhost:4000');
 ```
 
 ---
@@ -448,12 +477,16 @@ The `sendMessageStream` method returns an `AsyncGenerator` that yields events as
 
 ```typescript
 // client.ts
-import { A2AClient } from '@a2a-js/sdk/client';
+import { ClientFactory } from '@a2a-js/sdk/client';
 import { MessageSendParams } from '@a2a-js/sdk';
 import { v4 as uuidv4 } from 'uuid';
 // ... other imports ...
 
-const client = await A2AClient.fromCardUrl('http://localhost:4000/.well-known/agent-card.json');
+const factory = new ClientFactory();
+
+// createFromUrl accepts baseUrl and optional path,
+// (the default path is /.well-known/agent-card.json)
+const client = await factory.createFromUrl('http://localhost:4000');
 
 async function streamTask() {
   const streamParams: MessageSendParams = {

src/client/client.ts

@@ -37,6 +37,7 @@ export interface A2AClientOptions {
 /**
  * A2AClient is a TypeScript HTTP client for interacting with A2A-compliant agents.
  * Only JSON-RPC transport is supported.
+ * @deprecated Use {@link ClientFactory}
  */
 export class A2AClient {
   private static emptyOptions?: RequestOptions = undefined;

src/samples/agents/movie-agent/index.ts

@@ -8,6 +8,7 @@ import {
   TaskStatusUpdateEvent,
   TextPart,
   Message,
+  AGENT_CARD_PATH,
 } from '../../../index.js';
 import {
   InMemoryTaskStore,
@@ -17,7 +18,7 @@ import {
   ExecutionEventBus,
   DefaultRequestHandler,
 } from '../../../server/index.js';
-import { A2AExpressApp } from '../../../server/express/index.js';
+import { agentCardHandler, jsonRpcHandler, UserBuilder } from '../../../server/express/index.js';
 import { MessageData } from 'genkit';
 import { ai } from './genkit.js';
 import { searchMovies, searchPeople } from './tools.js';
@@ -247,8 +248,7 @@ class MovieAgentExecutor implements AgentExecutor {
 const movieAgentCard: AgentCard = {
   name: 'Movie Agent',
   description: 'An agent that can answer questions about movies and actors using TMDB.',
-  // Adjust the base URL and port as needed. /a2a is the default base in A2AExpressApp
-  url: 'http://localhost:41241/', // Example: if baseUrl in A2AExpressApp
+  url: 'http://localhost:41241/',
   provider: {
     organization: 'A2A Samples',
     url: 'https://example.com/a2a-samples', // Added provider URL
@@ -296,13 +296,15 @@ async function main() {
   // 3. Create DefaultRequestHandler
   const requestHandler = new DefaultRequestHandler(movieAgentCard, taskStore, agentExecutor);
 
-  // 4. Create and setup A2AExpressApp
-  const appBuilder = new A2AExpressApp(requestHandler);
-  const expressApp = appBuilder.setupRoutes(express());
+  // 4. Create and setup Express.js app
+  const app = express();
+
+  app.use(`/${AGENT_CARD_PATH}`, agentCardHandler({ agentCardProvider: requestHandler }));
+  app.use(jsonRpcHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
 
   // 5. Start the server
   const PORT = process.env.PORT || 41241;
-  expressApp.listen(PORT, (err) => {
+  app.listen(PORT, (err) => {
     if (err) {
       throw err;
     }