Strands A2A Demo

This demo showcases multiple AI agents using the complete official A2A (agent-to-agent) Python SDK patterns from google-a2a/a2a-samples. The agents use the Strands Agents Python SDK for their LLM implementation, fully integrated with the official A2A SDK patterns.

About A2A Protocol: The A2A (Agent-to-Agent) Protocol was originally developed by Google and is now being transitioned to the Linux Foundation to ensure open governance and broad industry adoption for multi-agent AI systems.

📋 Implementation Note: This project currently uses the official A2A Python SDK directly alongside Strands Agents SDK. It does not use the new native A2A support that may be available in newer versions of Strands Agents. This approach demonstrates how to integrate both SDKs manually for maximum control and compatibility with official A2A patterns.

This project features a unified a2a-client with multiple modes of operation, including web-based UI, voice interaction capabilities, and comprehensive testing.

🏗️ Agent Architecture

This system features two distinct types of agents, both configurable through config/config.toml:

🔧 Individual Agents (configurable_agent)

Specialized agents that perform specific tasks using tools:

• Strands Tools: Built-in capabilities like calculator, current_time, file_read, file_write, editor
• MCP Servers: External integrations via Model Context Protocol (e.g., web fetch, file systems)
• Direct Communication: Can be contacted directly by clients
• Focused Expertise: Each agent specializes in a particular domain

Examples: Calculator agent (math operations), Time agent (timezone queries), File Editor agent (file operations), Web Browser agent (content fetching)

🌀 Coordinator Agents (coordinator_agent)

Meta-agents that orchestrate multiple individual agents:

• No Direct Tools: Don't use Strands tools or MCP servers directly
• Agent Delegation: Route requests to appropriate individual agents
• Workflow Management: Handle complex multi-step operations across agents
• Intelligent Routing: Analyze requests to determine which specialist agent(s) to use

Examples: Time & Calculator coordinator (manages math and time requests), Edit & Browse coordinator (manages file and web operations)

🔄 How They Work Together

User Request → Coordinator Agent → Individual Agent(s) → Tools/MCP → Results → User

Both types are automatically discovered and can be used through any client interface (web, CLI, voice).

📋 Table of Contents

• Quick Start
• A2A Client Modes Overview
• Complete Tutorial
• Architecture Overview
• Configuration Guide
• Agent Management
• Troubleshooting
• API Reference

🚀 Quick Start

Prerequisites

• Python 3.12+
• UV package manager (extremely fast Python package manager)

Install UV if you don't have it:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or visit: https://docs.astral.sh/uv/getting-started/installation/

Installation

# Clone the repository
git clone <repository-url>
cd strands-a2a-demo

# Install dependencies with UV
uv sync

Start All Agents

# Start all configured agents (recommended)
uv run a2a-client agents start

# Wait for agents to be ready, then use the client
uv run a2a-client web

Open http://localhost:8080 in your browser and start chatting with your agents!

🖥️ A2A Client Modes Overview

The a2a-client provides five distinct modes for interacting with A2A agents:

Mode	Command	Purpose	Best For
web	uv run a2a-client web	Modern browser-based UI	General use, demos, development
interactive	uv run a2a-client interactive	Command-line chat interface	Quick testing, scripting
speak	uv run a2a-client speak --agent <name>	CLI voice interaction	Voice testing, accessibility
webspeak	uv run a2a-client webspeak	Browser-based voice UI	Voice demos, user-friendly voice
test	uv run a2a-client test	Comprehensive test suite	Validation, CI/CD, debugging

📖 Complete Tutorial

Tutorial 1: Web Interface (Recommended for Beginners)

The web interface is the most user-friendly way to interact with A2A agents.

Step 1: Start the Agents

# Start all configured agents
uv run agents start

# Verify agents are running
uv run agents status

You should see output like:

✅ calculator (port 8001): Running (PID: 12345)
✅ time (port 8002): Running (PID: 12346)
✅ fileeditor (port 8003): Running (PID: 12347)
✅ webbrowser (port 8004): Running (PID: 12348)
✅ time-and-calculator (port 8005): Running (PID: 12349)
✅ edit-and-browse (port 8006): Running (PID: 12350)

Step 2: Launch Web Interface

# Start the web interface (default port 8080)
uv run a2a-client web

# Or specify a custom port
uv run a2a-client web --port 3000 --host 0.0.0.0

Step 3: Use the Interface

1. Open http://localhost:8080 in your browser
2. You'll see a list of available agents with their capabilities
3. Select an agent from the dropdown
4. Type your message and press Enter or click Send
5. Watch real-time responses appear in the chat

Example Conversations:

👤 User: "What's 25 * 47?"
🤖 Calculator: "25 × 47 = 1,175"

👤 User: "What time is it in Tokyo?"
🤖 Time: "The current time in Tokyo is 2:30 PM JST (Japan Standard Time)"

👤 User: "Create a file called hello.txt with 'Hello World'"
🤖 File Editor: "✅ Created file hello.txt with content: 'Hello World'"

Tutorial 2: Interactive CLI Mode

Perfect for developers and command-line users.

Basic Usage

# Start interactive mode
uv run a2a-client interactive

# Start with a specific agent
uv run a2a-client interactive --agent calculator

# Use task-based communication (with push notifications)
uv run a2a-client interactive --use-tasks

Step-by-Step Walkthrough:

# 1. Start interactive mode
uv run a2a-client interactive

# You'll see:
🎭 A2A Interactive Mode (Messages)
==================================================
📋 Available Agents:
  • calculator: Mathematical calculation specialist
  • time: Time and timezone information specialist
  ...

# 2. Select an agent by typing its name
Select an agent (or 'list' to see all, 'quit' to exit): calculator

# 3. Chat with the agent
💬 Chat with calculator (type 'back' to change agents, 'quit' to exit)
You: What's the square root of 144?

🤖 calculator: The square root of 144 is 12.

You: Calculate 15% tip on $50.75
🤖 calculator: 15% tip on $50.75 is $7.61. Total with tip: $58.36

Advanced CLI Features:

# Send a single message and exit
uv run a2a-client interactive --agent calculator --send "What's 100 * 25?"

# Use asynchronous tasks (better for complex operations)
uv run a2a-client interactive --use-tasks --agent fileeditor

Tutorial 3: Voice Interaction (Speak Mode)

Voice interaction using Amazon Nova Sonic for speech-to-text and text-to-speech.

Prerequisites:

• AWS credentials configured (for Nova Sonic)
• Audio input/output devices

Setup AWS Credentials:

# Option 1: AWS CLI
aws configure

# Option 2: Environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

# Option 3: IAM role (for EC2 instances)
# No additional setup needed

Using Speak Mode:

# Start voice interaction with an agent
uv run a2a-client speak --agent calculator

# Disable echo cancellation if using headphones
uv run a2a-client speak --agent time --disable-echo-cancellation

Voice Interaction Flow:

1. Start speaking - The system listens for your voice
2. Speech-to-text - Your speech is converted to text using Nova Sonic
3. Agent processing - The agent processes your request
4. Text-to-speech - The response is converted to speech
5. Audio playback - You hear the agent's response

Example Voice Session:

🎤 Voice mode started with calculator
🔊 Say something to the agent (press Ctrl+C to exit)

[You speak]: "What is twenty five times forty seven?"
📝 Transcription: "What is 25 times 47?"
🤖 calculator: "25 times 47 equals 1,175"
🔊 [Audio plays]: "Twenty five times forty seven equals one thousand one hundred seventy five"

Tutorial 4: WebSpeak Interface

Browser-based voice interaction - combines the convenience of the web interface with voice capabilities.

Starting WebSpeak:

# Start WebSpeak interface (default port 3000)
uv run a2a-client webspeak

# Custom port and host
uv run a2a-client webspeak --port 8090 --host 0.0.0.0

Using WebSpeak:

1. Open http://localhost:3000 in your browser
2. Allow microphone permissions when prompted
3. Select an agent from the dropdown
4. Click the microphone button to start speaking
5. See real-time transcription and responses
6. Hear audio responses automatically

WebSpeak Features:

• Real-time transcription - See your speech converted to text
• Visual feedback - Watch the conversation flow in the browser
• Agent switching - Change agents without restarting
• Audio controls - Mute, volume control, playback speed
• WebRTC processing - Client-side audio processing for better quality

Tutorial 5: Testing Mode

Comprehensive testing suite to validate all agent functionality.

Basic Testing:

# Test all agents
uv run a2a-client test

# Test specific agent
uv run a2a-client test --agent calculator
uv run a2a-client test --agent time-and-calculator

Test Types Performed:

1. Agent Discovery - Verify agents are reachable and respond
2. Skill Detection - Check agent capabilities and skill descriptions
3. Message Communication - Test immediate request/response
4. Task Communication - Test asynchronous tasks with push notifications
5. Coordinator Testing - Test agent-to-agent delegation

Sample Test Output:

🧪 A2A Client Test Suite
========================

🔍 Discovering agents...
✅ Found 6 agents: calculator, time, fileeditor, webbrowser, time-and-calculator, edit-and-browse

🎯 Testing agent skills and descriptions...
✅ calculator: Advanced mathematical calculation agent
   Skills: calculate (Perform mathematical calculations and solve equations)
✅ time: Accurate time and timezone information agent  
   Skills: get_current_time (Get current time and timezone information)

📨 Testing message communication...
✅ calculator: Responded to 'What is 12 * 8?' with '12 × 8 = 96'
✅ time: Responded to 'What time is it?' with 'Current time: 2:30 PM EST'

🚀 Testing task communication with push notifications...
✅ calculator: Task completed with result: '√144 = 12'
✅ time: Task completed with result: 'Current UTC time: 19:30:15'

📊 Test Summary:
   • Agent Discovery: ✅ 6/6 passed
   • Message Tests: ✅ 6/6 passed  
   • Task Tests: ✅ 6/6 passed
   • Push Notifications: ✅ 6/6 passed

🏗️ Architecture Overview

System Architecture

graph TB
    subgraph "Client Layer"
        WEB[Web Interface<br/>Port 8080]
        CLI[Interactive CLI]
        VOICE[Voice Interface]
        WEBSPEAK[WebSpeak Interface<br/>Port 3000]
        TEST[Test Suite]
    end
    
    subgraph "A2A Client Core"
        A2ACLIENT[A2A Client<br/>CleanA2AClient]
        WEBHOOK[Webhook Manager<br/>Port 8000]
        DISCOVERY[Agent Discovery]
    end
    
    subgraph "Coordinator Agents"
        COORD1[Time & Calculator<br/>Coordinator<br/>Port 8005]
        COORD2[Edit & Browse<br/>Coordinator<br/>Port 8006]
    end
    
    subgraph "Individual Agents"
        CALC[Calculator Agent<br/>Port 8001<br/>Strands Tools]
        TIME[Time Agent<br/>Port 8002<br/>Strands Tools]
        FILE[File Editor Agent<br/>Port 8003<br/>Strands Tools]
        WEB_AGENT[Web Browser Agent<br/>Port 8004<br/>MCP Server]
    end
    
    subgraph "External Services"
        NOVA[Amazon Nova<br/>Speech Services]
        MCP[MCP Servers<br/>fetch, filesystem]
        STRANDS[Strands Tools<br/>calculator, time, file_ops]
    end
    
    WEB --> A2ACLIENT
    CLI --> A2ACLIENT
    VOICE --> A2ACLIENT
    WEBSPEAK --> A2ACLIENT
    TEST --> A2ACLIENT
    
    A2ACLIENT --> WEBHOOK
    A2ACLIENT --> DISCOVERY
    
    A2ACLIENT --> COORD1
    A2ACLIENT --> COORD2
    A2ACLIENT --> CALC
    A2ACLIENT --> TIME
    A2ACLIENT --> FILE
    A2ACLIENT --> WEB_AGENT
    
    COORD1 --> CALC
    COORD1 --> TIME
    COORD2 --> FILE
    COORD2 --> WEB_AGENT
    
    VOICE --> NOVA
    WEBSPEAK --> NOVA
    
    WEB_AGENT --> MCP
    CALC --> STRANDS
    TIME --> STRANDS
    FILE --> STRANDS

Architecture Components

Client Layer

• Web Interface: Modern browser-based UI with real-time WebSocket communication
• Interactive CLI: Command-line interface for direct agent interaction
• Voice Interface: CLI-based voice interaction using Amazon Nova
• WebSpeak Interface: Browser-based voice interaction with WebRTC
• Test Suite: Comprehensive testing framework for all agents

A2A Client Core

• CleanA2AClient: Core A2A SDK integration with connection management
• Webhook Manager: Handles push notifications for asynchronous tasks
• Agent Discovery: Dynamic discovery of available agents and their capabilities

Agent Types

• Individual Agents: Specialized agents for specific tasks
• Coordinator Agents: Meta-agents that delegate tasks to individual agents

Integration Points

• Strands Tools: Native Python tools for calculator, time, and file operations
• MCP Servers: Model Context Protocol servers for external integrations
• Amazon Nova: Speech-to-text and text-to-speech services

A2A Task Webhook Sequence

sequenceDiagram
    participant Client as A2A Client
    participant Webhook as Webhook Manager<br/>(Port 8000)
    participant Agent as A2A Agent<br/>(Port 800X)
    participant Nova as Amazon Nova<br/>(Speech Services)
    
    Note over Client,Nova: Task Creation & Push Notification Setup
    
    Client->>Webhook: 1. Start webhook server
    Webhook-->>Client: Server started
    
    Client->>Agent: 2. Send task request
    Agent-->>Client: Task created (ID: task-123)
    
    Client->>Agent: 3. Register push notification
    Note right of Client: POST /api/a2a/tasks/task-123/push-config<br/>{"url": "http://localhost:8000/webhook/a2a-tasks"}
    Agent-->>Client: Push notification registered
    
    Note over Client,Nova: Asynchronous Task Processing
    
    Agent->>Agent: 4. Process task asynchronously
    Note right of Agent: Agent uses Strands tools<br/>or MCP servers
    
    Agent->>Webhook: 5. Push notification
    Note right of Agent: POST /webhook/a2a-tasks<br/>Complete Task object with result
    
    Webhook->>Client: 6. Execute callback
    Client-->>Webhook: Callback executed
    
    Note over Client,Nova: Voice Mode Additional Steps (if applicable)
    
    opt Voice Mode
        Client->>Nova: 7. Text-to-speech
        Nova-->>Client: Audio response
        Client->>Client: 8. Play audio
    end
    
    Webhook->>Webhook: 9. Cleanup task tracking

Message vs Task Communication

Message Communication (Synchronous)

sequenceDiagram
    participant Client as A2A Client
    participant Agent as A2A Agent
    
    Client->>Agent: Send message request
    Agent->>Agent: Process immediately
    Agent-->>Client: Return response
    Note right of Client: Best for: Simple queries,<br/>immediate responses

Task Communication (Asynchronous)

sequenceDiagram
    participant Client as A2A Client
    participant Agent as A2A Agent
    participant Webhook as Webhook Server
    
    Client->>Agent: Send task request
    Agent-->>Client: Return task ID immediately
    
    Client->>Agent: Register push notification
    Agent->>Agent: Process task asynchronously
    Agent->>Webhook: Send task completion
    Webhook->>Client: Execute callback
    Note right of Client: Best for: Complex operations,<br/>long-running tasks

Agent Coordination Flow

graph TD
    A[User Request] --> B{Coordinator Agent}
    B --> C[Analyze Request]
    C --> D{Determine Specialist}
    D --> E[Calculator Agent]
    D --> F[Time Agent]
    D --> G[File Editor Agent]
    D --> H[Web Browser Agent]
    E --> I[Return Result]
    F --> I
    G --> I
    H --> I
    I --> J[Format Response]
    J --> K[Return to User]

⚙️ Configuration Guide

Configuration File Structure

All agents are configured through config/config.toml. This single file defines:

• Agent types and capabilities
• Port assignments
• Tool integrations
• Coordinator relationships

Basic Structure

[logging]
level = "INFO"
log_directory = "./logs"

[webhook]
port = 8000
host = "0.0.0.0"

[web_interface]
port = 8080
host = "0.0.0.0"
webspeak_port = 8081

[agents]
model = "us.amazon.nova-lite-v1:0"

# Individual agents
[configurable_agent.agent_name]
# ... agent configuration

# Coordinator agents  
[coordinator_agent.coordinator_name]
# ... coordinator configuration

Individual Agent Configuration

[configurable_agent.myagent]
description = "Description of what this agent does"
port = 8001                                    # Unique port number
system_prompt = "You are a helpful assistant..."
strands_tools = ["calculator", "current_time"] # Optional Strands tools

# Optional MCP server integrations
[configurable_agent.myagent.mcp_servers]
fetch = { command = "uvx", args = ["mcp-server-fetch"] }

Required Fields:

• description: Human-readable description
• port: Unique port number (8001-8099 recommended for individual agents)
• system_prompt: Agent behavior definition

Optional Fields:

• strands_tools: Array of Strands tool names
• mcp_servers: MCP server configurations

Coordinator Agent Configuration

[coordinator_agent.mycoordinator]
description = "Coordinator that manages specific agents"
port = 8000
system_prompt = "You are a coordinator agent..."
coordinated_agents = ["agent1", "agent2"]  # Agents this coordinator manages

Available Strands Tools

Tool	Purpose	Example Use
calculator	Mathematical calculations	"What's 25 * 47?"
current_time	Time and timezone info	"What time is it in Tokyo?"
editor	File editing with changes	"Edit line 5 of config.py"
file_read	Advanced file reading	"Read the contents of README.md"
file_write	File writing operations	"Create a new Python script"

MCP Server Integration

MCP (Model Context Protocol) servers extend agent capabilities:

[configurable_agent.webbrowser.mcp_servers]
fetch = { command = "uvx", args = ["mcp-server-fetch"] }
filesystem = { command = "mcp-server-filesystem", args = ["/path/to/root"] }

Common MCP servers:

• fetch: Web content retrieval
• filesystem: File system operations
• sqlite: Database interactions
• brave-search: Web search capabilities

Port Management Strategy

Recommended Port Ranges:

• 8001-8099: Individual configurable agents
• 8000, 8100-8199: Coordinator agents
• 8000: Webhook server (fixed)
• 8080: Web interface (default)
• 3000: WebSpeak interface (default)

Port Conflict Resolution:

# Check what's using a port
lsof -i :8001

# Force start agents (kills existing processes)
uv run agents start --force

