1. Introducción
Descripción general
En este lab, se muestra cómo implementar de forma segura una invocación controlada por eventos de un agente de ADK implementado en Cloud Run con los servicios de Eventarc y Pub/Sub. Por lo general, un usuario o un agente llama a otro agente directamente. Sin embargo, cuando se integra un agente en flujos de trabajo existentes basados en eventos, realizar una llamada directa requiere cambios en el software existente. Activar una invocación del agente en función de un evento permite incorporar un agente en los flujos de trabajo existentes sin realizar cambios en ellos.
Actividades
En este lab, crearás una aplicación agentic de ZooKeeper que tiene un agente de IA y usa algunas herramientas para proporcionar información sobre los animales en el zoológico imaginario.
Implementarás la aplicación de ZooKeeper como un servicio en Cloud Run, que es una plataforma de procesamiento sin servidores completamente administrada que ejecuta contenedores sin estado en la infraestructura de Google. Luego, configurarás un activador de Eventarc que invocará el extremo del servicio para controlar de forma asíncrona los mensajes publicados en un tema de Pub/Sub. Te asegurarás de que la implementación siga las prácticas recomendadas, como usar cuentas de servicio de IAM designadas, otorgar el acceso con privilegios mínimos y minimizar una posible superficie de ataque exponiendo el extremo de la aplicación de ZooKeeper solo a Eventarc. Lo harás con la ayuda de Cloud Shell y la consola de Cloud. Usarás las bibliotecas del ADK y del SDK de Cloud para Python. Para verificar el comportamiento, usarás la CLI de gcloud.
Qué aprenderás
- Implementa tu agente del ADK en Google Cloud Run.
- Integra el activador de Eventarc con el agente de ADK que se ejecuta en Google Cloud Run.
- Protege tu implementación e integración con Eventarc usando el principio de privilegio mínimo con la ayuda de Google Cloud IAM.
- Publicar y extraer mensajes hacia y desde Pub/Sub
- Minimiza la exposición pública de tu aplicación implementada en Google Cloud Run.
Requisitos
- Navegador web Chrome †
- Una Cuenta de Google personal ‡
- Un proyecto de Google Cloud vinculado a una cuenta de facturación activa
Ten en cuenta que tu cuenta debe tener acceso de IAM al proyecto que te permita aprovisionar recursos y configurar el acceso de IAM a estos recursos.
† La experiencia del usuario con otros navegadores puede diferir de la que se describe en el lab.
‡ Es posible que el uso de una cuenta corporativa o de institución educativa esté limitado para realizar algunas de las operaciones que se describen en el lab.
2. Configuración del entorno
Para garantizar un entorno de desarrollo completamente funcional para el lab, usarás Google Cloud Shell, que tiene todas las herramientas necesarias preinstaladas. Sigue las instrucciones para configurar el entorno.
Si no tienes una, créala.
Instrucciones de configuración
- Usa tu Cuenta de Google para acceder a la consola de Google Cloud.
- 👉 Abre el selector de proyectos en la barra de navegación superior (es posible que diga "Selecciona un proyecto" o que muestre el nombre de un proyecto existente) o haz clic en el atajo de teclado
Ctrl+Oy elige un proyecto existente o crea uno nuevo.La creación de un proyecto nuevo tardará unos segundos. Espera hasta que esté listo y selecciónalo con el selector de proyectos.
- 👉 Haz clic en el ícono de Cloud Shell en la parte superior de la consola de Google Cloud. (marcado con el rectángulo rojo):
Si se te solicita, haz clic en **Autorizar** en el cuadro de diálogo emergente para aprobar que Cloud Shell use las credenciales de tu cuenta.
- 👉💻 Asegúrate de que la CLI de gcloud esté configurada para usar el proyecto que seleccionaste (o creaste). Ejecuta el siguiente comando para verificar el ID del proyecto configurado:
gcloud config get-value projectYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID]será el ID del proyecto que seleccionaste o creaste.👉💻 Si ves otro valor, ejecuta el siguiente comando para configurar el ID de tu proyecto como el ID del proyecto predeterminado para los comandos de la CLI de gcloud:gcloud config set project [YOUR_PROJECT_ID]gcloud config set project lab-project-id-example-123
gcloud projects list \ --format='value(projectId)' \ --sort-by='~createTime'
- 👉💻 Configura la ubicación para el aprovisionamiento de recursos y el ID y el número de tu proyecto en las variables de entorno:
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 Habilita las APIs de Google necesarias para este lab.
gcloud services enable \ aiplatform.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ pubsub.googleapis.comOperation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.
3. Implementa la aplicación de demostración de ZooKeeper
En los siguientes pasos, se aprovisionan y configuran recursos, incluida la implementación de la aplicación de IA basada en agentes.
Configura recursos de Pub/Sub
Crearás dos temas de Pub/Sub. Un servicio externo lo usará para enviar eventos a tu aplicación de IA agentiva. Otro para que la aplicación publique los resultados del procesamiento de eventos.
- 👉💻 Crea un tema de Pub/Sub que se use para activar la aplicación de IA basada en agentes:
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 Crea un tema de Pub/Sub en el que la aplicación pueda publicar sus respuestas:
gcloud pubsub topics create agent_responses export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)") gcloud pubsub subscriptions create agent_responses \ --topic=agent_responses
Configura cuentas de servicio y políticas de IAM a nivel del proyecto
Crearás dos cuentas de servicio para limitar el alcance del acceso del servicio de Cloud Run y el activador de Eventarc al mínimo según el principio de privilegio mínimo. El servicio de Cloud Run requiere permisos para escribir registros y seguimientos, llamar al LLM de Gemini en Google Vertex AI y publicar resultados en un tema de Pub/Sub. El acceso mínimo del activador de Eventarc requiere permisos para llamar al servicio de ZooKeeper de Cloud Run y acceder a Pub/Sub para leer los eventos publicados. En estas instrucciones, se explica cómo otorgar a la cuenta de servicio del activador los permisos necesarios para suplantar la identidad del servicio del sistema de Pub/Sub. Después de crear el recurso del activador de Eventarc, ejecutarás el comando que otorga el rol roles/run.invoker para permitir que la cuenta de servicio del activador llame al servicio de Cloud Run.
- 👉💻 Crea una cuenta de servicio para el servicio de Cloud Run:
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Otorga a la cuenta de servicio permisos para escribir registros y seguimientos, y usar modelos de Gemini en Vertex AI:
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/logging.logWriter" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/cloudtrace.agent" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/aiplatform.user" \ --condition=None - 👉💻 Otorga a la cuenta de servicio permisos para publicar mensajes en el tema “agent_responses”:
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 Crea una cuenta de servicio para el activador de Eventarc:
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Otorga permisos a la cuenta de servicio del sistema de Pub/Sub para realizar solicitudes push autenticadas:
gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
Implementa la app de ZooKeeper en Cloud Run
Descargarás el código de la aplicación de demostración desde GitHub. Luego, implementa el código en Cloud Run.
- 👉💻 Descarga la aplicación de IA con agentes:
mkdir zoo-keeper-lab && cd zoo-keeper-lab git init git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos git config set core.sparseCheckout true echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout git pull origin main --depth 1 cd ai-ml/agent-labs/adk_invoke_with_pubsub/ - 👉💻 Implementa la aplicación de IA basada en agentes en Cloud Run:
gcloud run deploy zookeeper-agent \ --region="${LOCATION}" \ --source="." \ --no-allow-unauthenticated \ --quiet \ --service-account="${ZOOKEEPER_SA}" \ --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"
Configura el activador de Eventarc
Después de preparar todos los recursos (temas de Pub/Sub, cuentas de servicio de IAM y servicio de Cloud Run), es hora de configurar el recurso del activador de Eventarc. Crearás el recurso del activador de Eventarc y otorgarás los permisos para llamar al servicio de Cloud Run a la cuenta de servicio del activador.
- 👉💻 Crea un activador de Eventarc:
gcloud eventarc triggers create invoke-agent \ --location="${LOCATION}" \ --destination-run-service="zookeeper-agent" \ --destination-run-path="/zookeeper" \ --destination-run-region="${LOCATION}" \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic="${INVOKE_TOPIC_ID}" \ --service-account="${TRIGGER_SA}" - 👉💻 Otorga permisos a la cuenta de servicio del activador para invocar el servicio de Cloud Run:
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
4. Revisa el funcionamiento de la solución
Ahora, revisa lo que acabas de implementar. En el siguiente diagrama, se reflejan todos los recursos y cómo interactúan entre sí. Usarás la CLI de gcloud para publicar un mensaje en el tema "invoke_agent". Esto simulará un evento que un servicio de terceros registra en el servicio de mensajería para invocar la aplicación de IA basada en agentes.
La implementación se protege siguiendo el principio de privilegio mínimo. El servicio de Cloud Run exige la autenticación (consulta el argumento --no-allow-unauthenticated en el paso 9 de la sección anterior). Solo las identidades con los roles/run.invoker o permisos similares pueden llamar al servicio. Este rol solo se otorga a la cuenta de servicio del activador de Eventarc. Del mismo modo, se minimiza el acceso al tema "invoke_agent" para impedir la publicación no autorizada de eventos. Aún es posible llamar al agente de ZooKeeper directamente sin publicar en el tema de Pub/Sub. Consulta la sección 6 para obtener información sobre cómo ocultar el extremo de la aplicación del acceso público.
Ejecuta el flujo de trabajo
Emularás un evento externo publicando una pregunta en lenguaje natural en ZooKeeper.
👉💻 Usa el siguiente comando para publicar un mensaje en el tema de Pub/Sub:
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
En realidad, la información del evento probablemente tendrá un formato menos legible. Para procesarlo, una aplicación de IA basada en agentes deberá tener instrucciones detalladas sobre el formato del evento, los datos y lo que el agente debe hacer con la información del evento.
Puedes verificar que el agente recibió el evento, procesó la solicitud y publicó la respuesta en el tema “agent_responses”. Para leer la respuesta, usarás la suscripción "agent_responses" (el codelab usa el mismo ID para el tema y la suscripción de las respuestas).
👉💻 Usa el siguiente comando para leer la respuesta del agente desde la suscripción de Pub/Sub:
gcloud pubsub subscriptions pull agent_responses --auto-ack
El resultado imprimirá una tabla con los metadatos del mensaje y la carga útil que contiene la respuesta de que hay 33 especies en el zoo. La marca --auto-ack confirma automáticamente la recepción del mensaje después de que se extrae, por lo que no se volverá a entregar.
Cómo funciona
Para ver el código fuente de la aplicación de IA basada en agentes, abre el Editor de Cloud Shell y consulta los archivos en la carpeta ~/zoo-keeper-lab. También puedes ver el código fuente en GitHub.
- El archivo main.py implementa una aplicación web básica de FastAPI con un solo controlador que procesa eventos de Eventarc.
- El archivo processor.py analiza el mensaje del evento para recuperar el ID del usuario y la solicitud. Luego, crea una sesión nueva en el ejecutor del ADK y llama al agente de Zookeeper para procesar la solicitud. La respuesta del agente se publica en el tema de Pub/Sub "agent_responses".
- La subcarpeta zookeeper_agent aloja el código fuente del agente de ADK. Puedes ejecutar el comando
adk run zookeeper_agentdesde la carpeta raíz de la aplicación para interactuar con el agente usando la CLI de adk.
Cómo solucionar problemas
En caso de que falle alguno de los comandos anteriores, lee el mensaje de error con atención. Si falla la implementación en Cloud Run, el primer paso será determinar en qué etapa del proceso se produjo la falla.
- Si el resultado del comando "gcloud run deploy…" indica que falló la compilación, consulta la URL de los registros de compilación en el resultado y ábrela en una ventana separada.
- Si el resultado indica algo como "No se pudo iniciar el servicio" o similar, significa que el servicio se implementa, pero luego la ejecución falla en la verificación de estado. En este caso, abre el Explorador de registros o consulta el siguiente párrafo para ver el comando de la CLI de gcloud. Lee los registros para encontrar la causa raíz de la falla.
¿Qué sucede si publicaste un mensaje en Pub/Sub, pero el agente no responde o la respuesta parece extraña?
👉💻 Usa el siguiente comando para leer los registros de la aplicación publicados desde la ejecución reciente:
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
Los registros hacen un seguimiento de la ejecución y registran errores, como cargas útiles de mensajes incorrectas o no analizables, respuestas no válidas del modelo de Gemini, parámetros de configuración del entorno no válidos y otros posibles problemas.
5. Endurece la seguridad de la implementación
El servicio de Cloud Run que implementaste expone un extremo público al que puede llamar cualquier persona en Internet. Si bien el extremo está protegido contra invocaciones no autorizadas y valida rigurosamente la estructura de la solicitud, aún deja este vector de ataque que permite ataques de denegación de servicio y de denegación de billetera. Dado que la única ruta de invocación para el servicio en el diseño actual es a través del activador de Eventarc, el servicio no necesita exponer su extremo a Internet.
👉💻 Cierra este vector de ataque restringiendo las llamadas al servicio para que solo provengan de la colección limitada de fuentes, incluidos los activadores de Eventarc:
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
Ahora, si intentas llamar a la URL del servicio desde tu máquina local, recibirás un error "404 Page not found".
👉💻 Usa curl para enviar una solicitud al extremo del servicio:
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
Verás un resultado similar al siguiente:
<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>404 Page not found</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Page not found</h1> <h2>The requested URL was not found on this server.</h2> <h2></h2> </body></html>
Después de este cambio, ya no es posible invocar ZooKeeper directamente llamando al extremo del servicio de Cloud Run, a menos que realices la llamada desde la VPC en el mismo proyecto, la red de VPC compartida a la que se configuró tu revisión para enviar tráfico o un host que forme parte del perímetro de los Controles del servicio de VPC.
6. Resumen
¡Felicitaciones! Configuraste correctamente un entorno para invocar de forma asíncrona tu aplicación de IA basada en agentes que se activa con eventos entrantes.
Limpia
Ten en cuenta que mantener los recursos que aprovisionaste puede generar cargos en tu cuenta de facturación. Si no planeas usar este entorno para más experimentos y evitar cargos futuros, te recomendamos que borres los recursos que se crearon durante este codelab.
Existen dos métodos para hacerlo:
Método 1: Cómo dar de baja el proyecto
Si cierras (borras) el proyecto, se liberarán todos sus recursos y datos, y se desvinculará la cuenta de facturación. Con este método, se evitan cargos adicionales por los recursos o los datos que se usen en este codelab. Usa el siguiente comando para apagar el proyecto:
gcloud projects delete $(gcloud config get-value project) --quiet
Método 2: Borra recursos del proyecto
Borrar el servicio de Cloud Run protege contra cargos adicionales por usar la plataforma sin servidores. Ten en cuenta que este método no quita por completo todos los datos generados durante el codelab, como los registros de Cloud Build y de la aplicación, las imágenes de contenedores, etcétera. Ejecuta el siguiente comando para borrar el servicio:
gcloud run services delete zookeeper-agent --region=${LOCATION}
La definición del activador de Eventarc y los temas de Pub/Sub no imponen costos de administración (consulta los precios de Eventarc y los precios de Pub/Sub para obtener más detalles).
Obtén más información para cerrar el proyecto.
¿Qué sigue?
- Revisa la demostración en GitHub para obtener más información sobre el código.
- Revisa la arquitectura que coordina el acceso a sistemas empresariales dispares
- Obtén información para activar Cloud Run con activadores de Eventarc
- Más información sobre el ADK