Se usó la API de Cloud Translation para traducir esta página.

Crea un sistema multiagente con el ADK, impleméntalo en Agent Engine y comienza a usar el protocolo A2A

1. Objetivo de este lab

En este lab práctico, compilarás una aplicación de varios agentes que genera una imagen según tu instrucción y la evalúa en función de ella. Si la imagen no cumple con los requisitos descritos en la instrucción de manera satisfactoria, el agente generará imágenes de forma continua hasta que se genere la imagen que cumpla con tus requisitos. Cada uno de los agentes de este ejercicio práctico tiene un solo propósito, y los agentes cooperan entre sí para lograr el objetivo general.

Qué aprenderás

Comprende los conceptos básicos del ADK y aprende a crear un sistema multiagente.
Aprende a implementar y usar fácilmente los agentes en GCP.
Comprende los conceptos básicos del protocolo A2A
Aprende a usar el protocolo A2A y el ADK juntos para crear agentes abiertos.

2. Antes de comenzar

Si aún no tienes un proyecto que puedas usar, deberás crear uno nuevo en la consola de GCP.
En este lab, usaremos GCP Cloud Shell para realizar nuestras tareas. Abre Cloud Shell y configura el proyecto con Cloud Shell.
Presiona el botón del editor de Cloud Shell para abrir el editor de Cloud Shell de GCP. Si ves la ventana emergente "Autorizar Shell", haz clic para autorizar el editor de Cloud Shell.
Puedes verificar si el proyecto ya está autenticado con el siguiente comando.

gcloud auth list

En Cloud Shell, ejecuta el siguiente comando para confirmar tu proyecto.

gcloud config list project

Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:

gcloud config set project <YOUR_PROJECT_ID>

Debemos habilitar algunos servicios para ejecutar este lab. Ejecuta el siguiente comando en Cloud Shell.

gcloud services enable aiplatform.googleapis.com

3. Descripción general: Beneficios del Kit de desarrollo de agentes

El kit de desarrollo de agentes ofrece varias ventajas clave para los desarrolladores que crean aplicaciones basadas en agentes:

Sistemas multiagente: Crea aplicaciones modulares y escalables componiendo varios agentes especializados en una jerarquía. Permite una coordinación y delegación complejas.
Ecosistema de herramientas enriquecido: Equipa a los agentes con diversas capacidades: usa herramientas prediseñadas (búsqueda, ejecución de código, etcétera), crea funciones personalizadas, integra herramientas de frameworks de agentes de terceros (LangChain, CrewAI) o incluso usa otros agentes como herramientas.
Organización flexible: Define flujos de trabajo con agentes de flujo de trabajo (SequentialAgent, ParallelAgent y LoopAgent) para canalizaciones predecibles o aprovecha el enrutamiento dinámico basado en LLM (transferencia de LlmAgent) para un comportamiento adaptable.
Experiencia del desarrollador integrada: Desarrolla, prueba y depura de forma local con una potente CLI y una IU interactiva para desarrolladores. Inspecciona los eventos, el estado y la ejecución del agente paso a paso.
Evaluación integrada: Evalúa sistemáticamente el rendimiento del agente analizando la calidad de la respuesta final y la trayectoria de ejecución paso a paso en comparación con casos de prueba predefinidos.
Listo para la implementación: Aloja tus agentes en contenedores e impleméntalos en cualquier lugar. Ejecútalos de forma local, escálalos con Vertex AI Agent Engine o intégralos en una infraestructura personalizada con Cloud Run o Docker.

Si bien otros SDKs de IA generativa o frameworks de agentes también te permiten consultar modelos y hasta potenciarlos con herramientas, la coordinación dinámica entre varios modelos requiere una gran cantidad de trabajo de tu parte.

El Agent Development Kit ofrece un framework de nivel superior que estas herramientas, lo que te permite conectar fácilmente varios agentes entre sí para flujos de trabajo complejos, pero fáciles de mantener.

4. Introducción a A2A

El protocolo Agent2Agent (A2A) es un estándar abierto diseñado para permitir la comunicación y la colaboración fluidas y seguras entre agentes autónomos de IA de diferentes frameworks, proveedores y dominios.

