Multi Agents with A2A, Azure OpenAI and MCP

A sophisticated multi-agent system that leverages Agent-to-Agent (A2A) communication protocol, Azure OpenAI services, and Model Context Protocol (MCP) to provide comprehensive data analysis capabilities for both CSV files and SQL databases.

Architecture Overview

This project implements a distributed multi-agent architecture where specialized agents collaborate to provide data analysis services:

Core Components

1. MCP Servers (Model Context Protocol)

   • CSV MCP Server (Port 8000): Provides tools for CSV file operations including loading, analyzing, executing custom Python code, and generating visualizations
   • MySQL MCP Server (Port 8001): Offers MySQL database operations such as query execution, database/table listing, and schema inspection

2. Specialized Agents

   • CSV Agent (Port 5555): A semantic kernel-based agent specialized in CSV data analysis, connected to the CSV MCP Server via SSE (Server-Sent Events)
   • MySQL Agent (Port 5556): A semantic kernel-based agent focused on SQL query execution and database operations, connected to the MySQL MCP Server via SSE
   • Host Agent (Port 8002): An orchestration agent that coordinates between CSV and MySQL agents, providing a unified interface for users

Communication Flow

1. Agent Initialization:

   • Each agent is built using semantic_kernel.agents.chat_completion.ChatCompletionAgent
   • Agents use Azure OpenAI's ChatCompletion service (deployment: gpt-4o-mini)
   • Agents are configured with specific plugins (MCPSsePlugin) to communicate with their respective MCP servers

2. A2A Protocol Communication:

   • Agents expose their capabilities through A2A (Agent-to-Agent) protocol
   • Each agent publishes an AgentCard describing its skills and capabilities
   • The Host Agent uses A2AClient to communicate with both CSV and MySQL agents
   • Messages are exchanged using the A2A protocol's SendMessageRequest/Response pattern

3. MCP Integration:

   • MCP servers provide tool-based interfaces for specific operations
   • Agents connect to MCP servers via SSE (Server-Sent Events) for real-time communication
   • The semantic kernel's MCPSsePlugin enables agents to invoke MCP tools as native functions

Data Flow Example

1. User submits a request to the Host Agent via web interface
2. Host Agent analyzes the request and determines which specialized agent to invoke
3. Host Agent sends an A2A message to the appropriate agent (CSV or MySQL)
4. The specialized agent processes the request using its semantic kernel and MCP tools
5. Results flow back through the A2A protocol to the Host Agent
6. Host Agent returns the consolidated response to the user

Deep Dive into Components

Semantic Kernel Integration

Each agent leverages Microsoft's Semantic Kernel framework:

• ChatCompletionAgent: Provides LLM-powered reasoning capabilities
• Kernel Functions: Enable tool registration and invocation
• Chat History Management: Maintains conversation context per session
• Plugin System: Allows integration with external services (MCP servers)

MCP (Model Context Protocol) Servers

The MCP servers act as tool providers:

CSV MCP Server Tools:

• load_csv: Load CSV files into memory
• list_datasets: Show all loaded datasets
• get_dataset_info: Get detailed dataset information
• execute_analysis_code: Run custom Python code for analysis
• generate_basic_insights: Auto-generate statistical insights
• export_dataset: Export processed data
• send_email: Send analysis results via email

MySQL MCP Server Tools:

• execute_query: Run SQL queries
• list_databases: Show available databases
• list_tables: List tables in a database
• describe_table: Get table schema
• test_connection: Verify database connectivity
• update_connection: Change connection parameters

A2A Protocol Implementation

The system uses the A2A SDK for inter-agent communication:

• AgentCard: Describes agent capabilities and endpoints
• AgentSkill: Defines specific skills with examples
• MessageSendParams: Structures communication between agents
• A2AClient/A2ACardResolver: Handles agent discovery and messaging

Azure OpenAI Integration

All agents use Azure OpenAI for intelligent processing:

• Deployment: gpt-4o-mini model
• API Version: 2024-12-01-preview
• Configuration: Loaded from environment variables for security
• Usage: Powers natural language understanding and response generation

Project Structure

csv-sql-agents-with-mcp/
├── agents/                    # Agent implementations
│   ├── csv_agent/            # CSV analysis agent
│   │   ├── __main__.py      # A2A server setup
│   │   ├── agent.py         # Semantic kernel agent
│   │   └── agent_executor.py # Request processing
│   ├── sql_agent/            # SQL query agent
│   │   ├── __main__.py      # A2A server setup
│   │   ├── agent.py         # Semantic kernel agent
│   │   └── agent_executor.py # Request processing
│   └── host_agent/           # Host orchestration agent
│       ├── main.py          # FastAPI app with agents
│       └── index.html       # Web interface
├── mcp-csv-analyzer/         # CSV MCP server
│   └── mcp_csv_analyzer/
│       └── server.py        # MCP tool implementations
├── mysql_mcp/                # MySQL MCP server
│   └── main.py              # MCP tool implementations
├── scripts/                  # Entry point scripts
├── .env                      # Environment configuration
├── pyproject.toml           # Unified project configuration
├── start_uv.bat             # Windows batch script
└── README.md                # This file

Installation

1. Clone the repository

