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 A2A:

• Cómo configurar tu proyecto
• Establece roles de IAM
• Configura tu entorno de nube
• Implementa tu agente
• Depura las fallas de implementación
• Prueba y supervisa

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:

• Revisa la especificación oficial de A2A y los conceptos de comunicación entre agentes para la comunicación entre agentes.
• Explora los agentes de muestra existentes.
• Revisa la muestra de Cloud Run del ADK.

Antes de comenzar

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

2. Verify that billing is enabled for your Cloud de Confiance project.

3. Install the Google Cloud CLI.

4. Configure the gcloud CLI to use your federated identity.

   For more information, see Sign in to the gcloud CLI with your federated identity.

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

   gcloud init

6. De forma predeterminada, te recomendamos que asignes una identidad del agente segura y administrada por el sistema a tu agente pasando las marcas --functional-type=agent y --identity-type=agent-identity durante la implementación. Para obtener instrucciones, consulta Configura las funciones de la plataforma del agente. Si debes implementar tu agente con una cuenta de servicio estándar, puedes crear una cuenta de servicio administrada por el usuario y pasar la marca --service-account durante la implementación.

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

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:

• Desarrollador de origen de Cloud Run (roles/run.sourceDeveloper) en el proyecto
• Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin) en el proyecto
• Administrador de Secret Manager (roles/secretmanager.admin) en el proyecto
• Usuario de la cuenta de servicio (roles/iam.serviceAccountUser) en la identidad del servicio
• Descriptor de acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor) en la cuenta de servicio
• Usuario de Vertex AI (roles/aiplatform.user) en la cuenta de servicio
• Si realizas la implementación con AlloyDB para PostgreSQL, otorga los siguientes roles:
  • Cliente de AlloyDB para PostgreSQL (roles/alloydb.client) en la cuenta de servicio
  • Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin) en la cuenta de servicio

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.

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

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 para 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 bases de datos, a tu servidor de A2A a través de un mecanismo seguro. Cloud Run admite proporcionar 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 implementes con AlloyDB para PostgreSQL, necesitarás el usuario y la contraseña. Ejecuta los siguientes comandos en la gcloud CLI para crear y administrar los secretos de la contraseña y el 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 creación de contenedores

Cloud Run puede implementar servicios desde imágenes de contenedores ya alojadas o directamente desde tu código fuente. Cuando se implementa 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 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.

• Aplicaciones de Python en Cloud Run: Cloud Run busca un archivo main.py para compilar e implementar servicios de Python. Para obtener más información, consulta la guía de inicio rápido para implementar un servicio de Python en Cloud Run.
• Aplicaciones de Node.js en Cloud Run: Cloud Run busca un archivo index.js para compilar e implementar servicios de Node.js. Consulta la guía de inicio rápido para implementar un servicio de Node.js en Cloud Run.

Implementa el agente A2A en Cloud Run

Para asignar una identidad administrada por el sistema a tu agente A2A y registrarla en Agent Platform, consulta Configura las funciones de Agent Platform para 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 la tarea se pierden cuando la instancia del contenedor se apaga, reduce la escala verticalmente o se reinicia.
• AlloyDB para PostgreSQL proporciona persistencia de datos, lo que permite que los agentes escalen horizontalmente y garantiza que las tareas sobrevivan a los reinicios de contenedores, los eventos de escalamiento y las implementaciones.

Una configuración TaskStore en la memoria es adecuada para desarrollar agentes A2A en el entorno local, y AlloyDB para PostgreSQL es adecuado para escalar el agente 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 en la implementación es el enfoque recomendado para configurar la autenticación de los clientes internos de Cloud de Confiance by S3NS , 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 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 fundamental en la tarjeta de tu agente 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 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 \
    --functional-type=agent \
    --identity-type=agent-identity \
    --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.s3nsrun.fr"

Reemplaza lo siguiente:

• REGION: Es la región de Cloud de Confiance by S3NS en la que deseas implementar tu servicio, por ejemplo, europe-west1.
• PROJECT_ID: Es el ID del 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 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 \
    --functional-type=agent \
    --identity-type=agent-identity \
    --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.s3nsrun.fr",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 región de Cloud de Confiance by S3NS en la que deseas implementar tu servicio, por ejemplo, europe-west1.
• PROJECT_ID: Es el ID del proyecto.
• PROJECT_NUMBER: Es el número de tu proyecto.
• CLUSTER_NAME: Es el nombre de tu clúster de AlloyDB para PostgreSQL.

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 de s3nsrun.fr 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: Es el ID del proyecto.
     • REGION: Es la región de Cloud de Confiance by S3NS 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 actualice 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 correctamente, Cloud Run proporciona automáticamente una URL de s3nsrun.fr, que sirve 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.s3nsrun.fr
• Ejemplo de URL: https://sample-a2a-agent-1234.europe-west1.s3nsrun.fr

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