Interoperabilidad universal: A2A permite que los agentes trabajen juntos independientemente de sus tecnologías subyacentes, lo que fomenta un ecosistema verdaderamente multiagente. Esto significa que los agentes creados por diferentes empresas en diferentes plataformas pueden comunicarse y coordinarse.
Descubrimiento de capacidades: Los agentes pueden anunciar sus capacidades con "tarjetas de agente" (documentos JSON) que describen su identidad, las funciones de A2A compatibles, las habilidades y los requisitos de autenticación. Esto permite que otros agentes descubran y seleccionen el más adecuado para una tarea determinada.
Seguridad ante todo: La seguridad es un principio fundamental. La A2A incorpora mecanismos de autenticación y autorización de nivel empresarial, y utiliza estándares como HTTPS/TLS, JWT, OIDC y claves de API para garantizar interacciones seguras y proteger los datos sensibles.
Independiente de la modalidad: El protocolo admite varias modalidades de comunicación, como transmisión de texto, audio y video, así como formularios interactivos y elementos iframe incorporados. Esta flexibilidad permite que los agentes intercambien información en el formato más adecuado para la tarea y el usuario.
Administración de tareas estructurada: A2A define protocolos claros para la delegación, la supervisión y la finalización de tareas. Admite el agrupamiento de tareas relacionadas y su administración en diferentes agentes con IDs de tareas únicos. Las tareas pueden pasar por ciclos de vida definidos (p.ej., enviada, en curso, completada).
Ejecución opaca: Una característica importante es que los agentes no necesitan revelar sus procesos de razonamiento internos, su memoria ni sus herramientas específicas a otros agentes. Solo exponen sus servicios invocables, lo que promueve la modularidad y la privacidad.
Basada en estándares existentes: La API de A2A aprovecha tecnologías web establecidas, como HTTP, eventos enviados por el servidor (SSE) para la transmisión en tiempo real y JSON-RPC para el intercambio de datos estructurados, lo que facilita la integración con la infraestructura de TI existente.
Comunicación asíncrona: El protocolo se diseñó con la comunicación asíncrona como una consideración principal, lo que facilita la progresión flexible de las tareas y habilita las notificaciones push para las actualizaciones, incluso cuando no se mantiene una conexión de forma persistente.

5. Arquitectura del agente

En este lab, crearás una aplicación de varios agentes que genera una imagen según tus especificaciones y la evalúa antes de presentártela.

El sistema se estructura con un agente principal llamado image_scoring que coordina todo el proceso. Este agente principal tiene un subagente llamado image_generation_scoring_agent, que, a su vez, tiene sus propios subagentes para tareas más específicas. Esto crea una relación jerárquica en la que el agente principal delega tareas a sus subagentes. Figura 2: Flujo general del agente.

Lista de todos los agentes

image_scoring (agente principal):
Propósito: Este es el agente raíz que administra el flujo de trabajo general. Ejecuta de forma repetida los agentes image_generation_scoring_agent y checker_agent en un bucle hasta que se cumpla una condición de finalización.
Subagentes:

image_generation_scoring_agent
checker_agent_instance

image_generation_scoring_agent (subagente de image_scoring):
Propósito: Este agente es responsable de la lógica principal de generación y puntuación de imágenes. Para lograrlo, ejecuta una secuencia de tres subagentes.
Subagentes:

image_generation_prompt_agent
image_generation_agent
scoring_images_prompt

checker_agent_instance (subagente de image_scoring):
Propósito: Este agente verifica si el proceso de calificación de imágenes debe continuar o finalizar. Utiliza la herramienta check_tool_condition para evaluar la condición de finalización.
image_generation_prompt_agent (subagente de image_generation_scoring_agent):
Propósito: Este agente es experto en crear instrucciones para la generación de imágenes. Toma un texto de entrada y genera un mensaje detallado adecuado para el modelo de generación de imágenes.
mage_generation_agent (subagente de image_generation_scoring_agent):
Propósito: Este agente es experto en la creación de imágenes con Imagen 3. Toma la instrucción del image_generation_prompt_agent y genera una imagen.
scoring_images_prompt (subagente de image_generation_scoring_agent):
Propósito: Este agente es experto en evaluar y calificar imágenes según diversos criterios. Toma la imagen generada y le asigna una puntuación.

Herramientas que usan los agentes

