adding dynamic agent request handler

Author: richardanaya

package.json

@@ -69,7 +69,9 @@
     "coverage": "c8 npm run test",
     "generate": "curl https://raw.githubusercontent.com/google-a2a/A2A/refs/heads/main/specification/json/a2a.json > spec.json && node scripts/generateTypes.js && rm spec.json",
     "sample:cli": "tsx src/samples/cli.ts",
-    "sample:movie-agent": "tsx src/samples/agents/movie-agent/index.ts"
+    "sample:movie-agent": "tsx src/samples/agents/movie-agent/index.ts",
+    "sample:dynamic-agents": "tsx src/samples/servers/dynamic_agents/index.ts",
+    "sample:single_agent": "tsx src/samples/servers/single_agent/index.ts"
   },
   "dependencies": {
     "uuid": "^11.1.0"

src/samples/servers/dynamic_agents/README.md

@@ -0,0 +1,98 @@
+# Dynamic Agent Server
+
+This sample demonstrates how to use `DynamicAgentRequestHandler` to create a server that can dynamically route to different agents based on the URL path.
+
+The server provides two working example agents:
+- **Calculator Agent**: Performs basic math operations like "2 + 2" or "10 * 5"  
+- **Weather Agent**: Provides fake weather data for major cities (London, Paris, Tokyo, New York, Sydney)
+
+## Running the Sample
+
+```bash
+npm run sample:dynamic-agents
+```
+
+The server will start on `http://localhost:3000`.
+
+## Available Endpoints
+
+- `GET /agents/calculator/.well-known/agent-card.json` - Calculator agent card
+- `POST /agents/calculator/` - Calculator agent messages
+- `GET /agents/weather/.well-known/agent-card.json` - Weather agent card  
+- `POST /agents/weather/` - Weather agent messages
+
+## How It Works
+
+The `DynamicAgentRequestHandler` inspects the incoming URL and dynamically determines:
+1. Which agent card to return
+2. Which task store to use
+3. Which agent executor to run
+
+This allows a single route setup (`/agents`) to handle multiple different agent behaviors without needing separate route configurations for each agent.
+
+## Testing the Agents
+
+### Using the CLI Client
+
+The easiest way to test the agents is using the built-in CLI client:
+
+```bash
+# Test the calculator agent
+npm run sample:cli -- http://localhost:3000/agents/calculator/
+# Try typing: 1 + 1
+
+# Test the weather agent  
+npm run sample:cli -- http://localhost:3000/agents/weather/
+# Try typing: whats weather in tokyo
+```
+
+### Using curl or HTTP clients
+
+You can also test the agents using curl or any HTTP client:
+
+```bash
+# Get calculator agent card
+curl http://localhost:3000/agents/calculator/.well-known/agent-card.json
+
+# Send a math problem to calculator
+curl -X POST http://localhost:3000/agents/calculator/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "sendMessage",
+    "params": {
+      "message": {
+        "messageId": "test-1",
+        "role": "user",
+        "parts": [{"kind": "text", "text": "What is 15 * 7?"}],
+        "kind": "message"
+      }
+    },
+    "id": 1
+  }'
+
+# Ask weather agent about a city
+curl -X POST http://localhost:3000/agents/weather/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "sendMessage",
+    "params": {
+      "message": {
+        "messageId": "test-2",
+        "role": "user",
+        "parts": [{"kind": "text", "text": "What is the weather in Tokyo?"}],
+        "kind": "message"
+      }
+    },
+    "id": 2
+  }'
+```
+
+## Key Benefits
+
+- **Single Route Setup**: One `setupRoutes()` call handles all agents
+- **Dynamic Routing**: URL inspection determines agent behavior  
+- **Easy Extension**: Add new agents by updating resolver functions, no new routes needed
+- **Working Examples**: Both agents actually respond to messages with proper A2A protocol
+- **Clean API**: No need for complex route configuration

src/samples/servers/dynamic_agents/index.ts

@@ -0,0 +1,198 @@
+import express from 'express';
+import { 
+    DynamicAgentRequestHandler, 
+    RouteContext
+} from '../../../server/index.js';
+import { AgentCard, Message, TextPart } from '../../../types.js';
+import { InMemoryTaskStore } from '../../../server/store.js';
+import { AgentExecutor } from '../../../server/agent_execution/agent_executor.js';
+import { A2AExpressApp } from '../../../server/express/a2a_express_app.js';
+import { RequestContext } from '../../../server/agent_execution/request_context.js';
+import { ExecutionEventBus } from '../../../server/events/execution_event_bus.js';
+import { v4 as uuidv4 } from 'uuid';
+
+// Simple agent cards for calculator and weather
+const calculatorAgentCard: AgentCard = {
+    name: 'Calculator Agent',
+    description: 'Performs mathematical calculations',
+    version: '1.0.0', 
+    protocolVersion: '2024-11-05',
+    capabilities: {
+        streaming: true,
+        pushNotifications: false,
+    },
+    defaultInputModes: [],
+    defaultOutputModes: [],
+    skills: [],
+    url: "http://localhost:3000/agents/calculator"
+};
+
+const weatherAgentCard: AgentCard = {
+    name: 'Weather Agent',
+    description: 'Provides weather information and forecasts',
+    version: '1.0.0',
+    protocolVersion: '2024-11-05',
+    capabilities: {
+        streaming: true,
+        pushNotifications: false,
+    },
+    defaultInputModes: [],
+    defaultOutputModes: [],
+    skills: [],
+    url: "http://localhost:3000/agents/weather"
+};
+
+// Calculator agent that performs basic math operations
+class CalculatorAgentExecutor implements AgentExecutor {
+    async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
+        const userMessage = requestContext.userMessage;
+        console.log(`Calculator processing: ${JSON.stringify(userMessage.parts)}`);
+        
+        // Extract text from user message
+        const textParts = userMessage.parts.filter(part => part.kind === 'text');
+        const userText = textParts.map(part => (part as TextPart).text).join(' ');
+        
+        // Simple calculation logic
+        let result: string;
+        try {
+            // Look for basic math expressions
+            const mathMatch = userText.match(/(\d+\.?\d*)\s*([\+\-\*\/])\s*(\d+\.?\d*)/);
+            if (mathMatch) {
+                const [, num1, operator, num2] = mathMatch;
+                const a = parseFloat(num1);
+                const b = parseFloat(num2);
+                
+                switch (operator) {
+                    case '+': result = `${a} + ${b} = ${a + b}`; break;
+                    case '-': result = `${a} - ${b} = ${a - b}`; break;
+                    case '*': result = `${a} × ${b} = ${a * b}`; break;
+                    case '/': result = b !== 0 ? `${a} ÷ ${b} = ${a / b}` : 'Error: Division by zero'; break;
+                    default: result = 'Unknown operation';
+                }
+            } else {
+                result = "I can help you with basic math! Try asking me something like '2 + 2' or '10 * 5'.";
+            }
+        } catch (error) {
+            result = 'Sorry, I had trouble understanding that math expression.';
+        }
+        
+        // Create response message
+        const responseMessage: Message = {
+            kind: 'message',
+            role: 'agent',
+            messageId: uuidv4(),
+            parts: [{ kind: 'text', text: result }],
+            taskId: requestContext.taskId,
+            contextId: userMessage.contextId,
+        };
+        
+        // Publish the response
+        eventBus.publish(responseMessage);
+        eventBus.finished();
+    }
+    
+    async cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void> {
+        console.log(`Canceling calculation task: ${taskId}`);
+        eventBus.finished();
+    }
+}
+
+// Weather agent that provides fake weather information
+class WeatherAgentExecutor implements AgentExecutor {
+    async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
+        const userMessage = requestContext.userMessage;
+        console.log(`Weather agent processing: ${JSON.stringify(userMessage.parts)}`);
+        
+        // Extract text from user message
+        const textParts = userMessage.parts.filter(part => part.kind === 'text');
+        const userText = textParts.map(part => (part as TextPart).text).join(' ').toLowerCase();
+        
+        // Simple weather response logic
+        let result: string;
+        const cities = ['london', 'paris', 'tokyo', 'new york', 'sydney'];
+        const foundCity = cities.find(city => userText.includes(city));
+        
+        if (foundCity) {
+            const temp = Math.floor(Math.random() * 30) + 5; // Random temp between 5-35°C
+            const conditions = ['sunny', 'cloudy', 'rainy', 'partly cloudy'][Math.floor(Math.random() * 4)];
+            result = `The weather in ${foundCity.charAt(0).toUpperCase() + foundCity.slice(1)} is currently ${temp}°C and ${conditions}. (This is fake data for demonstration purposes!)`;
+        } else {
+            result = "I can provide weather information! Try asking about the weather in London, Paris, Tokyo, New York, or Sydney.";
+        }
+        
+        // Create response message
+        const responseMessage: Message = {
+            kind: 'message',
+            role: 'agent',
+            messageId: uuidv4(),
+            parts: [{ kind: 'text', text: result }],
+            taskId: requestContext.taskId,
+            contextId: userMessage.contextId,
+        };
+        
+        // Publish the response
+        eventBus.publish(responseMessage);
+        eventBus.finished();
+    }
+    
+    async cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void> {
+        console.log(`Canceling weather task: ${taskId}`);
+        eventBus.finished();
+    }
+}
+
+// Create shared instances for persistence across requests
+const taskStore = new InMemoryTaskStore();
+const calculatorExecutor = new CalculatorAgentExecutor();
+const weatherExecutor = new WeatherAgentExecutor();
+
+// Create the dynamic request handler
+const dynamicHandler = new DynamicAgentRequestHandler(
+    // Agent card resolver - determines which agent card to use based on route
+    async (route: RouteContext) => {
+        console.log(`Resolving agent card for route: ${route.url}`);
+        
+        // For other requests, check path segments
+        if (route.url.includes('calculator')) {
+            return calculatorAgentCard;
+        } else if (route.url.includes('weather')) {
+            return weatherAgentCard;
+        }
+        
+        throw new Error("request for invalid agent");
+    },
+    
+    // Task store resolver - same store instance for all agents to ensure persistence  
+    async (route: RouteContext) => {
+        return taskStore;
+    },
+    
+    // Agent executor resolver - returns singleton instances for efficiency
+    async (route: RouteContext) => {
+        console.log(`Resolving agent executor for route: ${route.url}`);
+        
+        if (route.url.includes('calculator')) {
+            return calculatorExecutor;
+        } else if (route.url.includes('weather')) {
+            return weatherExecutor;
+        }
+        
+        throw new Error("request for invalid agent");
+    }
+);
+
+// Create the A2A Express app - dynamic routing is auto-detected from the handler
+const appBuilder = new A2AExpressApp(dynamicHandler);
+const app = appBuilder.setupRoutes(express(), '/agents');
+
+// Start the server
+const PORT = process.env.PORT || 3000;
+
+app.listen(PORT, () => {
+    console.log(`🚀 Server started on http://localhost:${PORT}`);
+    console.log('\nThe dynamic handler will route based on URL context.');
+    console.log('Try accessing different URLs to see dynamic routing in action!');
+});
+
+// That's it! Simple and clean - just like the original A2A pattern.
+// The dynamic handler inspects the request context to determine routing.

