Implementa un agente del ADK en Agent Runtime con la CLI de Agents

1. Descripción general

Este lab forma parte del curso intensivo de vibe coding de 5 días con agentes de IA de Google de Kaggle. Puedes encontrar los codelabs y recursos adicionales disponibles en el sitio del evento.

En este codelab, harás la transición de un agente de ADK 2.0 de un entorno de desarrollo local a una implementación de nivel de producción. Usarás agents-cli para empaquetar, verificar y alojar tu flujo de trabajo basado en grafos en vivo en Agent Runtime en Google Cloud.

Para explorar este proceso de implementación, compilarás un prototipo local del Agente de gastos ambientado desde cero antes de implementarlo en la nube. (Para obtener más información sobre el diseño de la lógica principal de este agente, consulta los codelabs básicos en el sitio del evento de Kaggle). El agente de gastos ambientales optimiza los informes de gastos de los empleados, ya que aprueba al instante los reclamos estándares y marca los gastos más grandes para que se revisen con la intervención humana. En segundo plano, usa un flujo de trabajo basado en grafos del ADK 2.0 para coordinar estos pasos de análisis de riesgos y aprobaciones automatizadas.

Qué aprenderás

• Cómo preparar tu proyecto local de Ambient Expense Agent para el alojamiento en la nube
• Cómo generar los descriptores de implementación y los wrappers de producción necesarios
• Cómo realizar simulaciones y, luego, implementar tu código directamente en Agent Runtime
• Cómo supervisar los registros de ejecución de tu agente de producción con Cloud Trace

Requisitos

• Un proyecto de Google Cloud activo con la facturación habilitada.
• El SDK de gcloud instalado y autenticado
• El administrador de paquetes uv instalado
• IDE de Google Antigravity instalado

Requisitos previos

En este codelab, se supone que tienes experiencia en lo siguiente:

• Navegar por el sistema con una terminal
• Conocimientos básicos de los conceptos de desarrollo en Python
• Conceptos fundamentales de Google Cloud

2. Configura tu entorno de Google Cloud

Antes de implementar, debes configurar tu proyecto de Google Cloud y habilitar las APIs necesarias.

👉 Solicitar Antigravity:

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

Cuando Antigravity ejecute esta instrucción, propondrá y ejecutará los comandos de terminal gcloud necesarios para configurar tu proyecto y habilitar los servicios. Durante el paso de autenticación, Antigravity mostrará una URL de autorización en la terminal. Haz clic en el vínculo para acceder a través de tu navegador web y otorgar acceso. Una vez que completes el acceso con el navegador, Antigravity reanudará la ejecución para establecer las variables de entorno de tu proyecto y habilitar las APIs requeridas.

Nota: Si este es un proyecto nuevo, es posible que gcloud te solicite que primero habilites la API de Service Usage. Sigue el vínculo que se proporciona en la terminal para habilitarlo en la consola de Cloud si se te solicita.

3. Configura la CLI de Agents y las habilidades del ADK

Para que Antigravity cree e implemente bien los agentes del ADK, necesita el conjunto de habilidades del ADK. Son referencias agrupadas para la API del ADK, el andamiaje del proyecto, el flujo de trabajo de implementación de agents-cli y la evaluación. La instalación de la cadena de herramientas agents-cli también instala estas habilidades en tu agente de codificación, lo que lo equipa para administrar el ciclo de vida completo de tu agente, desde el andamiaje local hasta la implementación en la nube.

👉 Copia y pega la siguiente instrucción en Antigravity:

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

Cuando Antigravity ejecuta esta instrucción, ejecuta uvx google-agents-cli setup en la terminal para instalar la CLI y sus habilidades complementarias. Luego, ejecuta agents-cli info para verificar la instalación y enumera las habilidades de dominio recién instaladas (como google-agents-cli-deploy y google-agents-cli-workflow) directamente en el chat.

Nota para los usuarios de Antigravity: Durante este codelab, es posible que Antigravity genere planes de implementación o muestre ventanas emergentes antes de ejecutar comandos o escribir código. Asegúrate de revisar y aprobar estos planes o ventanas emergentes para permitir que Antigravity continúe con las tareas.