check_tool_condition:
Descripción: Esta herramienta verifica si se cumple la condición de finalización del bucle o si se alcanzó la cantidad máxima de iteraciones. Si se cumple alguna de estas condiciones, se detiene el bucle.
Usado por: checker_agent_instance
generate_images:
Descripción: Esta herramienta genera imágenes con el modelo Imagen 3. También puede guardar las imágenes generadas en un bucket de Google Cloud Storage.
Usado por: image_generation_agent
get_policy:
Descripción: Esta herramienta recupera una política de un archivo JSON. El image_generation_prompt_agent usa la política para crear la instrucción de generación de imágenes, y el scoring_images_prompt la usa para calificar las imágenes.
Usado por: image_generation_prompt_agent, scoring_images_prompt
get_image:
Descripción: Esta herramienta carga el artefacto de imagen generado para que se pueda calificar.
Usado por: scoring_images_prompt
set_score:
Descripción: Esta herramienta establece la puntuación total de la imagen generada en el estado de la sesión.
Usado por: scoring_images_prompt

6. Tarea 1: Instala el ADK y configura tu entorno

En este ejercicio práctico, usaremos Cloud Shell para realizar las tareas.

Habilita las APIs recomendadas de Vertex AI

En la parte superior de la consola de Google Cloud, busca Vertex AI.
Haz clic en Habilitar todas las APIs recomendadas.

Prepara una pestaña del editor de Cloud Shell

Con la ventana de la consola de Google Cloud seleccionada, abre Cloud Shell presionando la tecla G y, luego, la tecla S. Como alternativa, puedes hacer clic en el botón de Cloud Shell en la esquina superior derecha de la consola de Google Cloud.
Haz clic en Continuar.
Cuando se te solicite que autorices Cloud Shell, haz clic en Autorizar.
En la esquina superior derecha del panel de Cloud Shell, haz clic en el botón Abrir en una ventana nueva .
Haz clic en el ícono de lápiz Abrir editor ( ) en la parte superior del panel para ver los archivos.
En la parte superior del menú de navegación de la izquierda, haz clic en el ícono del Explorador para abrir el explorador de archivos.
Haz clic en el botón Abrir carpeta.
Durante el resto de este lab, puedes trabajar en esta ventana como tu IDE con el editor de Cloud Shell y la terminal de Cloud Shell.

Descarga e instala el ADK y las muestras de código para este lab

Ejecuta los siguientes comandos para clonar el código fuente necesario desde GitHub y, luego, instalar las bibliotecas necesarias.

#create the project directory
mkdir imagescoring
cd imagescoring
#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git

#Create the virtual environment
python3 -m venv pythonenv
source pythonenv/bin/activate

#install google-adk and a2a sdk
python3 -m pip install google-adk==1.8.0
python3 -m pip install a2a-sdk==0.2.16

Usaremos Poetry para instalar requisitos adicionales:

cd multiagenthandson #go to the application directory
pip install poetry poetry-plugin-export
poetry install --with deployment

Si no tienes un bucket de Cloud Storage, crea uno nuevo en Google Cloud Storage. También puedes crear el bucket con el comando gsutil.

gsutil mb gs://YOUR-UNIQUE-BUCKETNAME

En el editor, ve a View->Toggle hidden files. En la carpeta image_scoring, crea un archivo .env con el siguiente contenido. Agrega los detalles necesarios, como el nombre del proyecto y el bucket de Cloud Storage.

GOOGLE_GENAI_USE_VERTEXAI=1 #1 if VERTEXAI has to be used. Can be 0 if API_KEY is specified
GOOGLE_CLOUD_PROJECT=YOUR CLOUD PROJECT NAME
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=YOUR BUCKET NAME  # Only required for deployment on Agent Engine
GCS_BUCKET_NAME=YOUR BUCKET NAME #Bucket for storing generated images.
SCORE_THRESHOLD=40 # Min threshold for image_score. Max Score is 50 , hence should be less than 50. 
#If the computed score is higher then loop will terminate
#MAX_ITERATIONS=5 #Max iterations for evaluating the image_score before terminating the loop.
IMAGEN_MODEL="imagen-3.0-generate-002" 
GENAI_MODEL="gemini-2.5-flash"
#AGENT_ENGINE_ID=<AGENT_ENGINE_ID> #The Agent Engine ID obtained after deploying to the agent engine.

