Discurso de apertura para desarrolladores de Next ‘26: Depuración de agentes a gran escala

1. Introducción

En este codelab, aprenderás a depurar agentes de IA que se ejecutan en Google Cloud. Implementarás un agente de simulador en Agent Runtime, usarás Cloud Observability para detectar problemas y usarás Gemini Cloud Assist y el IDE de Antigravity para identificar la causa raíz y corregir errores en tiempo real.

La premisa de esta demostración es que acabamos de agregar ADK EventCompaction al agente de Simulator. Esto permite que el Simulador resuma periódicamente su flujo de trabajo con Gemini, lo que reduce el contexto total que se envía al modelo en cada turno y, de este modo, mejora la calidad de la respuesta y reduce los costos totales. Sin embargo, aprenderemos que hay un error en nuestro EventCompactionConfig, lo que provoca errores en el agente. En este codelab, se explica cómo encontrar ese tipo de problemas y solucionarlos rápidamente.

Actividades

• Implementa el agente de Marathon Simulator en Agent Runtime.
• Configura una alerta de Cloud Monitoring para detectar errores del agente.
• Investiga errores con Cloud Trace y Gemini Cloud Assist.
• Identifica la causa raíz del problema y aplica un parche al agente con Antigravity y MCP.

Nota: Actualmente, Gemini Cloud Assist se encuentra en versión preliminar privada. No es necesario que estés en la lista de entidades permitidas para que Cloud Assist ejecute este codelab. Todos los pasos de Cloud Assist se encuentran aislados en el paso 8 (opcional): Usa las investigaciones de Cloud Assist. Omite esta página si aún no puedes acceder a Cloud Assist.

Requisitos

• Un navegador web, como Chrome
• Una Cuenta de Google
• Antigravity (compatible con Mac, Linux y Windows)
• Python 3.13 y versiones posteriores.
• uv (administrador de paquetes de Python)

Duración estimada: 45 minutos

Costo estimado: Menos de USD 5

2. Antes de comenzar

Crea un proyecto de Google Cloud

1. En la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud.

Configura tu entorno

Abre Antigravity y accede. Luego, abre una terminal presionando cmd-shift-P (o ctrl-shift-P) y, luego, escribiendo "Create New Terminal".

1. Desde la terminal, autentícate en Google Cloud:

gcloud auth login
gcloud auth application-default login

2. Establece tu ID del proyecto:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

Habilita las APIs

Ejecuta el siguiente comando para habilitar las APIs de Google Cloud requeridas:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

Si se te agregó a la lista de entidades permitidas para Gemini Cloud Assist (versión preliminar privada), habilita estas APIs adicionales:

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. Configura el agente de Simulator

En este paso, clonarás el repositorio de demostración y configurarás las variables de entorno para el agente de Simulator.

Clona el repositorio

Clona el repositorio de next-26-keynotes y navega al directorio de demostración:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

Configura variables de entorno

El agente de Simulator usa un archivo .env para la configuración.

Ubica el archivo sample.env en el lado izquierdo de la ventana Antigravity (Explorador):

Abre sample.env y actualiza el campo GCP_PROJECT_ID con el ID real de tu proyecto de Google Cloud. El archivo debería verse de la siguiente manera:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

Habilitaremos las integraciones de OpenTelemetry para capturar seguimientos detallados de las llamadas a herramientas y el flujo de razonamiento del agente.

4. Implementa el agente de Simulator en Agent Runtime

Ahora, implementarás el agente en Agent Runtime con el Kit de desarrollo de agentes (ADK).

Instala dependencias

uv sync

Implementa en Agent Runtime

1. Ejecuta el comando adk deploy. En este paso, se empaqueta tu agente y se implementa en Google Cloud (Agent Runtime).

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Este proceso puede tardar hasta 5 minutos en ejecutarse. Finalmente, deberías ver un resultado como este:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

Toma nota del ID del entorno de ejecución del agente generado. Lo necesitarás más adelante.

2. En un navegador web, abre la consola de Agent Runtime. Deberías ver que simulator_agent se ejecuta en Agent Runtime, con la recopilación de telemetría habilitada.

5. Configura una política de alertas

Para detectar automáticamente los errores de Agent Runtime, crearás una alerta basada en registros en la consola de Google Cloud.

1. Navega a la consola de Cloud Monitoring - Alerting.

2. Haz clic en Editar canales de notificaciones. Desplázate hacia abajo hasta el tipo Correo electrónico y, luego, crea un canal de notificaciones por correo electrónico para enviarlo a tu correo electrónico personal. Haga clic en Guardar.

