Información general sobre el alojamiento de agentes de A2A en Cloud Run

En esta guía se ofrece una descripción general de cómo preparar y configurar agentes de Agent2Agent (A2A) para implementarlos en Cloud Run. En él se explican los pasos esenciales, como configurar un entorno de nube, configurar los roles de Gestión de Identidades y Accesos (IAM) necesarios y preparar el agente para la implementación.

Antes de empezar

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

Hoja de ruta de la implementación de agentes A2A

Para implementar tu agente, sigue estos pasos:

Arquitectura avanzada

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

En el siguiente diagrama se muestra la arquitectura de un sistema de agente A2A, donde se ve un cliente A2A (usuario o agente) interactuando con el agente A2A.

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

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

Roles y permisos de gestión de identidades y accesos para agentes de A2A de Cloud Run

Es importante que los roles de gestión de identidades y accesos estén configurados correctamente para que tu servicio de Cloud Run pueda interactuar de forma segura con otros servicios de Google Cloud. Crea una cuenta de servicio específica y concede los permisos que se indican en las siguientes secciones para garantizar la seguridad y la eficiencia operativas.

Crear una cuenta de servicio de Cloud Run

Antes de ejecutar cualquier comando de gcloud, asegúrate de que te has autenticado. Ejecuta el siguiente comando para iniciar sesión en tu cuenta de Google Cloud :

gcloud auth login

Crea una cuenta de servicio específicamente para la instancia de servicio A2A implementada. 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"

Sustituye A2A_SERVICE_ACCOUNT_NAME por el nombre de la cuenta de servicio.

Configurar roles de gestión de identidades y accesos para el agente A2A

Asigna los siguientes roles de gestión de identidades y accesos a tu cuenta de servicio en función de los Google Cloud servicios con los que interactúe tu agente de A2A:

Acceso a Secret Manager para credenciales seguras

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

  • Finalidad: permite que la cuenta de servicio de Cloud Run obtenga de forma segura secretos, como credenciales de bases de datos, de 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 de IA

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

  • Finalidad: es necesario para que la cuenta de servicio de Cloud Run invoque APIs de predicción en 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 procede)

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

  • Finalidad: permite que la identidad de servicio de Cloud Run interactúe con el clúster de AlloyDB para almacenar tareas de forma persistente, lo cual es fundamental para los agentes 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"

Preparar el agente de A2A para el despliegue en Cloud Run

En esta sección se describen las configuraciones necesarias para preparar tu agente A2A para la implementación en Cloud Run, lo que garantiza un funcionamiento seguro, eficiente y escalable en la nube.

Configurar secretos para servicios de Cloud Run

Proporciona todas las credenciales sensibles, como las claves de API y las contraseñas de bases de datos, a tu servidor A2A mediante un mecanismo seguro. Cloud Run admite el uso de secretos como variables de entorno o volúmenes montados dinámicamente. Para obtener más información, consulta Configurar secretos en Cloud Run.

Por ejemplo, puedes crear y gestionar secretos de usuarios y contraseñas de bases de datos en Google Secret Manager con la CLI de gcloud. Para obtener más información, consulta el artículo Crear 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"

Crear un Dockerfile para la contenedorización

Cloud Run puede desplegar servicios a partir de imágenes de contenedor ya alojadas o directamente desde tu código fuente. Cuando se despliega desde el código fuente, Cloud Run crea automáticamente una imagen de contenedor si hay un Dockerfile en el directorio raíz del proyecto.

A continuación, se muestra un ejemplo de Dockerfile para la implementación de un 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"]

Desplegar desde el código fuente sin un Dockerfile

En el caso de los repositorios de código fuente que no tienen un Dockerfile, Cloud Run ofrece compatibilidad integrada con algunos lenguajes de programación populares, lo que simplifica el proceso de creación de contenedores.

Siguientes pasos