Implementación de Agentes A2A con ADK: Guía Completa de Desarrollo

Tabla de Contenido

Visión General de ADK y Protocolo A2A
Preparación del Entorno e Instalación de Dependencias
Diseño de la Estructura del Proyecto
Desarrollo del Agente Servidor A2A
Desarrollo del Agente Cliente A2A
Configuración de Agentes y Metadatos
Inicio y Pruebas del Servidor A2A
Integración y Pruebas con Web UI
Análisis Detallado del Flujo de Comunicación A2A

Visión General de ADK y Protocolo A2A

¿Qué son ADK y A2A?

ADK (Kit de Desarrollo de Agentes) es un framework de desarrollo de agentes inteligentes creado por Google, mientras que A2A (Protocolo Agent2Agent) es un protocolo estandarizado para comunicación entre agentes. El framework ADK incluye soporte completo para agentes A2A, proporcionando componentes clave como AgenteRemotoA2A, que permiten a los desarrolladores:

Conexión transparente: Implementar comunicación estandarizada entre agentes distribuidos
Desarrollo rápido: Construir sistemas de agentes complejos usando APIs simples
Protocolo estandarizado: Seguir las especificaciones del protocolo A2A para garantizar interoperabilidad
Enrutamiento inteligente: Manejar automáticamente el enrutamiento de mensajes y conversión de formatos
Observabilidad: Funciones integradas de registro y monitoreo

Nota importante: ADK es un framework de desarrollo, mientras que A2A es un protocolo de comunicación. El framework ADK contiene la implementación del protocolo A2A, permitiendo a los desarrolladores construir fácilmente sistemas de agentes inteligentes que soporten comunicación Agent2Agent. Esta guía demostrará cómo utilizar las funcionalidades A2A dentro del framework ADK.

Ventajas Clave de las Funcionalidades A2A en ADK

Arquitectura distribuida: Soporta el despliegue de agentes en diferentes servidores y entornos, comunicándose mediante el protocolo A2A
Protocolo estandarizado: Sigue las especificaciones del protocolo de comunicación A2A, asegurando compatibilidad entre plataformas
Listo para usar: ADK proporciona herramientas CLI completas y Web UI con soporte A2A integrado
Alta escalabilidad: Permite herramientas personalizadas y lógica de negocio compleja, compatible con el ecosistema A2A
Preparado para producción: Garantías de seguridad y fiabilidad a nivel empresarial

Preparación del Entorno e Instalación de Dependencias

Requisitos del Sistema

Python: 3.10 o superior
Sistema operativo: Linux, macOS o Windows
Clave de API: Gemini API Key (para funcionalidades LLM)

Paso 1: Crear el Directorio del Proyecto

# Crear directorio raíz del proyecto
mkdir demo-adk-a2a
cd demo-adk-a2a

# Crear entorno virtual
python -m venv .venv

# Activar entorno virtual
# Linux/macOS:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

Paso 2: Instalar Dependencias de ADK (con soporte A2A)

# Instalar paquete principal de ADK (incluyendo soporte para protocolo A2A)
pip install google-adk[a2a]>=1.6.1

# Verificar instalación
adk --version

Paso 3: Configurar Variables de Entorno

# Crear archivo .env
echo "GOOGLE_API_KEY=tu_clave_gemini_aqui" > .env

# Establecer variables de entorno (temporal)
export GOOGLE_API_KEY="tu_clave_gemini_aqui"

Diseño de la Estructura del Proyecto

Estructura Recomendada para Proyecto A2A con ADK

demo-adk-a2a/
├── .env                    # Configuración de variables de entorno
├── requirements.txt        # Dependencias de Python
├── __init__.py            # Inicialización principal del proyecto
├── agente_cliente.py      # Agente cliente A2A (AgenteRemotoA2A)
├── agentes_remotos/       # Directorio de agentes servidor A2A
│   └── agente_hechos/     # Implementación específica del agente
│       ├── __init__.py    # Inicialización del paquete de agente
│       ├── agente.py      # Lógica principal del agente
│       └── agente.json    # Configuración de metadatos del agente A2A
└── README.md              # Documentación del proyecto

