Content
# Agent-to-Agent Protocol Implementation
**Complete Google A2A SDK Integration**: Universal agent discovery and communication using Google's A2A protocol with enhanced semantic search, full JSON-RPC 2.0 compliance, and Temporal workflow orchestration.
## 🎉 What's Working - Complete End-to-End Demo
🚀 **[RUN THE DEMO](demo/end_to_end_demo.py)** - See Google A2A SDK communicate with our agents!
### ✅ Complete Flow Working:
1. **Google SDK** discovers agents via A2A Gateway (unified API)
2. **SDK creates A2AClient** pointing to our A2A Gateway
3. **Gateway implements** full JSON-RPC 2.0 A2A protocol + discovery extensions
4. **Gateway routes** tasks through Temporal to workers
5. **Workers process** tasks and return results
6. **SDK receives** complete A2A-compliant responses
```bash
# Quick Demo
python demo/end_to_end_demo.py
# Example Output:
# ✅ Found Echo Agent: http://a2a-gateway:3000
# ✅ Task created successfully!
# ✅ Task result: "Echo: Hello from Google A2A SDK!"
# 🎉 COMPLETE A2A FLOW SUCCESS!
```
## 🚀 Quick Start
```bash
# 1. Clone and setup
git clone <repository-url>
cd agent-to-agent
# 2. Add your OpenAI API key to .env file
echo "OPENAI_API_KEY=your-key-here" >> .env
# 3. Start the complete stack
docker-compose up -d
# 4. Verify A2A Gateway
curl http://localhost:3000/health
# 5. Test agent registry
curl http://localhost:8001/health
# 6. Run end-to-end demo
python demo/end_to_end_demo.py
```
## 🏗️ Complete Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐
│ Google A2A SDK │────────▶│ A2A Gateway │────────▶│ Enhanced Agent │
│ │ │ (JSON-RPC 2.0) │ │ Registry │
│ - Agent Discovery│ │ │ │ │
│ - A2AClient │ │ - x-discoverAgents│ │ - Semantic Search│
│ - Task Management│ │ - x-registerAgent │ │ - Vector DB │
└─────────────────┘ │ - createTask │ │ - Google SDK │
│ - getTask │ │ Compatible │
│ - sendMessage │ └──────────────────┘
│ - cancelTask │
└─────────────────┘
│
▼
┌──────────────────┐ ┌─────────────────┐
│ Temporal │ │ Workers │
│ Workflows │◀───│ - Echo Agent │
│ │ │ - LangChain │
│ - Task Routing │ │ - CrewAI │
│ - State Mgmt │ │ - AutoGen │
└──────────────────┘ └─────────────────┘
```
## ✅ Features Complete
### 🎯 Google A2A SDK Integration
- **✅ Full SDK Compatibility**: AgentCard structure matches Google SDK
- **✅ JSON-RPC 2.0 Protocol**: Complete A2A protocol implementation
- **✅ Agent Discovery**: Enhanced semantic search with vector embeddings
- **✅ Task Management**: Create, get, send messages, cancel tasks
- **✅ End-to-End Demo**: Working Google SDK → Gateway → Worker flow
### 🚀 Enhanced Agent Registry
- **✅ Semantic Search**: OpenAI embeddings for intelligent agent matching
- **✅ Google SDK Compatible**: Returns proper AgentCard format
- **✅ Multi-Framework**: LangChain, CrewAI, AutoGen, Custom agents
- **✅ CLI Management**: Complete agent registry CLI tool
- **✅ Vector Database**: Qdrant for fast semantic discovery
### ⚙️ Production Infrastructure
- **✅ A2A Gateway**: Complete JSON-RPC 2.0 A2A protocol server
- **✅ Temporal Integration**: Workflow orchestration and task routing
- **✅ Generic Metadata Support**: Store and query tasks by arbitrary metadata
- **✅ Conversation Coordination**: Link tasks across multi-turn agent interactions
- **✅ Agent Tool Registry**: Centralized tool discovery and management service
- **✅ Agent Memory Service**: Redis-backed conversation state management
- **✅ Input Normalization**: Converts various inputs to A2A message format
- **✅ Output Extraction**: Returns both structured messages and simple text
- **✅ Health Monitoring**: Prometheus, Grafana, Jaeger observability
- **✅ Security**: Proper authentication schemes and validation
### 🛠️ Agent Management Tools
- **✅ Registry CLI**: List, create, delete, search agents
- **✅ Pre-built Agent Cards**: JSON files for common agent types
- **✅ Documentation**: Complete setup and usage guides
- **✅ Examples**: Working demos and integration tests
## 🎯 Key Components
### Agent Registry (Port 8001)
```bash
# Semantic agent discovery
curl "http://localhost:8001/agents/discover?keyword=python%20security"
# Health check
curl http://localhost:8001/health
```
### A2A Gateway (Port 3000)
```bash
# Create task via A2A protocol
curl -X POST http://localhost:3000/a2a \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"a2a.createTask","params":{"agentId":"echo-agent","input":{"message":"Hello"}},"id":"1"}'
# Health check
curl http://localhost:3000/health
```
### Registry CLI Tool
```bash
# List all agents
python tools/registry-cli.py list
# Search agents
python tools/registry-cli.py search "security"
# Create agent from JSON
python tools/registry-cli.py create tools/agents/echo-agent.json
# Get agent details
python tools/registry-cli.py get agent-123 --details
```
## 📊 Service URLs
| Service | URL | Description |
|---------|-----|-------------|
| A2A Gateway | http://localhost:3000 | JSON-RPC 2.0 A2A Protocol |
| Agent Registry | http://localhost:8001 | Agent discovery & management |
| Agent Memory Service | http://localhost:8002 | Conversation state management |
| Agent Tool Registry | http://localhost:8003 | Tool discovery & management |
| Temporal UI | http://localhost:8088 | Workflow monitoring |
| Grafana | http://localhost:3001 | Metrics dashboard |
| Prometheus | http://localhost:9090 | Metrics collection |
| Jaeger | http://localhost:16686 | Distributed tracing |
## 🔧 Environment Configuration
### Required Variables
```bash
# .env file
OPENAI_API_KEY=your-openai-api-key-here
EMBEDDING_PROVIDER=openai
NODE_ENV=production
```
### Optional Variables
```bash
# Temporal configuration
TEMPORAL_HOST=temporal
TEMPORAL_PORT=7233
TEMPORAL_NAMESPACE=default
# Database configuration
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=temporal
# Redis configuration
REDIS_HOST=redis
REDIS_PORT=6379
# Qdrant configuration
QDRANT_URL=http://qdrant:6333
```
## 🚀 Usage Examples
### 1. End-to-End Demo with Google SDK
```python
# Run the complete demo
python demo/end_to_end_demo.py
# Shows:
# - Agent discovery via registry
# - Google SDK AgentCard creation
# - A2AClient communication
# - Task creation and management
# - Echo response retrieval
```
### 2. Agent Management with CLI
```bash
# Health check
python tools/registry-cli.py health
# List agents with details
python tools/registry-cli.py list --details
# Search for specific capabilities
python tools/registry-cli.py search "multi-agent orchestration"
# Create new agent
python tools/registry-cli.py create tools/agents/crewai-agent.json
```
### 3. Direct A2A Protocol Testing
```bash
# Create task
curl -X POST http://localhost:3000/a2a \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "a2a.createTask",
"params": {
"agentId": "echo-agent",
"input": {"message": "Hello World"}
},
"id": "test-001"
}'
# Get task result
curl -X POST http://localhost:3000/a2a \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "a2a.getTask",
"params": {"taskId": "your-task-id"},
"id": "test-002"
}'
```
## 📚 Documentation
### Quick Start Guides
- **[End-to-End Demo Guide](demo/README.md)** - Complete working examples
- **[Agent Registry CLI](tools/README.md)** - Command-line tools
- **[Docker Setup](docs/development/docker-guide.md)** - Container management
### Architecture & Design
- **[High-Level Overview](docs/architecture/high-level-overview.md)** - System design
- **[A2A Protocol Details](docs/api/a2a-protocol.md)** - Protocol specification
- **[Framework Integration](docs/architecture/framework-integration.md)** - Multi-framework support
### API Documentation
- **[Agent Registry API](docs/api/rest-api.md)** - HTTP endpoints
- **[A2A Gateway API](docs/api/a2a-protocol.md)** - JSON-RPC methods
- **[Error Codes](docs/A2A-Error-Codes.md)** - Complete error reference
### Development
- **[Setup Guide](docs/development/setup.md)** - Development environment
- **[Contributing](docs/contributing/README.md)** - How to contribute
- **[Project Status](docs/contributing/PROJECT-STATUS.md)** - Current state
## 🎉 Agent Types Available
### Pre-configured Agents
1. **Echo Agent** (`tools/agents/echo-agent.json`)
- Simple testing agent that echoes messages
- Perfect for testing A2A protocol flow
2. **Python Security Expert** (`tools/agents/python-security-agent.json`)
- Vulnerability scanning and code review
- Security analysis and recommendations
3. **CrewAI Orchestrator** (`tools/agents/crewai-agent.json`)
- Multi-agent coordination and task delegation
- Complex workflow management
4. **AutoGen Conversational** (`tools/agents/autogen-agent.json`)
- Multi-turn conversations and code generation
- Human-in-the-loop workflows
5. **LangChain Reasoning** (`tools/agents/langchain-agent.json`)
- Chain-of-thought reasoning and tool usage
- Document analysis and research
## 🔄 Complete Integration Flow
1. **Discovery**: Use A2A Gateway's discovery methods to find relevant agents
2. **Connection**: Google SDK creates A2AClient to gateway URL
3. **Communication**: Send messages via JSON-RPC 2.0 A2A protocol
4. **Processing**: Gateway routes through Temporal to workers
5. **Response**: Get structured results with both text and message format
## 🎯 What's Next
### Current Status: ✅ COMPLETE
- Google A2A SDK integration working end-to-end
- All core A2A protocol methods implemented
- Enhanced semantic discovery operational
- Complete agent management tooling
- Production-ready infrastructure
### Future Enhancements
- Additional AI framework integrations
- Advanced security schemes (OAuth2, JWT)
- Real-time agent health monitoring
- Cross-agent collaboration workflows
- Performance optimizations
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
This project is free for commercial and personal use.
## 🤝 Contributing
1. **Run the demo**: `python demo/end_to_end_demo.py`
2. **Read the docs**: Check [docs/contributing/README.md](docs/contributing/README.md)
3. **Follow guidelines**: See [docs/contributing/guidelines.md](docs/contributing/guidelines.md)
4. **Check status**: Review [docs/contributing/PROJECT-STATUS.md](docs/contributing/PROJECT-STATUS.md)
---
**Status**: ✅ **COMPLETE** - Google A2A SDK Integration Operational
**Demo**: `python demo/end_to_end_demo.py` for live demonstration
**Architecture**: Full A2A protocol with enhanced semantic discovery
