Descripción general del alojamiento de agentes de A2A en Cloud Run

En esta guía, se proporciona una descripción general de cómo preparar y configurar los agentes de Agent2Agent (A2A) para la implementación en Cloud Run. Abarca pasos esenciales, como configurar un entorno de nube, configurar los roles de Identity and Access Management (IAM) necesarios y preparar tu agente para la implementación.

Antes de comenzar

Antes de comenzar a desarrollar y a implementar tu agente de A2A, familiarízate con los siguientes conceptos y recursos:

Hoja de ruta de la implementación del agente A2A

Para implementar tu agente, completa los siguientes pasos:

Arquitectura de alto nivel

El núcleo del agente de A2A es una capa de servicio y organización, como Cloud Run. Esta capa administra las interacciones con modelos de IA, como Gemini y Vertex AI, los almacenamientos de memoria, como AlloyDB y A2A TaskStore, y las herramientas externas a través de las APIs. Los clientes interactúan con el agente enviando solicitudes, como "Obtener tarjeta del agente" o "Enviar mensaje", y reciben actualizaciones de las tareas.

En el siguiente diagrama, se ilustra la arquitectura de un sistema de agente de A2A, en el que se muestra un cliente de A2A (usuario o agente) que interactúa con el agente de A2A.

Arquitectura del agente de A2A que muestra la interacción del cliente con el agente a través de una capa de entrega y orquestación.
Arquitectura del agente de A2A

Para obtener información sobre el ciclo de vida de las solicitudes de A2A, consulta la sección Ciclo de vida de las solicitudes de A2A.

Roles y permisos de IAM para los agentes de A2A de Cloud Run

Las funciones de IAM configuradas correctamente son importantes para que tu servicio de Cloud Run interactúe de forma segura con otros servicios de Google Cloud. Crea una cuenta de servicio dedicada y otorga los permisos específicos que se indican en las siguientes secciones para garantizar la seguridad y la eficiencia operativas.

Crea una cuenta de servicio de Cloud Run

Antes de ejecutar cualquier comando de gcloud, asegúrate de estar autenticado. Ejecuta el siguiente comando para acceder a tu cuenta de Google Cloud :

gcloud auth login

Crea una cuenta de servicio específicamente para la instancia del servicio de A2A implementado. Usa el comando gcloud iam service-accounts create.

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="Service account for A2A Cloud Run service" \
  --display-name="A2A Cloud Run Service Account"

Reemplaza A2A_SERVICE_ACCOUNT_NAME por el nombre de la cuenta de servicio.

Configura roles de IAM para el agente de A2A

Asigna los siguientes roles de IAM a tu cuenta de servicio según los servicios con los que interactúa tu agente de A2A: Google Cloud

Acceso a Secret Manager para credenciales seguras

  • Rol: Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

  • Propósito: Permite que la cuenta de servicio de Cloud Run recupere de forma segura secretos, como credenciales de bases de datos, desde Secret Manager.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

Acceso a modelos de Vertex AI para funciones basadas en IA

  • Rol: Vertex AI User (roles/aiplatform.user)

  • Propósito: Se requiere para que la cuenta de servicio de Cloud Run invoque las APIs de predicción en los modelos de Vertex AI.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Acceso a la instancia de AlloyDB para el almacenamiento persistente (si corresponde)

  • Roles: AlloyDB Client (roles/alloydb.client) y Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

  • Propósito: Permite que la identidad del servicio de Cloud Run interactúe con el clúster de AlloyDB para el almacenamiento persistente de tareas, lo que es fundamental para los agentes de A2A de producción.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

Prepara el agente de A2A para la implementación en Cloud Run

En esta sección, se describen los parámetros de configuración necesarios para preparar tu agente de A2A para la implementación en Cloud Run, lo que garantiza un funcionamiento seguro, eficiente y escalable en la nube.

Configura secretos para los servicios de Cloud Run

Proporciona todas las credenciales sensibles, como las claves de API y las contraseñas de la base de datos, a tu servidor de A2A con un mecanismo seguro. Cloud Run admite el suministro de secretos como variables de entorno o volúmenes activados de forma dinámica. Para obtener más información, consulta Configura Secrets en Cloud Run.

Por ejemplo, crea y administra secretos de contraseñas y usuarios de bases de datos en Google Secret Manager con la CLI de gcloud. Para obtener más información, consulta Crea un secreto.

gcloud secrets create alloy_db_user --replication-policy="automatic"
# Create a file user.txt with contents of secret value
gcloud secrets versions add alloy_db_user --data-file="user.txt"

gcloud secrets create alloy_db_pass --replication-policy="automatic"
# Create a file pass.txt with contents of secret value
gcloud secrets versions add alloy_db_pass --data-file="pass.txt"

Crea un Dockerfile para la contenerización

Cloud Run puede implementar servicios desde imágenes de contenedores ya alojadas o directamente desde tu código fuente. Cuando implementas desde el código fuente, Cloud Run compila automáticamente una imagen de contenedor si hay un Dockerfile en el directorio raíz de tu proyecto.

A continuación, se muestra un ejemplo de Dockerfile para la implementación del agente de A2A:

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
EXPOSE 8080
WORKDIR /app
COPY . ./
RUN uv sync
ENTRYPOINT ["uv", "run", ".", "--host", "0.0.0.0", "--port", "8080"]

Implementa desde el código fuente sin un Dockerfile

En el caso de los repositorios de código fuente sin un Dockerfile, Cloud Run ofrece compatibilidad integrada con ciertos lenguajes de programación populares, lo que simplifica el proceso de contenedorización.

¿Qué sigue?