Observa la estructura del agente en el código fuente, comenzando por agent.py . Este agente contiene el agente raíz que se conectará a los demás agentes.
Regresa al directorio superior multiagenthandson en la terminal y ejecuta el siguiente comando para ejecutar el agente de forma local.

# Run the following command to run agents locally
export GCS_BUCKET_NAME=your gcs bucket name
adk web

Figura 1

Haz Ctrl+clic (CMD+clic para macOS) en la URL http:// que se muestra en la terminal para abrir el cliente de GUI basado en el navegador del ADK. Debería verse como en la Figura 2.

Generemos algunas imágenes. Prueba las siguientes instrucciones o las tuyas.
Un paisaje montañoso tranquilo al atardecer
Un gato andando en bicicleta

Figura 2

7. Tarea 2: Implementa en Agent Engine

Ahora implementaremos el agente en Agent Engine. Agent Engine es un servicio completamente administrado para implementar agentes en GCP. Agent Engine es compatible con el ADK, por lo que los agentes creados con el ADK se pueden implementar en Agent Engine.

Define algunas variables de entorno

export GOOGLE_CLOUD_LOCATION='us-central1'
export GOOGLE_CLOUD_PROJECT='your project id'

Crea el archivo requirements.txt con Poetry. Poetry usará pyproject.toml para crear el archivo requirements.txt. Después de ejecutar el comando, verifica si se creó el archivo requirements.txt.

# Go to the parent folder containing pyproject.toml file
# install poetry-plugin-export
pip install poetry-plugin-export

#Create requirements.txt file
poetry export -f requirements.txt --output requirements.txt --without-hashes

Crea el paquete. Debemos agrupar nuestra app en un paquete de Python .whl. Usaremos poesía para hacerlo. Una vez que ejecutes el comando, asegúrate de que se cree una carpeta dist y que contenga el archivo .whl.

# Go to the parent folder containing pyproject.toml file
#Create python package, to create whl file
poetry build

Ahora prepararemos la secuencia de comandos de implementación. La secuencia de comandos de implementación implementará nuestro agente de puntuación de imágenes o el servicio de Agent Engine. Cambia el contenido de deploy.py dentro de la carpeta image_scoring como se muestra a continuación.

# Change the content of the following. Look for #change this comment
import vertexai
from .agent import root_agent
import os
import glob # To easily find the wheel file

PROJECT_ID = "YOUR PROJECT ID" #change this your project
LOCATION = "us-central1" #change this
STAGING_BUCKET = "gs://YOUR BUCKET " #change this to your bucket

from vertexai import agent_engines

vertexai.init(
   project=PROJECT_ID,
   location=LOCATION,
   staging_bucket=STAGING_BUCKET,
)

remote_app = agent_engines.create(
   agent_engine=root_agent,
   requirements=open(os.path.join(os.getcwd(), "requirements.txt")).readlines()+["./dist/image_scoring-0.1.0-py3-none-any.whl"],#change this to your local location
   extra_packages=[
       "./dist/image_scoring-0.1.0-py3-none-any.whl", # change this to your location
   ]
)

print(remote_app.resource_name)

Ahora podemos ejecutar la secuencia de comandos de implementación.

#run deploy script from the parent folder containing deploy.py
python3 -m image_scoring.deploy

Después de la implementación, deberías ver algo similar a lo siguiente:

Figura 3

Ahora probemos el agente implementado. Para probar el motor del agente implementado de forma remota, primero copia la ubicación del agente del resultado de la implementación en la terminal. Debería verse algo similar a esto: projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 .
Ve a la carpeta testclient, abre el archivo remote_test.py y edita las siguientes líneas.

PROJECT_ID = "" #change this
LOCATION = "" #change this
STAGING_BUCKET = "" #change this

#replace the id with your own.
reasoning_engine_id="your agent engine id"

#You can replace this with your own prompt
image_prompt="A cat riding a bicycle"

#execute remote_test.py
python3 remote_test.py

8. Tarea 3: Crea un agente de A2A

En este paso, crearemos un agente de A2A simple basado en el agente que creamos en los pasos anteriores. Los agentes de ADK existentes se pueden publicar con el protocolo A2A. Estos son los aspectos clave que aprenderás en este paso.