Crear Estructura Básica del Proyecto

# Crear directorios y archivos necesarios
mkdir -p agentes_remotos/agente_hechos
touch __init__.py agente_cliente.py
touch agentes_remotos/agente_hechos/__init__.py
touch agentes_remotos/agente_hechos/agente.py
touch agentes_remotos/agente_hechos/agente.json
touch requirements.txt

Desarrollo del Agente Servidor A2A

Paso 1: Implemantación del Agente Servidor

El agente servidor es el componente principal que ejecuta la lógica de negocio. En agentes_remotos/agente_hechos/agente.py:

# agentes_remotos/agente_hechos/agente.py

from google.adk import Agente
from google.adk.herramientas import busqueda_google

# Definir el agente servidor
agente_principal = Agente(
    # Identificador único del agente
    nombre="agente_hechos",
    
    # Modelo de lenguaje grande a utilizar
    modelo="gemini-2.0-flash",
    
    # Descripción de las capacidades del agente
    descripcion="Agente que proporciona datos interesantes.",
    
    # Instrucciones de comportamiento del agente
    instruccion=(
        "Eres un agente útil que puede proporcionar datos interesantes. "
        "Utiliza la Búsqueda de Google para encontrar información precisa y actualizada. "
        "Siempre proporciona fuentes para tus datos."
    ),
    
    # Lista de herramientas disponibles
    herramientas=[busqueda_google],
)

Paso 2: Configuración de Inicialización del Paquete de Agente

En agentes_remotos/agente_hechos/__init__.py:

# agentes_remotos/agente_hechos/__init__.py

# Importar la implementación del agente para que sea descubrible por ADK
from . import agente

Paso 3: Análisis de las Funciones Principales del Agente Servidor

# Componentes principales del agente

# 1. Nombre (nombre)
# - Debe ser único, utilizado para identificar el agente en la red A2A
# - Se recomienda usar nombres descriptivos

# 2. Modelo (modelo)
# - Especifica el modelo de lenguaje grande a utilizar
# - Soporta modelos de la serie Gemini

# 3. Descripción (descripcion)
# - Breve descripción de las capacidades del agente
# - Se muestra a otros agentes durante el descubrimiento

# 4. Instrucciones (instruccion)
# - Guía de comportamiento detallada
# - Define la personalidad y estilo de respuesta del agente

# 5. Herramientas (herramientas)
# - Herramientas externas que el agente puede invocar
# - Como búsqueda, cálculos, llamadas API, etc.

Desarrollo del Agente Cliente A2A

Paso 1: Crear el Agente Cliente

El agente cliente utiliza AgenteRemotoA2A para conectarse al servicio remoto. En agente_cliente.py:

# agente_cliente.py

from google.adk.agentes.agente_remoto_a2a import AgenteRemotoA2A

# Definir el agente cliente remoto A2A
agente_principal = AgenteRemotoA2A(
    # Nombre del agente cliente
    nombre="agente_hechos",
    
    # Descripción de funcionalidades
    descripcion="Agente que proporciona datos interesantes.",
    
    # URL de la tarjeta del agente remoto
    tarjeta_agente="http://localhost:8001/a2a/agente_hechos/.well-known/agent.json",
)

Paso 2: Configuración Detallada de AgenteRemotoA2A

# Ejemplo de configuración avanzada
agente_principal = AgenteRemotoA2A(
    nombre="agente_hechos",
    descripcion="Agente que proporciona datos interesantes.",
    tarjeta_agente="http://localhost:8001/a2a/agente_hechos/.well-known/agent.json",
    
    # Configuración opcional
    timeout=300.0,          # Tiempo de espera HTTP en segundos
    cliente_httpx=None,     # Cliente HTTP personalizado
)

Paso 3: Principios de Funcionamiento del Agente Cliente