3. Regresa al panel de Alertas y haz clic en Crear política.
4. En el lado derecho de la pantalla, haz clic en Crear alerta basada en registros.

5. Se te redireccionará al Explorador de registros. Pega la siguiente consulta de registro y reemplaza por tu ID del proyecto.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

Esta consulta de registro busca registros de Error en tu agente de Agent Runtime, en el que ReasoningEngine es el nombre de la API subyacente de Agent Runtime.

6. Haga clic en Ejecutar consulta. Aún no verás ningún registro, lo cual es normal.
7. Haz clic en Acciones en la barra de herramientas de resultados y, luego, en Crear alerta de registro.

8. Configura la alerta basada en registros. Asigna un nombre a la alerta (cualquiera) y, luego, establece el nivel de gravedad en Error.

9. Haz clic en Siguiente para ir a la sección "Establecer la frecuencia de las notificaciones" (mantén la configuración predeterminada).

10. En ¿Quiénes deben recibir notificaciones?, configura la alerta para que active el canal de notificaciones por correo electrónico que acabas de configurar (es decir, My Email).
11. Haz clic en Guardar.

6. Activa el incidente

Ahora que el agente está implementado y supervisado, intentemos invocar la simulación de maratón de una manera que arroje un error.

1. En la consola de Google Cloud, navega a la consola de Agent Runtime.
2. Haz clic en simulator_agent.
3. En la barra de herramientas superior, haz clic en Playground. Esto iniciará una nueva sesión con el agente de ADK.

4. En la ventana de chat de la sesión, escribe Test Simulation y presiona Intro para enviar la instrucción.

Esto iniciará la simulación de la maratón, en la que se hará un seguimiento de miles de corredores simulados a lo largo de la ruta planificada. Deberías ver varias llamadas a herramientas para get_runner_telemetry y analyze_medical_risk, ya que la simulación evalúa varias "zonas" de la carrera.

Después de unos minutos, deberías ver que el agente deja de ejecutarse y devuelve sin respuesta.

5. En un plazo aproximado de un minuto, deberías ver un correo electrónico en tu carpeta Recibidos que te alerta sobre un nuevo incidente en el agente.

Haz clic en Ver incidente para abrir la consola de Cloud Monitoring. Continúa a la siguiente página para investigar el problema en la consola.

7. Investiga el incidente en la consola

1. Visualiza el incidente en la consola de Cloud Monitoring. Deberías ver registros de errores provenientes del agente del simulador.

Desde esta vista, es difícil ver exactamente en qué punto falló el agente. Para ver las llamadas a herramientas subyacentes del agente y el flujo de razonamiento, examinaremos los registros de seguimiento del agente.

2. Vuelve a abrir la consola de Agent Runtime. Haz clic en simulator_agent y, luego, abre la pestaña Traces.

3. Haz clic en el registro más reciente de la lista. Luego, en la esquina superior derecha, haz clic en Cronograma. Deberías ver un registro con "intervalos" individuales. Un tramo representa una llamada a un modelo o herramienta dentro del flujo de trabajo del agente.

4. Haz clic en el último intervalo en la vista de seguimiento. Debería ser rojo.
5. Haz clic en Stacktrace. Deberías ver registros de errores relacionados con una llamada al modelo de la API de Gemini. Específicamente, un error 400: Invalid Argument. Esto indica un problema a nivel de la solicitud con una carga útil que el agente de Simulator envió a la API de Gemini.

8. [Opcional] Usa las investigaciones de Cloud Assist para depurar

Sigue estos pasos solo si se te agregó a la lista de entidades permitidas para la versión preliminar privada de Gemini Cloud Assist. De lo contrario, continúa con la página siguiente.

1. En el tramo con errores, haz clic en Registros y eventos. Busca el registro "Exception" que tiene el botón de brillo junto a él. Luego, haz clic en Investigate Log.

2. Esto iniciará una investigación de Cloud Assist desde una barra lateral en el lado derecho de la pantalla. La carga tardará entre 3 y 5 minutos.

3. Una vez que se complete, abre la investigación.

4. Consulta el Resumen de la investigación.

5. Desplázate hacia abajo y consulta las Hipótesis. Gemini Cloud Assist debería haber identificado la línea específica del archivo agent.py del agente de Simulator que genera el error 400 de la API de Gemini.

Profundicemos más en el tema abriendo el código fuente de nuestro agente y usando Antigravity para encontrar la causa raíz del problema. Continúa a la página siguiente.