Sugerencia sobre la cuota: Si te quedas sin cuota durante las pruebas o el desarrollo, cambia el modelo en Antigravity a otro modelo disponible.

4. Crea tu proyecto de agente

Con tu entorno de Cloud configurado y tus habilidades de la CLI instaladas, ya puedes generar la base de código local para tu agente. En este paso, usarás Antigravity para crear un prototipo completamente funcional del agente de gastos de Ambient compatible con el ADK 2.0.

Nota para los usuarios de Kaggle 5 days of AI Agents: Si completaste correctamente este Codelab de Vibecode Ambient Expense Agent para el día 4 y prefieres implementar tu base de código de agente personalizado existente, puedes omitir este paso de andamiaje y pasar al siguiente.

👉 Solicitar Antigravity:

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

Cuando Antigravity ejecuta esta instrucción, aprovecha las habilidades de andamiaje recién instaladas para ejecutar agents-cli scaffold create expense-agent --adk en la terminal. Luego, verificará y ajustará el código del prototipo generado para garantizar que tu expense-agent implemente correctamente el umbral de aprobación automática y el flujo de revisión con interacción humana dentro de su flujo de trabajo de gráfico del Kit de desarrollo de agentes (ADK).$100

5. Preparación para la implementación en producción

Agent Runtime es un servicio completamente administrado de Google Cloud que te permite implementar, administrar y escalar agentes de IA en producción. Agent Runtime se encarga de las complejidades operativas del alojamiento y ofrece un entorno con estado con funciones como administración de sesiones, memoria a largo plazo y zonas de pruebas de ejecución de código seguras.

¿Por qué implementar en Agent Runtime?

Cuando compilas agentes de forma local con Antigravity, tu agente se ejecuta en tu máquina local en comparación con localhost. Si bien son excelentes para el prototipado rápido, los agentes locales dejan de ejecutarse en el momento en que cierras la laptop.

Implementar tu agente en Agent Runtime traslada tu flujo de trabajo a un entorno de Google Cloud completamente administrado y siempre activo. Esto establece un extremo de backend seguro y activo que permanece activo las 24 horas, todos los días. En el siguiente codelab, crearás un frontend web que se conectará directamente a este extremo de Cloud, lo que le dará a tu agente una URL pública.

Además, Agent Runtime proporciona infraestructura dedicada optimizada específicamente para agentes de IA, con capacidades integradas como las siguientes:

• Ejecución con estado administrada: Administración de sesiones integrada y persistencia de la memoria a largo plazo en los turnos de conversación
• Zona de pruebas segura: Ejecuta de forma segura llamadas a herramientas dinámicas y código generado por agentes en entornos aislados.
• Observabilidad empresarial: Transmisión de telemetría lista para usar directamente a Cloud Trace y Cloud Logging.

Para alojar tu agente en Agent Runtime, debes mejorar el directorio de tu proyecto local con descriptores, esquemas y wrappers de extremos de producción.

👉 Solicitar Antigravity:

Scaffold the production deployment files for Agent Runtime.

Cuando Antigravity ejecuta esta instrucción, se ejecuta agents-cli scaffold enhance --deployment-target agent_runtime --yes en la raíz de tu proyecto. Este comando analiza tu directorio y genera automáticamente lo siguiente:

• app/agent_runtime_app.py: Es el wrapper del servicio apto para producción.
• deployment_metadata.json: Es el esquema de diseño que usa Agent Runtime para activar recursos.

La lógica principal del agente en app/agent.py permanece intacta y se conserva.

6. Empaquetado y verificación local

Antes de iniciar una carga en la nube, bloquea tus paquetes y ejecuta una prueba local para identificar posibles conflictos de dependencias.

👉 Solicitar Antigravity:

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