Descubrimiento de agentes: Obtiene información del agente remoto a través de la URL de la tarjeta del agente
Establecimiento de conexión: Crea una conexión HTTP al servidor A2A remoto
Conversión de mensajes: Convierte eventos locales a mensajes del protocolo A2A
Llamada remota: Envía solicitudes al agente remoto
Procesamiento de respuestas: Recibe y convierte las respuestas del agente remoto

Configuración de Agentes y Metadatos

Paso 1: Crear Archivo de Configuración del Agente

En agentes_remotos/agente_hechos/agente.json, definir los metadatos del agente:

{
  "name": "agente_hechos",
  "description": "Agente que proporciona datos interesantes.",
  "url": "http://localhost:8001/a2a/agente_hechos",
  "version": "1.0.0",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "capabilities": {
    "streaming": true,
    "functions": true
  },
  "skills": [
    {
      "id": "proporcionar_hechos",
      "name": "Datos Interesantes",
      "description": "Proporciona datos interesantes sobre varios temas utilizando Búsqueda de Google.",
      "tags": ["información", "datos", "conocimiento", "búsqueda", "google"],
      "examples": [
        "Proporciona un dato interesante sobre la ciudad de Nueva York.",
        "Cuéntame algo fascinante sobre la física cuántica.",
        "¿Cuál es un dato inusual sobre la vida marina?"
      ]
    }
  ]
}

Paso 2: Análisis Detallado de Campos de Configuración

{
  // Información básica
  "name": "Identificador único del agente",
  "description": "Breve descripción de la funcionalidad del agente",
  "url": "URL del punto final del servidor A2A",
  "version": "Número de versión (semántico)",
  
  // Modos de entrada y salida
  "defaultInputModes": ["Formatos de entrada soportados"],
  "defaultOutputModes": ["Formatos de salida soportados"],
  
  // Capacidades del agente
  "capabilities": {
    "streaming": "Soporta respuesta en streaming",
    "functions": "Soporta invocación de funciones"
  },
  
  // Definición de habilidades
  "skills": [
    {
      "id": "Identificador único de la habilidad",
      "name": "Nombre para mostrar de la habilidad", 
      "description": "Descripción detallada de la habilidad",
      "tags": ["etiqueta1", "etiqueta2"],
      "examples": ["Ejemplo de uso 1", "Ejemplo de uso 2"]
    }
  ]
}

Paso 3: Crear Archivo de Dependencias

En requirements.txt:

google-adk[a2a]>=1.6.1

En __init__.py:

# Archivo de inicialización del proyecto
from . import agente_cliente

Inicio y Pruebas del Servidor A2A

Paso 1: Iniciar el Servidor A2A

# Asegurarse de estar en el directorio raíz del proyecto y con el entorno virtual activado
source .venv/bin/activate

# Iniciar el servidor A2A
adk api_server --a2a --port 8001 agentes_remotos

# Salida esperada:
# INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
# INFO:     A2A endpoints enabled for agents: agente_hechos

Paso 2: Verificar los Puntos Finales A2A

# Probar el punto final de descubrimiento de agentes
curl http://localhost:8001/a2a/agente_hechos/.well-known/agent.json

# Debería devolver la configuración JSON del agente

Paso 3: Análisis de la Arquitectura del Servidor A2A

Al iniciar, el servidor A2A crea los siguientes puntos finales:

Punto final de descubrimiento de agentes: /.well-known/agent.json

Proporciona metadatos y capacidades del agente
Utilizado para descubrimiento y configuración automáticos de agentes

Punto final de procesamiento de mensajes: /a2a/{nombre_agente}

Recibe mensajes de otros agentes
Procesa solicitudes del protocolo A2A

Punto final de verificación de salud: /health

Monitoreo del estado del servidor
Sondeo de actividad para balanceadores de carga

Integración y Pruebas con Web UI

Paso 1: Iniciar el Servidor Web de ADK

En una nueva ventana de terminal:

# Activar entorno virtual
source .venv/bin/activate

# Iniciar servidor Web UI
adk web .

# Salida esperada:
# INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
# INFO:     Available agents: agente_hechos

