Implementa agentes de A2A en Cloud Run

Prepara y configura agentes de Agent2Agent (A2A) para la implementación en Cloud Run.

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

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

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

Antes de comenzar

  1. Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  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. Instala 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. Instala 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: un nombre de cuenta de servicio que se mostrará en la Google Cloud consola de

Otorga los roles de la cuenta de servicio

Para otorgar los roles de IAM necesarios a tu cuenta en tu proyecto, haz lo siguiente:

     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: Es el nombre de la cuenta de servicio.
  • ROLE: Es el rol que agregas 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 Google Cloud consola de, dirígete a la página IAM.

    Ir a IAM
  2. Selecciona el proyecto.
  3. Haz clic en Grant access.

  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 uno más.
  7. Haz clic en Guardar.

gcloud

Para otorgar los roles de IAM necesarios a tu cuenta en tu proyecto, haz lo siguiente:

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

Reemplaza lo siguiente:

  • PROJECT_NUMBER por el número de tu Google Cloud proyecto
  • PROJECT_ID por el ID del Google Cloud proyecto
  • 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 por el rol que agregas a la cuenta del implementador.

Prepárate para la implementación de Cloud Run

En esta sección, se describen las configuraciones necesarias para preparar tu agente de A2A para la implementación en Cloud Run para una muestra de código de Python.

Prepara el agente de A2A

  1. Para recuperar la muestra de código, clona el repositorio de la app de muestra en tu máquina local:

    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 acceso a servicios externos para completar sus tareas. Los secretos son el mecanismo seguro para otorgar ese acceso. Cuando realizas la implementación con AlloyDB para PostgreSQL, necesitas el usuario y la contraseña. Para crear y administrar los secretos de usuario y contraseña de la base de datos en Secret Manager, ejecuta los siguientes comandos en gcloud CLI:

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 contenedor que ya están alojadas o directamente desde tu código fuente. Cuando realizas la implementación 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 de contenedor. A continuación, se muestra el Dockerfile del agente de A2A de muestra que clonaste 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"]

Realiza la implementación 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 de TaskStore en la memoria o con AlloyDB para PostgreSQL.

  • Una configuración de TaskStore en la memoria almacena todos sus datos exclusivamente dentro de la instancia de contenedor de Cloud Run. Esto significa que todos los datos de la tarea se pierden cuando la instancia de contenedor se cierra, 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 adecuada 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 --no-allow-unauthenticated marca durante la implementación es el enfoque recomendado para configurar la autenticación para clientes internos, como Gemini Enterprise. Google Cloud

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 de 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 crucial 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.

Realiza la implementación con una configuración de TaskStore en la 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: el número de tu proyecto
  • A2A_SERVICE_ACCOUNT_NAME: el nombre de tu cuenta de servicio de A2A

Realiza la implementación 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 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"

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: el número de tu proyecto
  • CLUSTER_NAME: el nombre de tu clúster de AlloyDB para PostgreSQL
  • A2A_SERVICE_ACCOUNT_NAME: el nombre de tu cuenta de servicio de A2A

Depura las fallas de implementación

Si encuentras errores o fallas de implementación de Cloud Run, considera lo siguiente:

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

  • Incoincidencia de URL: Si la run.app URL que muestra el comando de implementación difiere de la URL determinista esperada, actualiza la APP_URL variable de entorno 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: la Google Cloud región en la que deseas implementar tu servicio. Por ejemplo, europe-west1.
      • CLOUD_RUN_SERVICE_URL: la URL de tu servicio de Cloud Run

    2. Para verificar que APP_URL se actualizó correctamente, describe 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 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
  • Ejemplo de URL: 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 su funcionalidad por completo. 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 A2A de Google implementado. Esta herramienta garantiza que tu agente cumpla por completo 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: Verifica 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 una interacción 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 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 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 roles/run.invoker.

Prueba de forma local 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

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