Content
# Pokemon Agent Ecosystem - ADK, MCP & A2A Integration
## 📖 Descripción General
Este proyecto es una demostración completa de un ecosistema de agentes inteligentes especializados en información Pokemon, implementado usando tres tecnologías clave de Google:
- **ADK (Agent Development Kit)** - Framework para crear agentes con LLM
- **MCP (Model Context Protocol)** - Protocolo para herramientas y funcionalidades externas
- **A2A (Agent-to-Agent)** - Comunicación e interoperabilidad entre agentes
## 🏗️ Arquitectura del Sistema
### Componentes Principales
```
Pokemon Agent Ecosystem
├── Pokemon Agent (Puerto 10001) # Agente principal de información Pokemon
├── Pokedex Assistant (Puerto 10002) # Agente analítico especializado
├── Master Agent (Puerto 10003) # Agente orquestador
├── Pokemon MCP Server (Puerto 8080) # Servidor de herramientas básicas
└── Analytics MCP Server (Puerto 8081) # Servidor de análisis y comparaciones
```
### Flujo de Datos
```mermaid
graph TB
User[Usuario] --> MA[Master Agent]
MA --> PA[Pokemon Agent]
MA --> PDA[Pokedex Assistant]
PA --> MCP1[Pokemon MCP Server]
PDA --> MCP2[Analytics MCP Server]
MCP1 --> API[PokeAPI]
MCP2 --> API
PA -.->|A2A| PDA
PDA -.->|A2A| PA
```
## 🤖 Agentes del Sistema
### 1. Pokemon Agent (`pokemon_agent/`)
**Puerto:** 10001
**Especialidad:** Información básica de Pokemon
#### Funcionalidades:
- ✅ Información detallada de Pokemon individuales
- ✅ Datos de especies y descripciones
- ✅ Búsqueda y listado de Pokemon
- ✅ Comunicación A2A con Pokedex Assistant
#### Herramientas MCP:
- `get_pokemon_info(pokemon_name)` - Información completa del Pokemon
- `get_pokemon_species(pokemon_name)` - Datos de especie y evolución
- `search_pokemon(limit, offset)` - Búsqueda paginada
#### Capacidades A2A:
- Puede solicitar análisis comparativos al Pokedex Assistant
- Maneja derivaciones de consultas analíticas
- Colaboración automática para respuestas complejas
### 2. Pokedex Assistant (`pokedex_assistant/`)
**Puerto:** 10002
**Especialidad:** Análisis y comparaciones Pokemon
#### Funcionalidades:
- 📊 Comparaciones estadísticas detalladas
- ⚔️ Análisis de efectividad de tipos
- 🎯 Generación de trivia y datos curiosos
- 📈 Rankings estadísticos
#### Herramientas MCP:
- `compare_pokemon_stats(pokemon1, pokemon2)` - Comparación estadística
- `calculate_type_effectiveness(attacker_type, defender_types)` - Efectividad de tipos
- `generate_pokemon_trivia(pokemon_name)` - Trivia y curiosidades
- `get_stat_rankings(stat_name, limit)` - Rankings por estadística
#### Capacidades A2A:
- Puede solicitar información básica al Pokemon Agent
- Especializado en análisis profundos y educativos
- Proporciona insights estadísticos avanzados
### 3. Master Agent (`master-agent/`)
**Puerto:** 10003
**Especialidad:** Orquestación y coordinación
#### Funcionalidades:
- 🎭 Coordinación entre agentes especializados
- 🔀 Enrutamiento inteligente de consultas
- 📋 Gestión de flujos de trabajo complejos
- 🤝 Orquestación de colaboraciones A2A
## 🛠️ Servidores MCP
### Pokemon MCP Server (`mcp-server/`)
**Puerto:** 8080
**Propósito:** Herramientas básicas de Pokemon
#### Herramientas Disponibles:
```python
# Información básica
get_pokemon_info(pokemon_name: str) -> Dict
# Datos de especie
get_pokemon_species(pokemon_name: str) -> Dict
# Búsqueda y listado
search_pokemon(limit: int = 20, offset: int = 0) -> Dict
```
### Analytics MCP Server (`analytics-mcp-server/`)
**Puerto:** 8081
**Propósito:** Análisis y comparaciones avanzadas
#### Herramientas Disponibles:
```python
# Comparaciones estadísticas
compare_pokemon_stats(pokemon1: str, pokemon2: str) -> Dict
# Análisis de batalla
calculate_type_effectiveness(attacker_type: str, defender_types: List[str]) -> Dict
# Generación de trivia
generate_pokemon_trivia(pokemon_name: str) -> Dict
# Rankings estadísticos
get_stat_rankings(stat_name: str, limit: int = 10) -> Dict
```
## 🔄 Comunicación A2A (Agent-to-Agent)
### Protocolo de Comunicación
El sistema implementa comunicación A2A bidireccional entre agentes:
```python
# Pokemon Agent solicitando análisis
comparison = await pokemon_agent.request_pokemon_comparison("Pikachu", "Raichu")
# Pokedex Assistant solicitando información básica
basic_info = await assistant_agent.request_pokemon_info("Charizard")
```
### Patrones de Colaboración
1. **Derivación Inteligente**
- Pokemon Agent deriva consultas analíticas → Pokedex Assistant
- Pokedex Assistant solicita información básica → Pokemon Agent
2. **Análisis Colaborativo**
- Combinación de datos básicos + análisis profundo
- Respuestas enriquecidas con múltiples perspectivas
3. **Flujos de Trabajo Complejos**
- Orquestación via Master Agent
- Secuencias de tareas coordinadas
## ✨ Ventajas de la Arquitectura
### 🎯 Especialización por Dominio
- **Separación de responsabilidades**: Cada agente tiene un propósito específico
- **Expertise focalizado**: Pokemon Agent para datos, Assistant para análisis
- **Escalabilidad**: Fácil agregar nuevos agentes especializados
### 🔌 Modularidad MCP
- **Herramientas reutilizables**: Servidores MCP independientes
- **Fácil mantenimiento**: Lógica de negocio separada de agentes
- **Testabilidad**: Cada componente se puede probar por separado
### 🤝 Colaboración A2A
- **Interoperabilidad**: Agentes pueden comunicarse seamlessly
- **Enriquecimiento de respuestas**: Combinación automática de capacidades
- **Flujos complejos**: Orquestación de tareas multi-agente
### 📈 Escalabilidad y Extensibilidad
- **Horizontal**: Agregar nuevos agentes especializados
- **Vertical**: Extender capacidades de agentes existentes
- **Plug-and-play**: Nuevos servidores MCP sin modificar agentes
## 🚀 Configuración e Instalación
### Prerequisitos
```bash
# Python 3.10+
python --version
# uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Login google cloud
```bash
gcloud auth login
gcloud config set project [ID_DE_TU_PROYECTO]
# Si necesitas verificar qué cuenta está activa o qué proyecto está configurado, puedes usar:
gcloud auth list
gcloud config list
```
### Instalación
```bash
# Clonar proyecto
git clone <repository-url>
cd pokemon-agent
# Instalar dependencias
uv sync
# Configurar variables de entorno
cp .env.example .env
# Editar .env con configuración necesaria
```
### Configuración de Variables
```bash
# .env
GOOGLE_API_KEY=your_gemini_api_key
A2A_HOST=localhost
A2A_PORT=10001
A2A_PORT_ASSISTANT=10002
A2A_PORT_MASTER=10003
MCP_SERVER_URL=http://localhost:8080/mcp
ANALYTICS_MCP_SERVER_URL=http://localhost:8081/mcp
POKEMON_AGENT_URL=http://localhost:10001
ASSISTANT_AGENT_URL=http://localhost:10002
```
## 🏃♂️ Ejecución
### Iniciar Servidores MCP
```bash
# Terminal 1 - Pokemon MCP Server
cd mcp-server
uv run server.py
# Terminal 2 - Analytics MCP Server
cd analytics-mcp-server
uv run server.py
```
### Iniciar Agentes
```bash
# Terminal 3 - Pokemon Agent
uv run uvicorn pokemon_agent.agent:a2a_app --host localhost --port 10001
# Terminal 4 - Pokedex Assistant
uv run uvicorn pokedex_assistant.agent:a2a_app --host localhost --port 10002
# Terminal 5 - Master Agent
uv run adk web
```
## 📝 Ejemplos de Uso

### CRear un equipo

## 🧪 Testing y Demos
```bash
# Test Pokemon Agent
cd pokemon_agent
uv run test_client.py
# Test Pokedx Assistant
cd pokedex_assistant
uv run test_client.py
```

### Test Pokedx Assistant
```bash
cd pokedex_assistant
uv run test_client.py
```

### Workflows Disponibles:
1. **Individual Agent Queries** - Consultas directas a cada agente
2. **Collaborative Analysis** - Análisis que requiere ambos agentes
3. **Specialized Queries** - Funcionalidades específicas por agente
4. **Interactive Mode** - Modo interactivo para testing manual
### Comandos de Testing:
```bash
# Modo interactivo
> pokemon Tell me about Mew
> assistant Compare Mew vs Mewtwo
> compare Pikachu Raichu
> quit
```
## 🛡️ Consideraciones de Seguridad y Producción
### Seguridad
- Variables de entorno para API keys
- Timeouts en comunicaciones HTTP
- Validación de entrada en herramientas MCP
- Logging estructurado para debugging
### Monitoreo
- Logs detallados en cada componente
- Métricas de performance por agente
- Tracking de comunicaciones A2A
- Health checks para servidores MCP
### Escalabilidad
- Arquitectura stateless
- Comunicación HTTP asíncrona
- Balanceeo de carga posible
- Contenainerización ready
## 📚 Recursos Adicionales
### Documentación Técnica
- [Google ADK Documentation](https://cloud.google.com/agent-builder)
- [MCP Protocol Specification](https://spec.modelcontextprotocol.io/)
- [PokeAPI Documentation](https://pokeapi.co/docs/v2)
### Arquitectura de Referencia
- **Microservicios**: Cada agente como servicio independiente
- **Event-driven**: Comunicación asíncrona entre componentes
- **Domain-driven**: Separación por dominios de conocimiento
- **API-first**: Interfaces bien definidas entre servicios
## 🤝 Contribución
### Estructura para Nuevos Agentes
1. Crear directorio `new_agent/`
2. Implementar `agent.py` con ADK + A2A
3. Definir `AgentCard` con skills específicos
4. Configurar puerto único en variables de entorno
5. Documentar en README
### Estructura para Nuevos MCP Servers
1. Crear directorio `new_mcp_server/`
2. Implementar herramientas con FastMCP
3. Configurar puerto único
4. Agregar tests en `test_server.py`
5. Actualizar documentación de herramientas
---
**🎯 Objetivo:** Demostrar las capacidades de ADK, MCP y A2A en un ecosistema de agentes especializados, colaborativos y escalables.