Paso 2: Flujo de Pruebas con Web UI

Acceder a Web UI: Abrir http://localhost:8000 en el navegador
Seleccionar agente: Elegir agente_hechos del menú desplegable
Probar conversación: Ingresar mensaje de prueba, por ejemplo:

"Cuéntame un dato interesante sobre la inteligencia artificial"

Observar respuesta: Verificar si el agente responde correctamente y utiliza la herramienta de búsqueda de Google

Paso 3: Ejemplos de Casos de Prueba

# Caso de prueba 1: Consulta básica de datos
Entrada: ¿Cuál es un dato interesante sobre la Gran Muralla China?
Esperado: Devolver datos interesantes sobre la muralla, incluyendo fuentes de búsqueda

# Caso de prueba 2: Consulta de conocimiento científico  
Entrada: Cuéntame algo fascinante sobre los agujeros negros.
Esperado: Devolver hechos científicos sobre agujeros negros

# Caso de prueba 3: Consulta de eventos actuales
Entrada: ¿Cuál es un descubrimiento reciente en la exploración espacial?
Esperado: Devolver los últimos descubrimientos en exploración espacial

Análisis Detallado del Flujo de Comunicación A2A

Diagrama de Secuencia Completo del Flujo de Comunicación A2A

sequenceDiagram participant Usuario as Usuario participant WebUI as Interfaz Web ADK (localhost:8000) partipante Cliente as Agente Cliente (AgenteRemotoA2A) partipante ServidorA2A as Servidor A2A (localhost:8001) partipante Agente as Agente Servidor (agente_hechos) partipante LLM as Gemini LLM partipante Busqueda as Búsqueda de Google Usuario->>WebUI: 1. Ingresar mensaje de consulta WebUI->>Cliente: 2. Invocar agente cliente Nota sobre Cliente: 3. Verificación de inicialización del agente Cliente->>ServidorA2A: 4. GET /.well-known/agent.json ServidorA2A-->>Cliente: 5. Devolver configuración del agente Nota sobre Cliente: 6. Construir mensaje A2A Cliente->>ServidorA2A: 7. POST /a2a/agente_hechos enviar mensaje A2A ServidorA2A->>Agente: 8. Convertir a evento interno Agente->>LLM: 9. Enviar prompt LLM-->>Agente: 10. Devolver respuesta (con invocación de herramientas) Agente->>Busqueda: 11. Ejecutar Búsqueda de Google Busqueda-->>Agente: 12. Devolver resultados de búsqueda Agente->>LLM: 13. Integrar resultados de búsqueda LLM-->>Agente: 14. Generar respuesta final Agente-->>ServidorA2A: 15. Devolver resultado procesado ServidorA2A-->>Cliente: 16. Devolver respuesta A2A Nota sobre Cliente: 17. Convertir a evento interno Cliente-->>WebUI: 18. Devolver respuesta WebUI-->>Usuario: 19. Mostrar resultado final ### Análisis de Pasos Clave de Comunicación

1. Fase de Descubrimiento de Agentes (Pasos 4-5)

GET http://localhost:8001/a2a/agente_hechos/.well-known/agent.json

Respuesta:
{
  "name": "agente_hechos",
  "url": "http://localhost:8001/a2a/agente_hechos",
  "skills": [...]
}

2. Fase de Envío de Mensaje (Paso 7)

POST http://localhost:8001/a2a/agente_hechos
Content-Type: application/json

{
  "id": "uuid-123",
  "params": {
    "message": {
      "messageId": "msg-456",
      "parts": [{"text": "Cuéntame un dato sobre IA"}],
      "role": "user"
    }
  }
}

3. Fase de Devolución de Respuesta (Paso 16)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": {
    "messageId": "respuesta-789",
    "parts": [{"text": "Aquí tienes un dato interesante sobre IA..."}],
    "role": "agent"
  }
}

Etiquetas: ADK A2A Gemini Python Agentes Inteligentes

Publicado el 6-4 17:34

Friki Work