Example Complete Configuration

[logging]
level = "INFO"
log_directory = "./logs"

[webhook]
port = 8000
host = "0.0.0.0"

[agents]
model = "us.amazon.nova-lite-v1:0"

# Specialized math agent
[configurable_agent.calculator]
description = "Advanced mathematical calculation specialist"
port = 8001
system_prompt = "You are a precise calculator. Solve problems step by step."
strands_tools = ["calculator"]

[configurable_agent.calculator.mcp_servers]

# Web research agent
[configurable_agent.researcher]
description = "Web research and content analysis specialist"
port = 8004
system_prompt = "You are a research assistant. Find and analyze web content."
strands_tools = []

[configurable_agent.researcher.mcp_servers]
fetch = { command = "uvx", args = ["mcp-server-fetch"] }
brave_search = { command = "uvx", args = ["mcp-server-brave-search"] }

# Multi-purpose coordinator
[coordinator_agent.assistant]
description = "General purpose coordinator for math and research"
port = 8000
system_prompt = "You coordinate between math and research specialists."
coordinated_agents = ["calculator", "researcher"]

🔧 Agent Management

Starting and Stopping Agents

Start All Agents (Recommended)

# Start all configured agents with dependency ordering
uv run agents start

# Force start (kills existing processes on ports)
uv run agents start --force

Start Individual Agents

# Start specific configurable agent
uv run agents start calculator
uv run agents start time
uv run agents start fileeditor

# Start specific coordinator
uv run agents start time-and-calculator
uv run agents start edit-and-browse

Stop Agents

# Stop all agents
uv run agents stop

# Stop specific agent
uv run agents stop calculator
uv run agents stop time-and-calculator

Restart Agents

# Restart all agents
uv run agents restart

# Restart specific agent
uv run agents restart calculator

Check Agent Status

# Check all agents
uv run agents status

# Check specific agent
uv run agents status calculator

Sample status output:

📊 Agent Status Report
=====================

✅ calculator (port 8001): Running (PID: 12345)
   📍 URL: http://localhost:8001
   🕐 Started: 2024-01-15 14:30:22
   📝 Log: ./logs/calculator.log

✅ time (port 8002): Running (PID: 12346)
   📍 URL: http://localhost:8002
   🕐 Started: 2024-01-15 14:30:23
   📝 Log: ./logs/time.log

❌ webbrowser (port 8004): Not running
   📝 Log: ./logs/webbrowser.log

Manual Agent Startup (Alternative)

For development or debugging, you can start agents manually:

# Individual configurable agents
uv run configurable-agent calculator    # Port 8001
uv run configurable-agent time          # Port 8002
uv run configurable-agent fileeditor    # Port 8003
uv run configurable-agent webbrowser    # Port 8004

# Coordinator agents
uv run coordinator-agent time-and-calculator  # Port 8005
uv run coordinator-agent edit-and-browse      # Port 8006

Agent Dependency Management

The system automatically manages agent dependencies:

1. Independent agents start first (calculator, time, fileeditor, webbrowser)
2. Coordinator agents start after their dependencies are ready
3. Health checks ensure agents are ready before starting dependents

Log Management

Each agent maintains its own log file in the ./logs/ directory:

• ./logs/calculator.log - Calculator agent logs
• ./logs/time.log - Time agent logs
• ./logs/fileeditor.log - File editor agent logs
• ./logs/webbrowser.log - Web browser agent logs
• ./logs/time-and-calculator.log - Time & calculator coordinator logs
• ./logs/edit-and-browse.log - Edit & browse coordinator logs

Viewing Logs

# View real-time logs
tail -f ./logs/calculator.log

# View recent log entries
uv run log-viewer calculator

# View all agent logs
uv run log-viewer --all

Default Agent Configuration

The system comes with these pre-configured agents:

Agent	Type	Port	Capabilities	Tools/MCP
calculator	Individual	8001	Mathematical calculations	Strands calculator
time	Individual	8002	Time and timezone info	Strands current_time
fileeditor	Individual	8003	File operations	Strands editor, file_read, file_write
webbrowser	Individual	8004	Web content fetching	MCP fetch server
time-and-calculator	Coordinator	8005	Math & time coordination	Manages calculator + time
edit-and-browse	Coordinator	8006	File & web coordination	Manages fileeditor + webbrowser

🛠️ Troubleshooting

Common Issues and Solutions

1. Agents Won't Start

# Check if ports are in use
lsof -i :8001
lsof -i :8002

# Force start to kill existing processes
uv run agents start --force

# Check logs for specific errors
tail -f ./logs/calculator.log

2. "Connection Refused" Errors

# Verify agents are running
uv run agents status

# Restart all agents
uv run agents restart

# Check network connectivity
curl http://localhost:8001/.well-known/agent.json

