← Back to project home · GitHub repository

A2A Multi-Agent Communication System

Technical Architecture & Workflow Documentation

Project Overview

This project implements a simplified version of the Agent-to-Agent (A2A) protocol for inter-agent communication. The system features two specialized agents that can communicate to solve complex problems collaboratively using JSON-RPC 2.0 over HTTP.

Python 3.9+ FastAPI JSON-RPC 2.0 NumPy Pandas Matplotlib A2A Protocol

System Architecture Overview

graph TB subgraph "A2A Multi-Agent System" subgraph "Core Components" A2A[A2A Protocol
common/a2a_protocol.py] BASE[Base Agent
common/base_agent.py] end subgraph "Specialized Agents" MATH[Math Agent
Port 8001
Mathematical Computations] DATA[Data Analyst Agent
Port 8002
Data Analysis & Visualization] end subgraph "Orchestration Layer" ORCH[Multi-Agent Orchestrator
examples/orchestrator.py] end subgraph "Management Scripts" START1[start_math_agent.py] START2[start_data_agent.py] DEMO[run_demo.py] LAUNCH[launch_system.py] TEST[test_system.py] end end A2A --> BASE BASE --> MATH BASE --> DATA ORCH --> MATH ORCH --> DATA START1 --> MATH START2 --> DATA DEMO --> ORCH LAUNCH --> MATH LAUNCH --> DATA LAUNCH --> ORCH TEST --> MATH TEST --> DATA style A2A fill:#e1f5fe style BASE fill:#e8f5e8 style MATH fill:#fff3e0 style DATA fill:#fce4ec style ORCH fill:#f3e5f5

Component Architecture

A2A Protocol Core

File: common/a2a_protocol.py

Purpose: Implements core A2A protocol classes and message handling

Message, Task, AgentCard dataclasses
TaskState and TaskStatus enums
JSON-RPC 2.0 protocol constants
MessageSendParams for communication

Base Agent Framework

File: common/base_agent.py

Purpose: Abstract base class for all A2A-compatible agents

FastAPI server integration
Async message processing
Agent discovery and health checks
Task management and storage

Math Agent

File: agents/math_agent.py

Port: 8001

Arithmetic operations
Statistical analysis
Linear algebra
Probability distributions

Data Analyst Agent

File: agents/data_analyst_agent.py

Port: 8002

Data visualization
Correlation analysis
Trend analysis
Statistical reporting

Communication Protocol Flow

sequenceDiagram participant O as Orchestrator participant M as Math Agent
(Port 8001) participant D as Data Analyst
(Port 8002) Note over O,D: System Initialization O->>M: GET /health (Health Check) M-->>O: 200 OK O->>D: GET /health (Health Check) D-->>O: 200 OK Note over O,D: Agent Discovery O->>M: GET /agent-card (Capability Discovery) M-->>O: AgentCard with capabilities O->>D: GET /agent-card (Capability Discovery) D-->>O: AgentCard with capabilities Note over O,D: Task Processing Example O->>O: Analyze user request
"Calculate statistics and create visualization" O->>M: POST /send-message
Statistical calculation request M->>M: Process mathematical computation M-->>O: Task result with statistics O->>D: POST /send-message
Visualization request with stats D->>D: Create charts and analysis D-->>O: Task result with visualization O->>O: Combine results from both agents Note over O,D: Final response to user

Message Structure & Protocol

A2A Message Format

{
  "jsonrpc": "2.0",
  "method": "send-message",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Calculate the mean of [1,2,3,4,5]"
        }
      ],
      "contextId": "ctx-123",
      "taskId": "task-456"
    },
    "contextId": "ctx-123",
    "sessionId": "session-789"
  },
  "id": "msg-001"
}
            

Task Response Format

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-456",
    "messages": [...],
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [
          {
            "kind": "text",
            "text": "The mean of [1,2,3,4,5] is 3.0"
          }
        ]
      }
    },
    "contextId": "ctx-123",
    "sessionId": "session-789"
  },
  "id": "msg-001"
}
            

Agent Capabilities Matrix

Agent	Port	Primary Capabilities	Input Types	Output Types
Math Agent	8001	• Arithmetic operations • Statistical analysis • Linear algebra • Probability distributions	• Mathematical expressions • Numeric arrays • Statistical queries	• Numerical results • Statistical summaries • Mathematical proofs
Data Analyst Agent	8002	• Data visualization • Correlation analysis • Trend analysis • Report generation	• CSV data • JSON datasets • Statistical results	• Charts and plots • Analysis reports • Data insights

System Workflow