2. Create a .env file in the root directory with your Azure OpenAI credentials:

   API_KEY=your_azure_openai_api_key_here
   END_POINT=your_azure_openai_endpoint
   DEPLOYMENT=gpt-4o-mini
   API_VERSION=2024-12-01-preview
   
   # Optional: MySQL configuration
   MYSQL_HOST=localhost
   MYSQL_USER=root
   MYSQL_PASSWORD=your_password
   MYSQL_DATABASE=your_database
   MYSQL_PORT=3306
   

3. Install dependencies using uv:

   uv sync

Docker Deployment

Prerequisites

• Docker and Docker Compose installed
• At least 4GB of available RAM

Quick Start with Docker

1. Windows:

   docker-start.bat

2. Linux/Mac:

   chmod +x docker-start.sh
   ./docker-start.sh

Manual Docker Setup

1. Copy the Docker environment template:

   cp env.docker .env

2. Update .env with your Azure OpenAI credentials

3. Build and start all services:

   docker-compose build
   docker-compose up -d

4. Check service status:

   docker-compose ps

Docker Services

The Docker setup includes:

• All 5 agent services (CSV MCP, MySQL MCP, CSV Agent, SQL Agent, Host Agent)
• MySQL 8.0 database for testing
• Shared network for inter-service communication
• Volume mounts for data persistence
• Health checks for proper startup ordering

Docker Commands

# View logs for a specific service
docker-compose logs -f csv-agent

# Stop all services
docker-compose down

# Stop and remove all data volumes
docker-compose down -v

# Rebuild after code changes
docker-compose build --no-cache

# Scale a service
docker-compose up -d --scale csv-agent=2

Docker Networking

In Docker, services communicate using container names:

• CSV MCP Server: http://csv-mcp-server:8000
• MySQL MCP Server: http://mysql-mcp-server:8001
• CSV Agent: http://csv-agent:5555
• SQL Agent: http://sql-agent:5556
• MySQL Database: mysql-db:3306

Running the Services

Quick Start (Windows)

Run all services using the batch script:

start_uv.bat

Individual Services

# CSV MCP Server (port 8000)
uv run csv-mcp-server

# MySQL MCP Server (port 8001)
set FASTMCP_PORT=8001 && uv run mysql-mcp-server

# CSV Agent (port 5555)
uv run csv-agent

# SQL Agent (port 5556)
uv run sql-agent

# Host Agent (port 8002)
uv run host-agent

Service Endpoints

• CSV MCP Server: http://localhost:8000 (SSE endpoint: /sse)
• MySQL MCP Server: http://localhost:8001 (SSE endpoint: /sse)
• CSV Agent: http://localhost:5555 (A2A endpoint)
• SQL Agent: http://localhost:5556 (A2A endpoint)
• Host Agent: http://localhost:8002 (Web UI)

Usage Examples

Via Host Agent Web Interface

1. Navigate to http://localhost:8002
2. Enter your data analysis request in natural language
3. The system will automatically route to the appropriate agent

Example requests:

• "Load the sales.csv file and show me the top 10 products by revenue"
• "Connect to the customer database and find all orders from last month"
• "Analyze the correlation between price and quantity in my dataset"
• "Show me all tables in the inventory database"

Direct Agent Communication

You can also communicate directly with individual agents via their A2A endpoints using the A2A client SDK.

Key Features

Intelligent Routing

The Host Agent uses Azure OpenAI to understand user intent and automatically routes requests to the appropriate specialized agent.

Contextual Conversations

Each agent maintains conversation history, allowing for follow-up questions and contextual understanding.

Tool Augmentation

Agents are augmented with MCP tools, combining LLM intelligence with deterministic operations.

Scalable Architecture

The distributed nature allows for easy scaling and addition of new specialized agents.

Secure Configuration

All sensitive credentials are managed through environment variables.

Development

Adding New MCP Tools

1. Add the tool function to the appropriate MCP server
2. Decorate with @mcp.tool()
3. The tool automatically becomes available to connected agents

Creating New Agents

1. Create a new agent directory under agents/
2. Implement the semantic kernel agent
3. Set up A2A server with AgentCard
4. Add MCP plugin connections as needed

Extending the Host Agent

The Host Agent can be extended with new tools by:

1. Creating new kernel functions with @kernel_function
2. Adding them to the agent's plugin list
3. Updating the system prompt to include new capabilities

Troubleshooting

Common Issues

1. Port conflicts: Ensure ports 8000, 8001, 5555, 5556, and 8002 are available
2. MCP connection issues: Start MCP servers before agents
3. Azure OpenAI errors: Verify credentials in .env file
4. Agent communication failures: Check A2A endpoints are accessible

Debug Mode

Enable detailed logging by setting:

logging.basicConfig(level=logging.DEBUG)

Health Checks

• MCP Servers: Check /health endpoint
• Agents: Verify A2A card at agent URL
• Host Agent: Access web UI at http://localhost:8002

Architecture Benefits

1. Separation of Concerns: Each agent specializes in its domain
2. Modularity: Easy to add/remove agents without affecting others
3. Scalability: Agents can be distributed across machines
4. Flexibility: MCP tools can be updated independently
5. Intelligence: LLM-powered understanding and reasoning
6. Interoperability: A2A protocol enables cross-agent communication

Future Enhancements

• Add more specialized agents (e.g., Excel, MongoDB, APIs)
• Implement agent discovery service
• Add authentication and authorization
• Create Docker containers for easy deployment
• Implement result caching and optimization
• Add support for streaming responses
• Create agent orchestration workflows