A2A Protocol Multi-Agent System
A comprehensive multi-agent system demonstrating Agent-to-Agent (A2A) Protocol, OpenLLMetry tracing, and MCP integration through realistic AI-powered development workflows. Built for conference demonstrations and production-ready distributed agent systems.
What This System Does
This system features two powerful workflows with specialized agents:
Code Quality Analysis Workflow
Three review agents collaborate to analyze existing code:
- Security Scanner Agent - Scans for security vulnerabilities using tools like Bandit and Semgrep
- Code Reviewer Agent - Analyzes code quality, complexity, and style using MCP tools and linters
- Documentation Agent - Evaluates documentation coverage and quality
A2A Development Workflow (Featured!)
Five agents collaborate using A2A Protocol in a complete AI-powered development lifecycle:
- Dev Lead Agent - Orchestrates development tasks and coordinates A2A communication
- Developer Agent - Uses GPT-4o-mini to generate high-quality Python code based on requirements
- Security Scanner Agent - Reviews generated code for security vulnerabilities
- Code Reviewer Agent - Uses GPT-4o-mini to analyze code quality with MCP tools
- Documentation Agent - Evaluates documentation coverage and quality
The agents use authentic A2A Protocol for discovery, authentication, and message passing, with full cross-agent trace propagation via OpenTelemetry.
Quick Start
Prerequisites
- Python 3.10+
- uv package manager (recommended) or pip
Installation & Setup
# Clone or download this project
cd multi-agent-example
# Install with uv (recommended)
uv sync --dev
# OR install with pip
pip install -e .
cd multi-agent-example
# Install with uv (recommended)
uv sync --dev
# OR install with pip
pip install -e .
API Keys Setup
# Copy the example environment file
cp .env.example .env
# Edit .env with your actual API keys
# Required keys:
# - OPENAI_API_KEY=sk-your-openai-api-key-here
# - TRACELOOP_API_KEY=tl_your-traceloop-api-key-here
# Get your keys from:
# - OpenAI: https://platform.openai.com/account/api-keys
# - Traceloop: https://app.traceloop.com/settings/api-keys
cp .env.example .env
# Edit .env with your actual API keys
# Required keys:
# - OPENAI_API_KEY=sk-your-openai-api-key-here
# - TRACELOOP_API_KEY=tl_your-traceloop-api-key-here
# Get your keys from:
# - OpenAI: https://platform.openai.com/account/api-keys
# - Traceloop: https://app.traceloop.com/settings/api-keys
Alternative: Export directly (temporary)
export OPENAI_API_KEY="your_openai_api_key_here"
export TRACELOOP_API_KEY="your_traceloop_api_key_here"
export TRACELOOP_API_KEY="your_traceloop_api_key_here"
Optional Tools
# Enhanced security scanning (optional)
uv add bandit semgrep
# Or with pip
pip install bandit semgrep
uv add bandit semgrep
# Or with pip
pip install bandit semgrep
Running the A2A System
Complete A2A Development Workflow
# Run the complete A2A multi-agent development demo
uv run python test_a2a_complete.py
# Or test with specific requirements
uv run python -c "
import asyncio
from multi_agent_example.a2a_main import A2AMultiAgentOrchestrator
async def main():
orchestrator = A2AMultiAgentOrchestrator()
await orchestrator.initialize()
# Run development workflow
result = await orchestrator.run_development_workflow(
task_description='Create a secure authentication system',
requirements=[
'Implement JWT token authentication',
'Add password hashing with bcrypt',
'Include rate limiting protection',
'Add comprehensive error handling'
]
)
await orchestrator.shutdown()
asyncio.run(main())
"
uv run python test_a2a_complete.py
# Or test with specific requirements
uv run python -c "
import asyncio
from multi_agent_example.a2a_main import A2AMultiAgentOrchestrator
async def main():
orchestrator = A2AMultiAgentOrchestrator()
await orchestrator.initialize()
# Run development workflow
result = await orchestrator.run_development_workflow(
task_description='Create a secure authentication system',
requirements=[
'Implement JWT token authentication',
'Add password hashing with bcrypt',
'Include rate limiting protection',
'Add comprehensive error handling'
]
)
await orchestrator.shutdown()
asyncio.run(main())
"
Test Traceloop Integration
# Set your Traceloop API key first
export TRACELOOP_API_KEY="your_key_here"
# Run with Traceloop export
uv run python test_traceloop_export.py
# Check dashboard at: https://app.traceloop.com
export TRACELOOP_API_KEY="your_key_here"
# Run with Traceloop export
uv run python test_traceloop_export.py
# Check dashboard at: https://app.traceloop.com
Quick Development Test
# Test A2A system without Traceloop (uses demo key)
uv run python test_a2a_complete.py
uv run python test_a2a_complete.py
Architecture
A2A Protocol Architecture
- Authentic A2A Protocol: Uses official
a2a-sdkfor genuine agent-to-agent communication - Agent Discovery: Automatic discovery via A2A endpoints (
/.well-known/agent-card.json) - Message Passing: JSON-RPC message format with proper A2A validation
- RequestHandler: Complete A2A RequestHandler implementation with proper method signatures
- Agent Cards: Full A2A AgentCard, AgentSkill, and AgentCapability definitions
- Port Management: Each agent runs on dedicated ports (8001-8006)
OpenTelemetry Tracing & Observability
- Cross-Agent Trace Propagation: W3C Trace Context headers across HTTP requests
- Traceloop Export: Professional dashboard for trace visualization and analysis
- FastAPI Instrumentation: Automatic tracing of HTTP server requests/responses
- HTTPX Instrumentation: Client-side HTTP request tracing
- Custom Spans: Business logic spans with agent names, operations, and metadata
- Dashboard Waterfall: Complete cross-agent request flow visualization
MCP Integration
- Code Reviewer agent uses MCP tools for advanced analysis:
- AST analyzer for code structure analysis
- Complexity calculator for cyclomatic complexity
- Style checker for code formatting compliance
- Demonstrates protocol-based tool integration
Features
AI-Powered Development
- GPT-4o-mini Code Generation: Fast, cost-effective, high-quality Python code generation
- AI Code Review: Intelligent feedback on code quality, security, and best practices
- Smart Requirements Analysis: AI understands and implements complex requirements
- Contextual Suggestions: AI provides specific, actionable improvement recommendations
- Cost-Effective: Uses GPT-4o-mini for optimal performance/cost balance
Real-World Problem Solving
- Security Analysis: Detects SQL injection, XSS, hardcoded secrets, etc.
- Code Quality: Measures complexity, style compliance, maintainability
- Documentation: Analyzes docstring coverage and quality
- Actionable Reports: Prioritized improvement recommendations
Agent Collaboration
- Agents share results and coordinate analysis phases
- Cross-referencing findings for comprehensive assessment
- Distributed decision making and result aggregation
Observability
- Rich console output with progress indicators
- Detailed tracing of agent interactions
- Performance metrics and operation timings
- Visual result displays with tables and panels
Sample Output
Testing Complete A2A Protocol Multi-Agent System
Demonstrating authentic Agent-to-Agent Protocol communication
================================================================================
A2A Multi-Agent System
Initializing Agent-to-Agent Protocol Communication
Traceloop exporting traces to https://api.traceloop.com authenticating with bearer token
Traceloop SDK initialized
FastAPI instrumentation enabled
HTTPX client instrumentation enabled
Cross-agent trace propagation activated
Traces will be exported to Traceloop: https://api.traceloop.com
View traces at: https://app.traceloop.com
Initializing agents...
+----------------------------- A2A Agent Startup ------------------------------+
| Agent Security Scanner initializing with A2A Protocol |
| ID: security_scanner_2587bd69 |
| A2A Port: 8001 |
| Description: A2A-based security vulnerability scanner |
+------------------------------------------------------------------------------+
A2A Agent Network Overview
+---------------------+------+--------------------------------------+----------+
| Agent | Port | Capabilities | Status |
+---------------------+------+--------------------------------------+----------+
| Security Scanner | 8001 | vulnerability_scan, security_report | * Active |
| Code Reviewer Agent | 8002 | code_quality_review, ai_insights | * Active |
| Documentation Agent | 8003 | documentation_analysis | * Active |
| Dev Lead Agent | 8005 | orchestrate_development_workflow | * Active |
| Developer Agent | 8006 | generate_code, refactor_code | * Active |
+---------------------+------+--------------------------------------+----------+
Starting A2A Development Workflow...
+------------------------ [NEW] Development Task task_185 ------------------------+
| Create a calculator function for A2A demo |
| Priority: HIGH |
| Requirements: |
| * Create a function that can add, subtract, multiply, and divide |
| * Include proper error handling for division by zero |
| * Add comprehensive docstring with examples |
| * Use type hints for better code quality |
+------------------------------------------------------------------------------+
Phase 2: Code Generation
Dev Lead Agent - Developer Agent: A2A Message
Sending request to GPT-4o-mini...
Code generation completed successfully!
Phase 3: Multi-Agent Review
Dev Lead Agent - Security Scanner: A2A Message
Dev Lead Agent - Code Reviewer Agent: A2A Message
Dev Lead Agent - Documentation Agent: A2A Message
================================================================================
A2A PROTOCOL MULTI-AGENT SYSTEM TEST SUCCESSFUL!
Ready for conference demonstration!
================================================================================
A2A Workflow Results:
Status: completed
Workflow Phases: 4/4
Code Generated:
Agent Reviews: 3
Final Assessment: GOOD
A2A Agent Network Status:
* Active Agents: 5
* A2A Protocol: Operational
* Cross-Agent Tracing: Active
* AI Integration: Available
Configuration
Environment Variables
Recommended: Use .env file (automatically loaded)
# Copy and edit the environment file
cp .env.example .env
# The .env file contains:
OPENAI_API_KEY=sk-your-openai-api-key-here
TRACELOOP_API_KEY=tl_your-traceloop-api-key-here
TRACELOOP_BASE_URL=https://api.traceloop.com
ENVIRONMENT=development
DEBUG=false
cp .env.example .env
# The .env file contains:
OPENAI_API_KEY=sk-your-openai-api-key-here
TRACELOOP_API_KEY=tl_your-traceloop-api-key-here
TRACELOOP_BASE_URL=https://api.traceloop.com
ENVIRONMENT=development
DEBUG=false
Alternative: Export directly
export OPENAI_API_KEY="your_openai_api_key"
export TRACELOOP_API_KEY="your_traceloop_api_key"
export TRACELOOP_API_KEY="your_traceloop_api_key"
A2A Agent Ports
- Security Scanner: 8001
- Code Reviewer: 8002
- Documentation Agent: 8003
- Dev Lead Agent: 8005
- Developer Agent: 8006
Traceloop Dashboard
Once running with TRACELOOP_API_KEY, visit https://app.traceloop.com to see:
- Trace Waterfall: Complete cross-agent request flow visualization
- Performance Metrics: Request timing, duration, and throughput
- Error Analysis: Failed requests and exception tracking
- Service Map: Agent relationships and communication patterns
- Business Metrics: Code generation success rates, review scores
What You'll See in Traceloop
With your API key configured, the dashboard will show:
- Service Map: Visual network of your 5 A2A agents and their connections
- Trace Waterfall: Complete request flow from Dev Lead - Developer - Reviewers
- Performance Metrics: Request timing, spans per trace, success rates
- Span Details: Agent names, message types, business context attributes
- Error Tracking: Failed requests with stack traces and retry attempts
Conference Demo Features
This system was designed for conference presentations and includes:
Authentic A2A Protocol Implementation
- Real A2A SDK: Uses official
a2a-sdk, not custom HTTP APIs - Complete Protocol: Agent discovery, capability exchange, message validation
- Production Ready: Full RequestHandler implementation with proper error handling
Comprehensive Tracing & Observability
- Cross-Agent Propagation: W3C Trace Context headers across all agent communication
- Traceloop Dashboard: Professional waterfall visualization and service map
- Real-time Monitoring: See traces as they happen during demo
- Business Context: Spans include agent names, operations, and workflow stages
AI-Powered Workflows
- GPT-4o-mini Integration: Cost-effective, high-quality code generation and review
- Realistic Use Cases: Security scanning, code review, documentation analysis
- Multi-Agent Collaboration: Agents coordinate to solve complex development tasks
- MCP Tool Integration: Advanced code analysis with protocol-based tools
Engaging Presentation Features
- Rich Visual Output: Colorful tables, panels, and progress indicators
- Live Agent Network: Real-time display of active agents and their capabilities
- Interactive Workflows: Watch AI agents collaborate in real-time
- Conference Ready: Professional output suitable for large screen projection
Technical Stack
- A2A Protocol: Official
a2a-sdkfor authentic agent communication - OpenTelemetry: Industry standard distributed tracing
- FastAPI: Modern async HTTP framework for agent servers
- Traceloop: Professional trace visualization and analysis
- Rich: Beautiful terminal output with colors and formatting
- OpenAI GPT-4o-mini: Cost-effective AI for code generation and review
- AsyncIO: Concurrent agent operations and HTTP communication
- Pydantic: Data validation and serialization
- MCP: Model Context Protocol for advanced tool integration
Agent Capabilities
Each agent exposes its capabilities via REST API:
# List agent capabilities
curl http://localhost:8001/capabilities
curl http://localhost:8002/capabilities
curl http://localhost:8003/capabilities
# Check agent health
curl http://localhost:8001/health
curl http://localhost:8001/capabilities
curl http://localhost:8002/capabilities
curl http://localhost:8003/capabilities
# Check agent health
curl http://localhost:8001/health
Extending the System
To add new agents:
- Inherit from
BaseAgent - Implement required abstract methods
- Add to
CodeQualityOrchestrator.agent_classes - Define capabilities and message handlers
Example agent skeleton:
class MyAgent(BaseAgent):
def __init__(self):
super().__init__("My Agent", 8004, "Does something useful")
async def initialize(self):
# Setup agent-specific resources
pass
def get_capabilities(self):
return [AgentCapability(...)]
async def process_message(self, message):
# Handle incoming messages
pass
async def perform_analysis(self, target):
# Main agent logic
return {}
def __init__(self):
super().__init__("My Agent", 8004, "Does something useful")
async def initialize(self):
# Setup agent-specific resources
pass
def get_capabilities(self):
return [AgentCapability(...)]
async def process_message(self, message):
# Handle incoming messages
pass
async def perform_analysis(self, target):
# Main agent logic
return {}
License
MIT License - feel free to use this in your own projects and presentations!
Complete Setup Guide
1 Installation
git clone <this-repo>
cd multi-agent-example
uv sync --dev
cd multi-agent-example
uv sync --dev
2 API Keys
# Copy and configure environment file
cp .env.example .env
# Edit .env file with your actual API keys:
# OPENAI_API_KEY=sk-your-key-here
# TRACELOOP_API_KEY=tl_your-key-here
# Get your keys from:
# - OpenAI: https://platform.openai.com/account/api-keys
# - Traceloop: https://app.traceloop.com/settings/api-keys
cp .env.example .env
# Edit .env file with your actual API keys:
# OPENAI_API_KEY=sk-your-key-here
# TRACELOOP_API_KEY=tl_your-key-here
# Get your keys from:
# - OpenAI: https://platform.openai.com/account/api-keys
# - Traceloop: https://app.traceloop.com/settings/api-keys
3 Run Complete Demo
# Full A2A system with AI-powered development workflow
uv run python test_a2a_complete.py
# OR test Traceloop dashboard integration
uv run python test_traceloop_export.py
uv run python test_a2a_complete.py
# OR test Traceloop dashboard integration
uv run python test_traceloop_export.py
4 View Results
- Console: Rich visual output with A2A agent communication
- Dashboard: https://app.traceloop.com (shows cross-agent waterfall)
Note: The
.envfile is git-ignored for security. Each developer needs to create their own.envfile with their API keys.
Perfect For
Conference Presentations
- Live Demo: Watch AI agents collaborate in real-time
- Visual Appeal: Rich console output + professional dashboard
- Technical Depth: Real A2A Protocol + OpenTelemetry tracing
- Audience Engagement: Relatable AI-powered development workflow
Educational Use
- Distributed Systems: Agent communication patterns and discovery
- Observability: Cross-service tracing and monitoring
- AI Integration: Practical GPT-4o-mini usage in multi-agent systems
- Modern Protocols: A2A, OpenTelemetry, MCP integration
Production Insights
- Agent Architecture: Scalable multi-agent system design
- Trace Propagation: W3C standards implementation
- Error Handling: Robust failure modes and recovery
- Performance Monitoring: Real-time observability patterns
Questions?
This system demonstrates cutting-edge multi-agent architecture with:
Authentic A2A Protocol (not toy HTTP APIs)
Production-grade tracing (OpenTelemetry + Traceloop)
Real AI integration (GPT-4o-mini for development workflows)
Professional presentation (Rich visuals + dashboard)
Perfect for conference demonstrations, educational workshops, and production architecture examples!