9. Usa Antigravity para identificar la causa raíz del problema y aplicar el parche

1. Vuelve a abrir Antigravity.
2. Abre Agent Manager en la parte superior derecha de la pantalla.

3. Asegúrate de que el modelo esté configurado en el modo Planificación y Gemini 3 Flash.

4. Ingresa la siguiente instrucción y presiona Intro.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

Deberías ver a Antigravity examinando el código en agent.py y buscando problemas relevantes en GitHub:

La causa raíz del error 400 de la API de Gemini es que estamos superando el límite de tokens de contexto de entrada de Gemini 3 Flash, que es de aproximadamente 1 millón. El motivo por el que sucede esto es que no activamos EventCompaction con la frecuencia suficiente para resumir de manera eficaz las enormes respuestas de las llamadas a herramientas de los agentes del simulador.

Para solucionar este problema, Antigravity debería sugerir agregar un parámetro token_threshold al EventsCompactionConfig para comprimir periódicamente el contexto en cada invocación una vez que alcancemos una cierta cantidad de tokens.

Esto se alinea con la corrección sugerida en este problema de GitHub.

Aplica la corrección a agent.py.

Valida que veas algo similar a lo siguiente:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

Es importante que se establezcan token_threshold y event_retention_size.

10. Vuelve a implementar y valida la corrección

Ahora que aplicamos la corrección de token_threshold al EventCompactionConfig del agente del ADK, podemos volver a implementar el agente del simulador en Agent Runtime.

1. Abre Antigravity > New Terminal.
2. Configurar variables de entorno El AGENT_RUNTIME_ID debe ser el nombre de recurso completo de tu simulator_agent. Puedes encontrarlo en la lista de agentes de la consola de Agent Runtime.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. Vuelve a implementar el agente:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Este comando tardará unos minutos en ejecutarse. Cuando se complete la operación, deberías ver lo siguiente:

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. Abre la consola de Agent Runtime. Vuelve a abrir el archivo simulator_agent. Haz clic en Playground.
5. Ingresa la misma instrucción: Test Simulation y, luego, presiona Intro.
6. La simulación completa de Marathon en el backend debería tardar unos minutos en ejecutarse. Deberías ver varias llamadas a herramientas. Finalmente, deberías ver una respuesta como la siguiente:

Esto indica que el simulador se ejecutó correctamente. ✅

7. Abre la vista de registro para esa sesión del ADK.
8. Deberías ver todos los intervalos “azules”, sin errores rojos. Observa cómo el recuento total de tokens de las sesiones supera el límite de 1 millón de tokens de contexto de la API de Gemini. No hay problema, ya que ahora EventCompaction se ejecuta con la frecuencia suficiente dentro de cada invocación para evitar alcanzar el límite de contexto general para las llamadas de modelos individuales.

🎊 ¡Hurra! Corregimos el error en el agente de Simulator.

11. Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud, borra los recursos que creaste durante este codelab.

Borra la app de Agent Runtime

Puedes borrar la instancia de Reasoning Engine a través de la consola o con el comando gcloud (si tienes el nombre del recurso). Para simplificar, usa la consola:

1. Ve a la página Agent Runtime.
2. Selecciona simulator_agent > haz clic en el botón de tres puntos en el lado derecho.
3. Haz clic en Borrar.

Borra la política de Cloud Monitoring

1. Ve a la consola de Cloud Monitoring -> Alertas.
2. Desplázate hacia abajo hasta Políticas y, luego, haz clic en el botón de tres puntos para Borrar la política.

12. 🎊 ¡Felicitaciones!

¡Felicitaciones! Acabas de depurar correctamente un agente de IA en Google Cloud.

Qué aprendiste

• Cómo implementar agentes en Agent Runtime
• Cómo detectar errores con las alertas de Cloud Monitoring
• Cómo explorar incidentes activos con Cloud Logging y la vista de seguimiento del tiempo de ejecución del agente
• Cómo investigar fallas con Gemini Cloud Assist
• Cómo usar Antigravity para identificar la causa raíz de los errores del agente y corregirlos
• Cómo ajustar ADK Event Compaction para controlar turnos de agentes de larga duración y con muchas herramientas.

Próximos pasos

• Obtén más información sobre Agent Runtime.
• Obtén más información sobre el Kit de desarrollo de agentes.
• Obtén más información sobre las alertas en Cloud Monitoring.
• Obtén más información sobre Gemini Cloud Assist.