Desplegar agentes de A2A en Cloud Run

Prepara y configura agentes de agente a agente (A2A) para desplegarlos en Cloud Run.

En esta guía se describen los pasos esenciales para implementar agentes de A2A:

Revisa la especificación de A2A y los agentes de ejemplo

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

Antes de empezar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  6. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  11. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  12. Para crear una cuenta de servicio, ejecuta el siguiente comando:
    13. gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

    Sustituye los siguientes valores:

    • A2A_SERVICE_ACCOUNT_NAME: el nombre de la cuenta de servicio

    • DESCRIPTION: descripción opcional de la cuenta de servicio

    • DISPLAY_NAME: un nombre de cuenta de servicio que se mostrará en la consola Google Cloud

    Asigna los roles de cuenta de servicio

    Para conceder los roles de gestión de identidades y accesos necesarios a tu cuenta en tu proyecto, sigue estos pasos:

         gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
         --role="ROLE"

    Sustituye:

    • PROJECT_ID: tu ID de proyecto
    • A2A_SERVICE_ACCOUNT_NAME: el nombre de tu cuenta de servicio
    • ROLE: el rol que vas a añadir a la cuenta de servicio

    Roles obligatorios

    Para obtener los permisos que necesitas para desplegar agentes de A2A, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

    Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

    También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

    Conceder los roles

    Consola

    1. En la consola de Google Cloud , ve a la página Gestión de identidades y accesos.

      Ir a Gestión de identidades y accesos
    2. Selecciona el proyecto.
    3. Haz clic en Conceder acceso.

    4. En el campo Nuevos principales, introduce tu identificador de usuario. Normalmente, es la dirección de correo electrónico que se usa para desplegar el servicio Cloud Run.

    5. En la lista Selecciona un rol, elige un rol.
    6. Para conceder más roles, haz clic en Añadir otro rol y añade cada rol adicional.
    7. Haz clic en Guardar.

    gcloud

    Para conceder los roles de gestión de identidades y accesos necesarios a tu cuenta en tu proyecto, sigue estos pasos:

         gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=ROLE

    Sustituye:

    • PROJECT_NUMBER con el número de tu proyecto. Google Cloud
    • PROJECT_ID por el ID de tu proyecto. Google Cloud
    • PRINCIPAL con la cuenta a la que quieres añadir la vinculación. Normalmente, es la dirección de correo electrónico que se usa para desplegar el servicio Cloud Run.
    • ROLE con el rol que vas a añadir a la cuenta del implementador.

    Prepararse para el despliegue de Cloud Run

    En esta sección se describen las configuraciones necesarias para preparar tu agente de Asistente a Asistente para la implementación en Cloud Run de un ejemplo de código Python.

    Preparar un agente A2A

    1. Para obtener el código de ejemplo, clona el repositorio de la aplicación de ejemplo en tu máquina local:

      git clone https://github.com/a2aproject/a2a-samples

    2. Accede al directorio que contiene el código de muestra:

      cd a2a-samples/samples/python/agents/adk_cloud_run

    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.

    Los agentes necesitan acceder a servicios externos para completar sus tareas. Los secretos son el mecanismo seguro para conceder ese acceso. Cuando implementes con AlloyDB para PostgreSQL, necesitarás el usuario y la contraseña. Crea y gestiona el usuario y la contraseña de la base de datos como secretos en Secret Manager ejecutando los siguientes comandos en la CLI de gcloud:

    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"

    Para obtener más información, consulta el artículo Crear un secreto.

    Dockerfile para la creación en contenedores

    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.

    El Dockerfile determina los detalles de la imagen de contenedor. A continuación, se muestra el Dockerfile del agente A2A de ejemplo que has clonado antes:

    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.

    Desplegar el agente de A2A en Cloud Run

    Implementa tu aplicación A2A con una configuración TaskStore en memoria o con AlloyDB para PostgreSQL.

    • Una configuración de TaskStore en memoria almacena todos sus datos exclusivamente en la instancia de contenedor de Cloud Run. Esto significa que todos los datos de las tareas se pierden cuando la instancia del contenedor se cierra, se reduce o se reinicia.
    • AlloyDB para PostgreSQL proporciona persistencia de datos, lo que permite a los agentes escalar horizontalmente y garantiza que las tareas sobrevivan a los reinicios de contenedores, los eventos de escalado y las implementaciones.

    Una configuración TaskStore en memoria es adecuada para desarrollar agentes A2A en el entorno local, y AlloyDB para PostgreSQL es adecuada para escalar el agente A2A en producción.

    Los siguientes comandos muestran cómo usar la autenticación basada en IAM para tu servicio de Cloud Run. Se recomienda usar la marca --no-allow-unauthenticated en la implementación para configurar la autenticación de clientes internos, Google Cloud como Gemini Enterprise.

    Si tu servidor A2A está diseñado para el acceso público y necesita gestionar la autenticación a nivel de agente, puedes especificar la marca --allow-unauthenticated durante la implementación. Consulta más información sobre la autenticación de acceso público de Cloud Run. Para permitir el acceso público a tu servicio de Cloud Run, también debes proporcionar información de autenticación crucial en la tarjeta de tu agente A2A mediante los parámetros securitySchemes y security. Para obtener más información, consulta Especificación de A2A: detalles del objeto SecurityScheme.

    Implementar con una configuración TaskStore en memoria

    Para implementar tu agente A2A con una configuración TaskStore en memoria, ejecuta el siguiente comando en el directorio que contiene el código fuente de tu agente A2A:

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app"

    Haz los cambios siguientes:

    • REGION: la Google Cloud región en la que quieras desplegar tu servicio (por ejemplo, europe-west1).
    • PROJECT_ID: tu ID de proyecto.
    • PROJECT_NUMBER: tu número de proyecto.
    • A2A_SERVICE_ACCOUNT_NAME: el nombre de tu cuenta de servicio A2A.

    Despliegue con AlloyDB para PostgreSQL

    Para conservar las tareas de A2A, usa AlloyDB para PostgreSQL. Para desplegar tu agente A2A con AlloyDB para PostgreSQL para el almacenamiento de tareas persistente, usa el siguiente comando:

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --update-secrets=DB_USER=alloy_db_user:latest,DB_PASS=alloy_db_pass:latest \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app",USE_ALLOY_DB="True",DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",DB_NAME="postgres"

    Haz los cambios siguientes:

    • REGION: la región en la que quieras implementar tu servicio, por ejemplo, europe-west1. Google Cloud
    • PROJECT_ID: tu ID de proyecto.
    • PROJECT_NUMBER: tu número de proyecto.
    • CLUSTER_NAME: el nombre de tu clúster de AlloyDB para PostgreSQL.
    • A2A_SERVICE_ACCOUNT_NAME: el nombre de tu cuenta de servicio A2A.

    Depurar errores de despliegue

    Si se producen errores o fallos en la implementación de Cloud Run, ten en cuenta lo siguiente:

    • Registros detallados: para obtener registros de implementación detallados, define la marca --verbosity=info en tu comando gcloud run deploy.

    • Las URLs no coinciden: si la run.app URL devuelta por el comando de implementación es diferente de la URL determinista esperada, actualiza la APP_URL variable de entorno de tu servicio de Cloud Run:

      1. Usa el siguiente comando para actualizar la variable de entorno APP_URL:

        gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"

        Haz los cambios siguientes:

        • SERVICE_NAME: el nombre de tu servicio de Cloud Run.
        • PROJECT_ID: tu ID de proyecto.
        • REGION: la Google Cloud región en la que quieras desplegar tu servicio. Por ejemplo, europe-west1.
        • CLOUD_RUN_SERVICE_URL: la URL de tu servicio de Cloud Run.

      2. Verifica que el APP_URL se ha actualizado correctamente describiendo el servicio:

        gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"

    Información sobre la URL de la aplicación de Cloud Run

    Si el despliegue se realiza correctamente, Cloud Run proporciona automáticamente una run.app URL, que sirve como endpoint para consultar tu servicio A2A activo. La URL es determinista y predecible si el nombre del servicio es lo suficientemente corto.

    • Formato de URL de Cloud Run: https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
    • URL de ejemplo: https://sample-a2a-agent-1234.europe-west1.run.app

    Probar y monitorizar el despliegue de agentes A2A

    Una vez que hayas desplegado correctamente tu agente de A2A en Cloud Run, prueba a fondo su funcionalidad. Establece prácticas de monitorización sólidas para asegurar un rendimiento y una fiabilidad continuos.

    Inspector de A2A: validar el cumplimiento de los agentes

    Usa la herramienta a2a-inspector para inspeccionar, depurar y validar el agente de Google A2A que hayas implementado. Esta herramienta se asegura de que tu agente cumpla totalmente la especificación A2A y funcione correctamente.

    Una vez que se haya establecido la conexión, el inspector realizará las siguientes acciones:

    • Muestra la tarjeta de agente: muestra automáticamente la tarjeta de tu agente.
    • Valida el cumplimiento: comprueba que la tarjeta cumpla las especificaciones de A2A.
    • Habilita el chat en directo: te permite enviar y recibir mensajes del agente.
    • Mostrar datos sin procesar: muestra mensajes JSON-RPC 2.0 sin procesar en una consola para depurar.

    Interacción con la CLI de un agente A2A implementado

    Usa las herramientas de la interfaz de línea de comandos (CLI) del repositorio de ejemplos de A2A para interactuar con el servicio implementado. Esta CLI admite la autenticación basada en tokens de portador.

    Si tu servicio usa la autenticación basada en IAM, exporta el token gcloud para que la interacción se realice correctamente:

    export A2A_CLI_BEARER_TOKEN=$(gcloud auth print-identity-token)
# From CLI directory
uv run . --agent CLOUD_RUN_SERVICE_URL

    Sustituye CLOUD_RUN_SERVICE_URL por la URL de tu servicio de Cloud Run desplegado.

    Pruebas locales de servicios A2A implementados

    Puedes probar tu servicio de Cloud Run desplegado de forma local. Esto es especialmente útil cuando se implementa la autenticación basada en gestión de identidades y accesos.

    Probar la autenticación basada en IAM para agentes de Cloud Run

    Los clientes que interactúen con tu servicio de Cloud Run protegido con Gestión de Identidades y Accesos (IAM) deben tener el rol de roles/run.invoker de IAM.

    Prueba localmente el flujo de autenticación del servicio implementado con el comando gcloud auth print-identity-token:

    curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" CLOUD_RUN_SERVICE_URL/.well-known/agent.json

    Sustituye CLOUD_RUN_SERVICE_URL por la URL de tu servicio de Cloud Run desplegado.