Cuando Antigravity ejecuta esta instrucción, primero ejecuta uv lock en la terminal para generar un archivo de bloqueo determinístico, lo que garantiza versiones coherentes de la biblioteca en la nube. Luego, ejecuta agents-cli deploy --dry-run para verificar la validez de la configuración y obtener una vista previa de los pasos de implementación sin aprovisionar recursos de Cloud. Puedes revisar el resultado de la ejecución de prueba en la terminal para confirmar que todos los archivos y parámetros de configuración sean correctos.

7. Implementa en Agent Runtime

Implementa tu agente de gastos ambientales en Agent Runtime.

👉 Solicitar Antigravity:

Deploy this agent to Agent Runtime.

Cuando Antigravity ejecuta esta instrucción, activa la habilidad google-agents-cli-deploy y ejecuta agents-cli deploy --project YOUR_PROJECT_ID --region us-west1. El proceso de empaquetado, carga y aprovisionamiento del entorno de ejecución de Agent2Agent suele tardar entre 5 y 10 minutos. Antigravity supervisará el progreso de la implementación en la terminal y, una vez que se complete, mostrará la URL del endpoint activo.

💡 Sugerencia profesional (administra las ventanas de tiempo de espera): Si prefieres no bloquear tu terminal durante implementaciones largas, puedes indicarle a Antigravity que use la marca --no-wait para iniciar la implementación de forma asíncrona y verificar el progreso más tarde con agents-cli deploy --status.

Si tienes problemas para implementar tu agente, considera usar otra región. La herramienta Selector de región de Google Cloud puede ayudarte a determinar la mejor región para tu proyecto en función de la latencia, el precio y la huella de carbono.

8. Prueba tu agente

Una vez que se implemente tu agente, podrás verificar que aprueba automáticamente los gastos pequeños y que marca correctamente los gastos más grandes para una verificación humana en el circuito.

👉 Solicita a Antigravity que verifique el motor implementado en vivo:

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

Nota: Cuando Antigravity ejecuta esta instrucción de prueba en tu endpoint activo, si encuentra algún error de implementación o ejecución, intentará depurar el problema automáticamente, aplicar las correcciones de código necesarias y volver a implementar el agente por ti.

Como alternativa, puedes probar tu agente de forma manual con la versión preliminar de Cloud Console Playground. Sigue estos pasos para abrir Playground:

1. En el menú de navegación de la consola de Google Cloud, selecciona Agent Platform > Deployments.
2. Selecciona el agente implementado en la lista de implementaciones.
3. Haz clic en el botón Playground para abrir la interfaz de chat de prueba interactiva.

👉 Para probar la aprobación automática (menos de USD 100), pega la siguiente carga útil de JSON en el cuadro de chat:

{"data": {"amount": 50.0, "submitter": "[e-mail]", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

Deberías recibir una respuesta JSON que muestre el resultado del nodo auto_approve con el estado "aprobado".

👉 Para probar el flujo de interacción humana (HITL), pega la siguiente carga útil de JSON.

{"data": {"amount": 150.0, "submitter": "[e-mail]", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

Esto activará el review_agent, emitirá la alerta de advertencia y, luego, pausará la ejecución, lo que generará un RequestInput (interacción humana) que solicitará aprobación.

9. Supervisa y observa tu agente de producción

Con Agent Runtime, la telemetría se conecta automáticamente. Cada interacción, llamada al modelo y ejecución de herramientas transmite registros y tramos en tiempo real a tu proyecto.

1. Inspeccionar seguimientos: Abre la consola de Cloud Trace para auditar mapas de transacciones en vivo, latencias de modelos y pasos de ejecución de herramientas.
2. Registros de auditoría: Usa Cloud Logging para inspeccionar el resultado estándar en tiempo real y los seguimientos de pila de diagnóstico.

3. Análisis agregado: Si la marca --bq-analytics se habilitó durante el andamiaje, consulta tus registros en BigQuery con SQL para ver las proporciones de aprobación y las tendencias de los turnos de conversación.

La siguiente consulta en SQL proporciona un ejemplo para calcular los porcentajes de aprobación. Puedes solicitarle a Antigravity que personalice esta consulta para tu proyecto específico y tu conjunto de datos de BigQuery:

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. (Opcional) Verifica el registro en Agent Registry

Para permitir que otros servicios, desarrolladores o agentes de tu organización descubran y usen de forma segura tu agente de gastos, este debe estar registrado en el Registro de agentes empresarial (Gemini Enterprise).

Como implementaste tu agente en Agent Runtime, se registró automáticamente en Agent Registry. Las actualizaciones o eliminaciones futuras de tu agente en Agent Runtime también se sincronizarán automáticamente con el Registro de agentes.

👉 Pídele a Antigravity que verifique el registro automático de tu agente:

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

Cuando Antigravity ejecuta esta instrucción, se ejecuta agents-cli publish gemini-enterprise --list en la terminal. Esto consulta el Registro de agentes y enumera todos los agentes de Gemini Enterprise registrados en tu proyecto, lo que te permite confirmar que tu agente de gastos ambientales está activo y se puede detectar en toda tu organización.

11. Limpia

Participantes del curso de Kaggle: Si completas este lab como parte del curso de Agentes de IA de 5 días de Kaggle y planeas continuar con el siguiente lab (Vibecode y, luego, implementa un frontend para un agente de ADK) para compilar el cliente de frontend y la integración de Pub/Sub, no borres el agente implementado. Necesitarás esta infraestructura de nube activa para el siguiente lab.

Para evitar que se apliquen cargos continuos a tu cuenta de Google Cloud, debes apagar y limpiar los recursos implementados cuando termines.

👉 Solicitar Antigravity:

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

Cuando Antigravity ejecuta esta instrucción, automatiza todo el proceso de limpieza de recursos:

1. Borra el agente implementado: Lee deployment_metadata.json para obtener el ID del entorno de ejecución del agente remoto y, luego, borra de forma programática la instancia del motor activo de Vertex AI.
2. Liberar espacio en el espacio de trabajo local: Quita el archivo deployment_metadata.json inactivo de la raíz de tu proyecto.
3. Limpieza de Artifact Registry: Ejecuta gcloud artifacts docker images delete para quitar las imágenes de contenedor compiladas de Artifact Registry y liberar espacio de almacenamiento en la nube.

12. ¡Felicitaciones!

¡Felicitaciones! Implementaste y verificaste correctamente un agente de gastos de Ambient apto para producción en Google Cloud.

Qué aprendiste

• Configuración de Google Cloud: Credenciales del proyecto configuradas y APIs de la plataforma requeridas habilitadas.
• Herramientas y habilidades: Se instalaron agents-cli y se cargaron habilidades complementarias del ADK en Antigravity.
• Andamiaje de producción: Se genera el andamiaje de Agent Runtime para un agente del ADK 2.0.
• Verificación local: Se crearon archivos de bloqueo determinísticos (uv lock) y se ejecutaron verificaciones de prueba.
• Implementación en la nube: Tu agente se aloja en vivo en la infraestructura administrada de Agent Runtime.
• Observabilidad y análisis: Ejecución rastreada en Cloud Trace y telemetría analizada en BigQuery.
• Enterprise Discovery: Registro automático verificado en el registro de agentes de la empresa

¿Qué sigue?

• Realiza análisis de BigQuery: Consulta los registros de telemetría de tu agente en BigQuery para analizar las proporciones de aprobación y las tendencias de turnos conversacionales a lo largo del tiempo.
• Codelab de Vibe to Live: Usa Google Antigravity para desarrollar un cliente de frontend en Cloud Run y conectarlo directamente al extremo de backend de Agent Runtime en vivo.

Obtén tu insignia de Kaggle 5-Day AI Agents 🎉

¿Completaste este lab como parte del curso intensivo de vibe coding de 5 días con agentes de IA de Google de Kaggle? Reclama tu insignia de finalización:

Obtén la insignia de 5-Day AI Agents

Referencias

• Documentación del Kit de desarrollo de agentes (ADK)
• Tiempos de ejecución de Gemini Enterprise Agent Platform
• Guía de referencia de la CLI de Agents (agents-cli)
• Descripción general del registro de agentes de Gemini Enterprise
• Documentación de Google Cloud Trace