flowchart TD START([User Request]) --> PARSE{Orchestrator
Analyzes Request} PARSE -->|Math Required| MATH_FLOW[Send to Math Agent
Port 8001] PARSE -->|Data Analysis Required| DATA_FLOW[Send to Data Analyst
Port 8002] PARSE -->|Both Required| BOTH_FLOW[Multi-Agent Workflow] MATH_FLOW --> MATH_PROCESS[Math Agent Processing
• Arithmetic
• Statistics
• Linear Algebra] DATA_FLOW --> DATA_PROCESS[Data Analyst Processing
• Visualization
• Analysis
• Reporting] BOTH_FLOW --> STEP1[Step 1: Math Agent
Calculate Statistics] STEP1 --> STEP2[Step 2: Data Analyst
Create Visualization] STEP2 --> COMBINE[Combine Results] MATH_PROCESS --> RESPONSE[Return Response] DATA_PROCESS --> RESPONSE COMBINE --> RESPONSE RESPONSE --> END([Final Result to User]) style START fill:#e8f5e8 style PARSE fill:#fff3e0 style MATH_FLOW fill:#e1f5fe style DATA_FLOW fill:#fce4ec style BOTH_FLOW fill:#f3e5f5 style END fill:#e8f5e8

Deployment Architecture

graph LR subgraph "Local Development Environment" subgraph "Agent Services" M[Math Agent
localhost:8001
FastAPI Server] D[Data Analyst Agent
localhost:8002
FastAPI Server] end subgraph "Client Applications" O[Orchestrator
HTTP Client] T[Test Suite
System Validation] end subgraph "Management Layer" L[Launch Scripts
Process Management] VS[VS Code Tasks
Development Tools] end end O -.->|HTTP/JSON-RPC| M O -.->|HTTP/JSON-RPC| D T -.->|Health Checks| M T -.->|Health Checks| D L --> M L --> D L --> O VS --> L style M fill:#e1f5fe style D fill:#fce4ec style O fill:#f3e5f5 style T fill:#e8f5e8 style L fill:#fff3e0 style VS fill:#f0f0f0

Startup and Launch Options

Individual Agent Launch

# Math Agent only
python start_math_agent.py

# Data Analyst Agent only  
python start_data_agent.py
                

Ports: Math Agent (8001), Data Analyst (8002)

Complete System Launch

# Launch all agents and orchestrator
python launch_system.py

# Run demonstration
python run_demo.py
                

Services: Both agents + orchestrator demo

VS Code Integration

# Available VS Code tasks:
- Launch Math Agent
- Launch Data Analyst Agent  
- Launch Complete System
- Run Demo
- Run Tests
                

Access: Ctrl/Cmd + Shift + P → "Tasks: Run Task"

System Validation

# Test system health and communication
python test_system.py
                

Validates: Agent health, communication, capabilities

Error Handling & Resilience

flowchart TD REQ[Incoming Request] --> VALIDATE{Validate Request} VALIDATE -->|Valid| PROCESS[Process Request] VALIDATE -->|Invalid| ERROR1[Return Validation Error] PROCESS --> AGENT{Agent Available?} AGENT -->|Yes| EXECUTE[Execute Task] AGENT -->|No| ERROR2[Agent Unavailable Error] EXECUTE --> SUCCESS{Task Successful?} SUCCESS -->|Yes| RESULT[Return Result] SUCCESS -->|No| ERROR3[Task Execution Error] ERROR1 --> LOG[Log Error] ERROR2 --> LOG ERROR3 --> LOG LOG --> RETRY{Retry Logic} RETRY -->|Yes| PROCESS RETRY -->|No| FINAL_ERROR[Return Error Response] RESULT --> END[Response Sent] FINAL_ERROR --> END style REQ fill:#e8f5e8 style RESULT fill:#e8f5e8 style ERROR1 fill:#ffebee style ERROR2 fill:#ffebee style ERROR3 fill:#ffebee style FINAL_ERROR fill:#ffebee

Performance Considerations

⚠️ Current Limitations

Single-threaded agent processing
In-memory task storage (not persistent)
No load balancing for multiple requests
Basic error recovery mechanisms

✅ Optimization Opportunities

Implement async task queues
Add persistent storage for tasks
Implement agent clustering
Add comprehensive monitoring
Cache frequently used calculations

Development Workflow

Step 1: Environment Setup

Create Python virtual environment and install dependencies from requirements.txt

Step 2: Agent Development

Extend BaseAgent class, implement process_message method, define capabilities

Step 3: Testing

Run test_system.py to validate agent communication and functionality

Step 4: Integration

Use orchestrator to coordinate multiple agents for complex problem solving

Step 5: Deployment

Launch system using provided scripts or VS Code tasks

Future Enhancements

Protocol Extensions

WebSocket support for real-time communication
Message encryption and authentication
Agent capability negotiation
Distributed agent discovery

Additional Agents

Natural Language Processing Agent
Image Processing Agent
Database Query Agent
File Management Agent

Infrastructure

Docker containerization
Kubernetes orchestration
Service mesh integration
Monitoring and observability

User Interface

Web-based agent dashboard
Real-time task monitoring
Interactive agent testing
Performance analytics

📄 Documentation Generated

Date: July 24, 2025

Project: A2A Multi-Agent Communication System

Version: 1.0.0

Author: AI Development Team