Desplegar agentes de A2A en Cloud Run

En este documento se describe cómo desplegar tu agente de A2A en Cloud Run. Estos pasos aseguran un funcionamiento seguro, eficiente y escalable en el entorno de la nube.

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.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

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

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init
  12. Ve al directorio que contiene el código fuente de tu agente A2A:

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. Para consultar los roles y permisos de gestión de identidades y accesos necesarios, consulta el artículo Roles y permisos de gestión de identidades y accesos para agentes de A2A de Cloud Run.

Configurar la autenticación del servicio de Cloud Run

Una vez que tu agente A2A esté completamente desarrollado y su entorno de implementación esté preparado, debes configurar la autenticación y usar el comando gcloud run deploy para implementar el agente en Cloud Run.

Usa una de las siguientes opciones para configurar el acceso y la autenticación de tu servicio A2A de Cloud Run:

  • Autenticación basada en IAM para clientes internos: Google Cloud En el caso de los clientes que operan en Google Cloud, como los servicios internos de Agentspace, la autenticación basada en IAM es el método seguro recomendado. Estos clientes usan cuentas de servicio y requieren el rol Invocador de Cloud Run (roles/run.invoker) para invocar tu servicio de Cloud Run. Para obtener más información, consulta el artículo sobre la autenticación de servicio a servicio de Cloud Run.

    Para habilitar la autenticación basada en gestión de identidades y accesos en tu servicio de Cloud Run, sigue estos pasos:

    • Debes usar la marca --no-allow-unauthenticated durante la implementación.

  • Autenticación a nivel de agente para la exposición pública: si tu servidor A2A está diseñado para el acceso público, gestiona la autenticación a nivel de agente.

    Para permitir el acceso público a tu servicio de Cloud Run, haz lo siguiente:

Desplegar el agente de A2A en Cloud Run

Usa el ejemplo de ADK para implementar tu agente de A2A. Especifica los siguientes parámetros cuando uses el comando gcloud run deploy:

  • Configuración de acceso:
    • Para usar la autenticación de servicios basada en IAM, usa la marca --no-allow-unauthenticated.
    • Para que los servicios sean públicos en Internet, usa la marca --allow-unauthenticated.
  • Memoria: el requisito mínimo de memoria para que se ejecute la instancia de contenedor es 1Gi.
  • Secretos: para usar secretos, especifica los parámetros DB_USER y DB_PASS.
  • Cuenta de servicio: para especificar una cuenta de servicio, usa el parámetro a2a-service-account.
  • Variables de entorno: para especificar variables de entorno, usa las siguientes variables:
    • APP_URL
    • DB_INSTANCE
    • DB_NAME
    • GOOGLE_GENAI_USE_VERTEXAI = true

Para hacer pruebas locales, usa una configuración TaskStore en memoria. Para desplegar tu servicio en producción, debes usar almacenamiento persistente para un servidor A2A de producción. Consulta un ejemplo en la sección Implementación de AlloyDB para PostgreSQL.

Implementar con una configuración TaskStore en memoria

Para desplegar tu agente A2A con una configuración TaskStore en memoria, usa el siguiente comando gcloud run deploy:

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=a2a-service-account \
    --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"

Si no estás en el directorio que contiene el código fuente de tu agente A2A, actualiza la marca --source con la ruta completa al código de tu agente.

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.

Implementar con AlloyDB para PostgreSQL

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

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 \
    --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"

Si no estás en el directorio que contiene el código fuente de tu agente A2A, actualiza la marca --source con la ruta completa al código de tu agente.

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.
  • CLUSTER_NAME: el nombre de tu clúster de AlloyDB para PostgreSQL.

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 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
  • URL de ejemplo: https://sample-a2a-agent-1234.europe-west1.run.app

Depurar errores de despliegue

Para depurar los errores de despliegue 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 variable de entorno APP_URL 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"