src/samples/servers/single_agent/README.md

@@ -0,0 +1,73 @@
+# Single Agent Server
+
+A simple A2A agent that demonstrates the basic agent pattern by responding "Hello World!" to any user message.
+
+## Features
+
+- **Simple Response**: Always responds with "Hello World!" regardless of user input
+- **Basic A2A Protocol**: Demonstrates core A2A agent structure
+- **No Dependencies**: Minimal setup with no external API keys or services required
+- **Single Agent**: Uses `DefaultRequestHandler` for straightforward single-agent routing
+
+## Running the Agent
+
+1. **Install dependencies** (from project root):
+   ```bash
+   npm install
+   ```
+
+2. **Start the agent**:
+   ```bash
+   npx tsx src/samples/agents/hello-world-agent/index.ts
+   ```
+
+3. **View the agent card**:
+   ```
+   http://localhost:3001/.well-known/agent-card.json
+   ```
+
+## Testing the Agent
+
+You can test the agent using any A2A client or curl:
+
+```bash
+# Send a message to the agent
+curl -X POST http://localhost:3001/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "test-1",
+    "method": "agents/chat",
+    "params": {
+      "message": {
+        "kind": "message",
+        "role": "user", 
+        "messageId": "msg-1",
+        "parts": [{"kind": "text", "text": "What is your name?"}],
+        "contextId": "ctx-1"
+      }
+    }
+  }'
+```
+
+No matter what you send, the agent will always respond with "Hello World!"
+
+## Testing the Agents
+
+### Using the CLI Client
+
+The easiest way to test the agents is using the built-in CLI client:
+
+```bash
+# Test the hello world agent
+npm run sample:cli -- http://localhost:3000/
+# Try typing anything
+```
+
+## Code Structure
+
+- **HelloWorldAgentExecutor**: Implements the core agent logic
+- **Agent Card**: Defines the agent's capabilities and metadata
+- **Express Server**: Sets up HTTP endpoints using A2AExpressApp
+
+This sample is perfect for understanding the basic A2A agent structure before building more complex agents.