Implementa agentes de A2A en Cloud Run

Prepara y configura los agentes de Agent2Agent (A2A) para la implementación 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 muestra

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

Antes de comenzar

  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 usas un proveedor de identidad externo (IdP), primero debes Acceder a la gcloud CLI 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 usas un proveedor de identidad externo (IdP), primero debes Acceder a la gcloud CLI 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"

    Reemplaza los siguientes valores:

    • A2A_SERVICE_ACCOUNT_NAME: el nombre de la cuenta de servicio

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

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

    Otorga los roles de la cuenta de servicio

    Para otorgar los roles de IAM 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"

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto.
    • A2A_SERVICE_ACCOUNT_NAME: El nombre de tu cuenta de servicio
    • ROLE: Es el rol que agregarás a la cuenta de servicio.

    Roles obligatorios

    Para obtener los permisos que necesitas para implementar agentes de A2A, pídele a tu administrador que te otorgue los siguientes roles de IAM:

    Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

    Otorga los roles

    Console

    1. En la consola de Google Cloud , dirígete a la página IAM.

      Ir a IAM
    2. Selecciona el proyecto.
    3. Haz clic en Otorgar acceso.

    4. En el campo Principales nuevas, ingresa tu identificador de usuario. Por lo general, es la dirección de correo electrónico que se usa para implementar el servicio de Cloud Run.

    5. En la lista Seleccionar un rol, elige uno.
    6. Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega cada rol adicional.
    7. Haz clic en Guardar.

    gcloud

    Para otorgar los roles de IAM necesarios a tu cuenta en tu proyecto, sigue estos pasos:

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

    Reemplaza lo siguiente:

    • PROJECT_NUMBER por el número de tu proyecto Google Cloud .
    • PROJECT_ID por el ID de tu proyecto Google Cloud .
    • PRINCIPAL por la cuenta a la que agregarás la vinculación. Por lo general, es la dirección de correo electrónico que se usa para implementar el servicio de Cloud Run.
    • ROLE con el rol que agregas a la cuenta del implementador.

    Prepárate para la implementación de 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 de una muestra de código de Python.

    Prepara el agente A2A

    1. Clona el repositorio de la app de ejemplo en tu máquina local para recuperar la muestra de código:

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

    2. Dirígete al directorio que contiene el código de muestra:

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

    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 secretos en Cloud Run.

    Los agentes necesitan acceder a servicios externos para completar sus tareas. Los secretos son el mecanismo seguro para otorgar ese acceso. Cuando implementas con AlloyDB para PostgreSQL, necesitas el usuario y la contraseña. Ejecuta los siguientes comandos en gcloud CLI para crear y administrar los secretos de contraseña y usuario de la base de datos en Secret Manager:

    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 Crea un secreto.

    Dockerfile para la contenedorizació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.

    El Dockerfile determina los detalles de la imagen del contenedor. A continuación, se muestra el Dockerfile del agente de A2A de muestra que clonaste anteriormente:

    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

    Para 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.

    Implementa el agente de A2A en Cloud Run

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

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

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

    En los siguientes comandos, se muestra cómo usar la autenticación basada en IAM para tu servicio de Cloud Run. Usar la marca --no-allow-unauthenticated durante la implementación es el enfoque recomendado para configurar la autenticación para clientes Google Cloud internos, como Gemini Enterprise.

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

    Implementa con una configuración de TaskStore en memoria

    Para implementar tu agente de A2A con una configuración de TaskStore en la memoria, ejecuta el siguiente comando en el directorio que contiene el código fuente de tu agente de 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"

    Reemplaza lo siguiente:

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

    Implementa con AlloyDB para PostgreSQL

    Para conservar las tareas de A2A, usa AlloyDB para PostgreSQL. Para implementar tu agente de A2A con AlloyDB para PostgreSQL para el almacenamiento de tareas persistentes, 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"

    Reemplaza lo siguiente:

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

    Depura fallas de implementación

    Si encuentras errores o fallas en la implementación de Cloud Run, ten en cuenta lo siguiente:

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

    • No coincide la URL: Si la URL run.app que devuelve el comando de implementación difiere de la URL determinística esperada, actualiza la variable de entorno APP_URL para 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"

        Reemplaza lo siguiente:

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

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

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

    Comprende la URL de la aplicación de Cloud Run

    Si la implementación se realiza de forma correcta, Cloud Run proporciona automáticamente una run.app URL, que funciona como el extremo para consultar tu servicio de A2A activo. La URL es determinística 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

    Prueba y supervisa la implementación del agente de A2A

    Después de implementar correctamente tu agente de A2A en Cloud Run, prueba a fondo su funcionalidad. Establece prácticas de supervisión sólidas para garantizar el rendimiento y la confiabilidad continuos.

    Inspector de A2A: Valida el cumplimiento del agente

    Usa la herramienta a2a-inspector para inspeccionar, depurar y validar tu agente de Google A2A implementado. Esta herramienta garantiza que tu agente cumpla con la especificación de A2A y funcione correctamente.

    Después de una conexión exitosa, el inspector realiza las siguientes acciones:

    • Muestra la tarjeta del agente: Muestra automáticamente la tarjeta de tu agente.
    • Valida el cumplimiento: Comprueba que la tarjeta cumpla con las especificaciones de A2A.
    • Habilita el chat en vivo: Te permite enviar y recibir mensajes con el agente.
    • Muestra datos sin procesar: Muestra mensajes JSON-RPC 2.0 sin procesar en una consola para la depuración.

    Interacción de la CLI con un agente de A2A implementado

    Usa las herramientas de la interfaz de línea de comandos (CLI) del repositorio de muestras de A2A para interactuar con tu 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 sea exitosa:

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

    Reemplaza CLOUD_RUN_SERVICE_URL por la URL de tu servicio de Cloud Run implementado.

    Pruebas locales de los servicios de A2A implementados

    Puedes probar tu servicio de Cloud Run implementado de forma local. Esto es particularmente útil cuando se implementa la autenticación basada en IAM.

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

    Los clientes que interactúan con tu servicio de Cloud Run protegido por Identity and Access Management (IAM) deben tener el rol de IAM de roles/run.invoker.

    Prueba localmente el flujo de autenticación de tu 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

    Reemplaza CLOUD_RUN_SERVICE_URL por la URL de tu servicio de Cloud Run implementado.