Skip to content

falconcr/workshop-adk-a2a

BranchesTags

Repository files navigation

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

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
Loading

🤖 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:

# 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:

# 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:

# 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

# Python 3.10+
python --version

# uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

Login google cloud

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

# 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

# .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

# 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

# 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

alt text

CRear un equipo

alt text

🧪 Testing y Demos

# Test Pokemon Agent
cd pokemon_agent
uv run test_client.py

# Test Pokedx Assistant
cd pokedex_assistant  
uv run test_client.py

alt text

Test Pokedx Assistant

cd pokedex_assistant  
uv run test_client.py

alt text

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:

# 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

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.

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license
Activity

Stars

4 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages