Implementa agentes de A2A en Cloud Run

En este documento, se describe cómo implementar tu agente de A2A en Cloud Run. Estos pasos garantizan una operación segura, eficiente y escalable en el entorno de nube.

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.

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

    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 gcloud CLI con tu identidad federada.

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

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

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. Para conocer los roles y permisos de IAM necesarios, consulta Roles y permisos de IAM para los agentes de A2A de Cloud Run.

    14. Configura la autenticación del servicio de Cloud Run

    Después de que tu agente de 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 de Cloud Run de A2A:

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

      Para habilitar la autenticación basada en IAM para tu servicio de Cloud Run, haz lo siguiente:

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

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

      Sigue estos pasos para permitir el acceso público a tu servicio de Cloud Run:

    Implementa el agente de A2A en Cloud Run

    Usa el ejemplo existente del 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 servicio 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 del contenedor es de 1Gi.
    • Objetos secretos: Para usar objetos 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 las pruebas locales, usa una configuración de TaskStore en memoria. Para implementar tu servicio en producción, debes usar almacenamiento persistente para un servidor de A2A de producción. Consulta un ejemplo en la sección Implementación de AlloyDB para PostgreSQL.

    Implementa con una configuración de TaskStore en memoria

    Para implementar tu agente de A2A con una configuración de TaskStore en la memoria, usa el siguiente comando de 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 de A2A, actualiza la marca --source con la ruta de acceso completa a tu código del agente.

    Reemplaza lo siguiente:

    • REGION: Es la región Google Cloud 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.

    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 persistente de tareas, usa el siguiente comando de 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 de A2A, actualiza la marca --source con la ruta de acceso completa a tu código del agente.

    Reemplaza lo siguiente:

    • REGION: Es la región Google Cloud 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.

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

    Si la implementación se realiza de forma correcta, Cloud Run proporciona automáticamente una URL run.app 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

    Depura fallas de implementación

    Para depurar las fallas en la 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.

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