Aprende los conceptos básicos del protocolo A2A.
Obtén información sobre cómo funcionan los protocolos ADK y A2A entre sí.
Aprende a interactuar con el protocolo A2A.

En esta práctica, usaremos el código de la carpeta image_scoring_adk_a2a_server. Antes de comenzar la tarea, cambia el directorio a esta carpeta.

Crea una tarjeta de agente de A2A

El protocolo A2A requiere una tarjeta de agente que contenga toda la información sobre el agente, como las capacidades, la guía de uso, etcétera. Una vez que se implementa un agente A2A, la tarjeta de agente se puede ver con el vínculo ".well-known/agent-card.json". Los clientes pueden consultar esta información para enviar la solicitud a los agentes.

En la carpeta remote_a2a/image_scoring, confirma que haya un archivo agents.json con el siguiente contenido.

{
 "name": "image_scoring",
 "description": "Agent that generates images based on user prompts and scores their adherence to the prompt.",
 "url": "http://localhost:8001/a2a/image_scoring",
 "version": "1.0.0",
 "defaultInputModes": ["text/plain"],
 "defaultOutputModes": ["image/png", "text/plain"],
 "capabilities": {
   "streaming": true,
   "functions": true
 },
 "skills": [
   {
     "id": "generate_and_score_image",
     "name": "Generate and Score Image",
     "description": "Generates an image from a given text prompt and then evaluates how well the generated image adheres to the original prompt, providing a score.",
     "tags": ["image generation", "image scoring", "evaluation", "AI art"],
     "examples": [
       "Generate an image of a futuristic city at sunset",
       "Create an image of a cat playing a piano",
       "Show me an image of a serene forest with a hidden waterfall"
     ]
   }
 ]
}

Crea un agente de A2A

En la carpeta raíz image_scoring_adk_a2a_server, confirma que haya un archivo a2a_agent.py, que es el punto de entrada para el agente de a2a. Debe tener el siguiente contenido:

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

root_agent = RemoteA2aAgent(
   name="image_scoring",
   description="Agent to give interesting facts.",
   agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json",
  
   # Optional configurations
   timeout=300.0,          # HTTP timeout (seconds)
   httpx_client=None,      # Custom HTTP client
)

Ejecuta el agente de A2A

Ahora sí podemos ejecutar el agente. Para ejecutar el agente, ejecuta el siguiente comando desde la carpeta superior image_scoring_adk_a2a_server

#set some environmental variables
export GOOGLE_CLOUD_PROJECT=datapipeline-372305
export GOOGLE_CLOUD_LOCATION=us-central1
export GCS_BUCKET_NAME=haren-genai-bucket

#following command runs the ADK agent as a2a agent
adk api_server --a2a --port 8001 remote_a2a

Prueba el agente de A2A

Una vez que el agente esté en funcionamiento, podemos probarlo. Primero, revisemos la tarjeta del agente.

#Execute the following 
curl http://localhost:8001/a2a/image_scoring/.well-known/agent.json

Si ejecutas el comando anterior, se debería mostrar la tarjeta del agente para nuestro agente de A2A, que es principalmente el contenido de agent.json que creamos en el paso anterior.

Ahora, enviemos una solicitud al agente. Podemos usar curl para enviar solicitudes al agente.

curl -X POST   http://localhost:8001/a2a/image_scoring   -H 'Content-Type: application/json'   -d '{
    "id": "uuid-123",
    "params": {
      "message": {
        "messageId": "msg-456",
        "parts": [{"text": "Create an image of a cat"}],
        "role": "user"
      }
    }
  }'

En la solicitud anterior, puedes cambiar la instrucción modificando la línea "Create an image of a cat". Una vez que ejecutes el comando, podrás buscar la imagen de salida en el almacenamiento de Google Cloud especificado.

9. Limpia

Ahora, limpiemos lo que acabamos de crear.

Borra el servidor de Agent Engine que acabamos de crear. Para ir a Vertex AI, escribe Vertex AI en la barra de búsqueda de la consola de Google Cloud. Haz clic en Agent Engine, en el lado izquierdo.Para borrar el agente, haz clic en Borrar.

Figura 4

Borra los archivos en Cloud Shell

#Execute the following to delete the files
rm -R imagescoring

Borra el bucket. Puedes ir a GCP Console -> Cloud Storage , seleccionar y borrar tu bucket.