3. Voice Mode Issues (Nova Sonic)

# Check AWS credentials
aws sts get-caller-identity

# Set credentials if needed
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_DEFAULT_REGION=us-east-1

# Test audio devices
uv run a2a-client speak --agent calculator --disable-echo-cancellation

4. WebSpeak Not Working

# Check microphone permissions in browser
# Ensure port 3000 is available
lsof -i :3000

# Try different port
uv run a2a-client webspeak --port 8090

5. Push Notifications Not Working

# Check webhook server
curl http://localhost:8000/health

# Verify webhook port in config
grep -A5 "\[webhook\]" config/config.toml

# Restart with clean state
uv run agents stop
uv run agents start

Debugging Commands

# Enable debug logging
export STRANDS_LOG_LEVEL=DEBUG

# View all logs in real-time
tail -f ./logs/*.log

# Test individual agent
curl http://localhost:8001/.well-known/agent.json | jq

# Test webhook connectivity
curl -X POST http://localhost:8000/webhook/a2a-tasks \
  -H "Content-Type: application/json" \
  -d '{"test": "webhook"}'

Performance Optimization

For Better Response Times:

# In config/config.toml, use faster model
[agents]
model = "us.amazon.nova-lite-v1:0"  # Fastest
# model = "us.amazon.nova-pro-v1:0"    # Balanced
# model = "us.amazon.nova-premier-v1:0" # Best quality

For Memory Usage:

# Monitor memory usage
ps aux | grep -E "(configurable-agent|coordinator-agent)"

# Restart agents if memory usage is high
uv run agents restart

📚 API Reference

A2A Client Core API

CleanA2AClient Class

from a2a_client import CleanA2AClient

# Initialize client
client = CleanA2AClient("http://localhost:8001", "calculator")

# Discover agent capabilities
await client.discover_agent_skills()

# Send immediate message
response = await client.send_message("What is 25 * 47?")

# Send asynchronous task
def callback(task):
    print(f"Task completed: {client.extract_task_result(task)}")

task_id = await client.send_task("Complex calculation", callback)

Agent Management API

from agent_process_manager import AgentProcessManager

manager = AgentProcessManager()

# Start all agents
success = manager.start_all_agents()

# Get agent status
status = manager.get_agent_status()

# Stop all agents
manager.stop_all_agents()

Configuration API

Loading Configuration

import tomllib
from pathlib import Path

def load_config():
    config_path = Path("config/config.toml")
    with open(config_path, "rb") as f:
        return tomllib.load(f)

config = load_config()
agents = config.get("configurable_agent", {})

Agent Discovery

from a2a_client import discover_available_agents

# Get all available agents
agents = discover_available_agents()
# Returns: {"calculator": "http://localhost:8001", ...}

Webhook API

Push Notification Management

from a2a_push_notification_manager import get_client_webhook_manager

webhook_manager = get_client_webhook_manager()
await webhook_manager.start()

# Register task callback
success = await webhook_manager.register_task_callback(
    client=a2a_client,
    task_id="task-123",
    callback=my_callback,
    timeout_seconds=300.0
)

Testing API

Test Runner

from test_interface import test_mode

# Run all tests
await test_mode("all")

# Test specific agent
await test_mode("calculator")

Voice API

Speech Integration

from speak_interface import speak_mode
from aws_credentials_helper import ensure_aws_credentials

# Ensure AWS credentials
ensure_aws_credentials()

# Start voice mode
await speak_mode("calculator", disable_echo_cancellation=False)

🔗 Quick Reference

Essential Commands

# Setup and start
uv sync                              # Install dependencies
uv run agents start                  # Start all agents
uv run a2a-client web               # Launch web interface

# Agent management
uv run agents status                # Check agent status
uv run agents restart               # Restart all agents
uv run agents stop                  # Stop all agents

# Client modes
uv run a2a-client interactive       # CLI chat mode
uv run a2a-client speak --agent calculator  # Voice mode
uv run a2a-client webspeak         # Web voice interface
uv run a2a-client test             # Run test suite

# Individual agents (manual)
uv run configurable-agent calculator
uv run coordinator-agent time-and-calculator

Default Ports

• 8001: Calculator agent
• 8002: Time agent
• 8003: File editor agent
• 8004: Web browser agent
• 8005: Time & calculator coordinator
• 8006: Edit & browse coordinator
• 8000: Webhook server
• 8080: Web interface
• 3000: WebSpeak interface

Configuration Files

• config/config.toml: Main configuration
• ./logs/*.log: Agent log files
• ./state/agents.json: Agent state persistence

⚙️ Advanced Configuration

Basic Structure

[logging]
level = "INFO"

[webhook]
port = 8910
host = "0.0.0.0"

[agents]
model = "us.amazon.nova-lite-v1:0"

# Individual configurable agents
[configurable_agent.<agent_name>]
# ... agent configuration

# Coordinator agents that manage groups
[coordinator_agent.<coordinator_name>]
# ... coordinator configuration

Configurable Agent Syntax

Each configurable agent is defined using the [configurable_agent.<name>] section:

[configurable_agent.myagent]
description = "Description of what this agent does"
port = 8001
system_prompt = "You are a helpful assistant..."
strands_tools = ["tool1", "tool2"]  # Optional: Strands tools to load

# Optional: MCP servers to connect to
[configurable_agent.myagent.mcp_servers]
server_name = { command = "command", args = ["arg1", "arg2"] }

Required Fields:

• description: Human-readable description of the agent's purpose
• port: Port number where the agent will run (must be unique)
• system_prompt: The system prompt that defines the agent's behavior

Optional Fields:

• strands_tools: Array of Strands tool names to load (e.g., ["calculator", "current_time"])
• mcp_servers: Section defining MCP servers to connect to

Coordinator Agent Syntax

Coordinator agents manage groups of other agents:

[coordinator_agent.mycoordinator]
description = "Coordinator that manages specific agents"
port = 8000
system_prompt = "You are a coordinator agent..."
coordinated_agents = ["agent1", "agent2"]

Required Fields:

• description: Human-readable description of the coordinator's purpose
• port: Port number where the coordinator will run (must be unique)
• system_prompt: The system prompt for coordination behavior
• coordinated_agents: Array of agent names this coordinator manages

Available Strands Tools

The system supports these built-in Strands tools:

• calculator: Mathematical calculations and equation solving
• current_time: Current time and timezone information
• editor: File editing with iterative changes
• file_read: Advanced file reading capabilities
• file_write: File writing with confirmation

MCP Server Configuration

MCP (Model Context Protocol) servers can be configured per agent:

[configurable_agent.myagent.mcp_servers]
fetch = { command = "uvx", args = ["mcp-server-fetch"] }
filesystem = { command = "mcp-server-filesystem", args = ["/path/to/root"] }

Complete Example

Here's a complete example showing different types of agents:

[logging]
level = "INFO"

[webhook]
port = 8910
host = "0.0.0.0"

[agents]
model = "us.amazon.nova-lite-v1:0"

# Math specialist using Strands calculator tool
[configurable_agent.calculator]
description = "Mathematical calculation specialist"
port = 8001
system_prompt = "You are a precise calculator. Solve math problems step by step."
strands_tools = ["calculator"]

[configurable_agent.calculator.mcp_servers]
# No MCP servers for this agent

# Web browsing agent using MCP fetch server
[configurable_agent.webbrowser]
description = "Web content fetching specialist"
port = 8004
system_prompt = "You are a web browsing assistant. Fetch and analyze web content."
strands_tools = []

[configurable_agent.webbrowser.mcp_servers]
fetch = { command = "uvx", args = ["mcp-server-fetch"] }

# Coordinator managing both agents
[coordinator_agent.main]
description = "Main coordinator managing math and web agents"
port = 8000
system_prompt = "You coordinate tasks between math and web agents."
coordinated_agents = ["calculator", "webbrowser"]

Adding New Agents

To add a new agent:

1. Choose a unique name and port number
2. Add a [configurable_agent.<name>] section with required fields
3. Specify tools or MCP servers the agent should use
4. Restart the agent with uv run configurable-agent <name>
5. Optional: Add to a coordinator's coordinated_agents list

The system will automatically discover and make the new agent available to all clients.

Port Management

Recommended Port Ranges:

• 8001-8099: Individual configurable agents
• 8000, 8100-8199: Coordinator agents
• 8910: Webhook server (fixed)
• 8080: Web interface (default)
• 3000: WebSpeak interface (default)

Important: Each agent must have a unique port number.

🎤 WebSpeak Voice Interface

The demo now includes a web-based voice interface that allows natural voice conversations with A2A agents using Amazon Nova Sonic and WebRTC:

Features

• Browser-based Voice Interaction: No downloads needed, works in any modern browser
• WebRTC Audio Processing: Built-in echo cancellation, noise suppression, and auto-gain control
• Real-time Conversation: See transcriptions and responses in real-time
• Agent Discovery: Visual agent selection with skills display
• Tool Visualization: Watch agents use tools in real-time
• Multi-Agent Support: Switch between agents without restarting

Quick Start

# Start the WebSpeak server
uv run a2a-client webspeak

# Open browser to http://localhost:3000
# Select an agent and start talking!

Technical Architecture

• Frontend: HTML5/WebRTC for audio processing + SocketIO for real-time communication
• Backend: Flask-SocketIO server using the same A2A integration as CLI speak mode
• Audio Flow: Browser WebRTC → Nova Sonic → A2A Agents → Voice responses
• Advantages: Client-side audio processing, remote access, visual feedback

See webspeak/README.md for detailed documentation.

🔄 Agent-to-Agent Communication Flow

graph TB
    subgraph "A2A Client"
        C[User/Test Client]
    end
    
    subgraph "Coordinator Agent (Port 8000)"
        CA[Coordinator Agent<br/>A2AStarletteApplication]
        CE[CoordinatorAgentExecutor]
        CC[A2AClient Tools]
    end
    
    subgraph "Calculator Agent (Port 8001)" 
        MA[Calculator Agent<br/>A2AStarletteApplication]
        ME[CalculatorAgentExecutor]
        MT[Strands Calculator Tool]
    end
    
    subgraph "Time Agent (Port 8002)"
        TA[Time Agent<br/>A2AStarletteApplication] 
        TE[TimeAgentExecutor]
        TT[Strands Time Tool]
    end
    
    C --> CA
    CA --> CE
    CE --> CC
    CC --> MA
    CC --> TA
    MA --> ME
    TA --> TE
    ME --> MT
    TE --> TT

📖 Implementation Notes

Official Patterns Followed

• Server Pattern: A2AStarletteApplication + DefaultRequestHandler + AgentExecutor
• Client Pattern: A2AClient + A2ACardResolver for discovery
• Messaging Pattern: new_agent_text_message() for responses
• Context Pattern: RequestContext + EventQueue for task execution
• Task Pattern: InMemoryTaskStore for task management

Strands Integration

• Strands Agents SDK provides the LLM backbone
• Official A2A SDK provides the communication layer
• Seamless integration between both frameworks
• Tool sharing between Strands and A2A contexts

🚀 What's Next?

This implementation provides a solid foundation for:

• Building production A2A agent networks
• Integrating with existing LLM applications
• Creating specialized agent marketplaces
• Implementing complex multi-agent workflows

The codebase follows official patterns exactly, making it easy to:

• Add new agents following the same structure
• Scale to larger agent networks
• Integrate with other A2A-compatible systems
• Deploy in production environments

📋 Quick Reference

Managing Agents

# Agent management (recommended)
uv run agents start                        # Start all agents
uv run agents start calculator             # Start specific agent
uv run agents stop                         # Stop all agents  
uv run agents stop time                    # Stop specific agent
uv run agents restart                      # Restart all agents
uv run agents restart coordinator          # Restart specific agent
uv run agents status                       # Check all agent status
uv run agents status webbrowser            # Check specific agent status

Starting Agents Individually (Alternative)

# Individual configurable agents
uv run calculator-agent                    # Port 8001
uv run time-agent                          # Port 8002
uv run configurable-agent fileeditor      # Port 8003
uv run configurable-agent webbrowser      # Port 8004

# Coordinator agents
uv run coordinator-agent time-and-calculator  # Port 8000
uv run coordinator-agent edit-and-browse      # Port 8005

Using the A2A Client

# Web interface (recommended)
uv run a2a-client web                      # http://localhost:8080

# Interactive CLI
uv run a2a-client interactive              # Terminal-based chat
uv run a2a-client interactive --agent calculator  # Direct agent chat

# Voice interfaces
uv run a2a-client speak --agent coordinator       # CLI voice mode
uv run a2a-client webspeak                        # Web voice interface

# Testing
uv run a2a-client test                     # Comprehensive test suite
uv run a2a-client test --agent calculator # Test specific agent only

Configuration Quick Start

# Add a new agent
[configurable_agent.myagent]
description = "My custom agent"
port = 8010
system_prompt = "You are a helpful assistant."
strands_tools = ["calculator"]

# Add a coordinator
[coordinator_agent.mycoordinator]
description = "My coordinator"
port = 8020
system_prompt = "You coordinate tasks."
coordinated_agents = ["myagent", "calculator"]

📚 References

A2A Protocol Resources

• Official A2A Specification - Complete protocol documentation
• A2A Python SDK (GitHub) - Official Python implementation
• A2A Python Samples - Reference implementations
• A2A SDK Documentation - PyPI package documentation
• Google Transfers A2A to Linux Foundation - Official announcement

Strands Agents Resources

• Strands Agents - Official website and documentation
• Strands Agents SDK (GitHub) - Python SDK repository

Development Tools

• UV Documentation - Fast Python package manager
• Amazon Nova Documentation - Speech services for voice modes
• Python A2A Tutorial - Getting started guide

---

🚀 Built with ❤️ using the official A2A SDK patterns and Strands Agents SDK

Ready to build your own agent network? Start with uv sync && uv run agents start && uv run a2a-client web