Keynote pour les développeurs Next 2026 : Déboguer des agents à grande échelle

1. Introduction

Dans cet atelier de programmation, vous allez apprendre à déboguer des agents d'IA exécutés sur Google Cloud. Vous allez déployer un agent de simulateur sur Agent Runtime, utiliser Cloud Observability pour détecter les problèmes, et utiliser Gemini Cloud Assist et l'IDE Antigravity pour identifier la cause et corriger les erreurs en temps réel.

Le principe de cette démo est que nous venons d'ajouter ADK EventCompaction à l'agent Simulator. Cela permet au simulateur de résumer périodiquement son workflow à l'aide de Gemini, ce qui réduit le contexte total envoyé au modèle à chaque tour, améliorant ainsi la qualité des réponses et réduisant les coûts totaux. Mais nous allons découvrir qu'il y a un bug dans notre EventCompactionConfig, ce qui provoque des erreurs dans l'agent. Cet atelier de programmation vous explique comment trouver ce type de problème et le résoudre rapidement.

Objectifs de l'atelier

• Déployez l'agent Marathon Simulator sur Agent Runtime.
• Configurez une alerte Cloud Monitoring pour détecter les erreurs d'agent.
• Analysez les erreurs à l'aide de Cloud Trace et de Gemini Cloud Assist.
• Identifier la cause première et corriger l'agent à l'aide d'Antigravity et de MCP.

Remarque : Gemini Cloud Assist est actuellement en version Preview privée. Vous n'avez pas besoin de figurer sur une liste d'autorisation pour exécuter cet atelier de programmation Cloud Assist. Toutes les étapes Cloud Assist sont isolées à l'étape 8 (facultatif) : Utiliser Cloud Assist Investigations. Ignorez cette page si vous n'avez pas encore accès à Cloud Assist.

Prérequis

• Un navigateur Web tel que Chrome.
• Un compte Google
• Antigravity (compatible avec Mac, Linux et Windows)
• Python 3.13 ou version ultérieure.
• uv (gestionnaire de packages Python)

Durée estimée : 45 minutes

Coût estimé : moins de 5 USD

2. Avant de commencer

Créer un projet Google Cloud

1. Dans la console Google Cloud, sélectionnez ou créez un projet Google Cloud.
2. Assurez-vous que la facturation est activée pour votre projet Cloud.

Configurer votre environnement

Ouvrez Antigravity et connectez-vous. Ouvrez ensuite un terminal en appuyant sur cmd-shift-P (ou ctrl-shift-P), puis en saisissant "Create New Terminal" (Créer un terminal).

1. Dans le terminal, authentifiez-vous auprès de Google Cloud :

gcloud auth login
gcloud auth application-default login

2. Définissez l'ID de votre projet :

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

Activer les API

Exécutez la commande suivante pour activer les API Google Cloud requises :

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

Si vous êtes autorisé à utiliser Gemini Cloud Assist (preview privée), activez ces API supplémentaires :

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

3. Configurer l'agent Simulator

Au cours de cette étape, vous allez cloner le dépôt de démonstration et configurer les variables d'environnement pour l'agent Simulator.

Cloner le dépôt

Clonez le dépôt next-26-keynotes et accédez au répertoire de démonstration :

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

Configurer les variables d'environnement

L'agent Simulator utilise un fichier .env pour la configuration.

Localisez le fichier sample.env sur le côté gauche de la fenêtre Antigravity (Explorateur) :

Ouvrez sample.env et mettez à jour le champ GCP_PROJECT_ID avec l'ID de votre projet Google Cloud. Le fichier doit se présenter comme suit :

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

Nous activons les intégrations OpenTelemetry pour capturer des traces précises des appels d'outils et du flux de raisonnement de l'agent.

4. Déployer l'agent simulateur sur Agent Runtime

Vous allez maintenant déployer l'agent sur Agent Runtime à l'aide de l'Agent Development Kit (ADK).

Installer des dépendances

uv sync

Déployer sur Agent Runtime

1. Exécutez la commande adk deploy. Cette étape permet d'empaqueter votre agent et de le déployer sur 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

Cette opération peut prendre jusqu'à cinq minutes. Vous devriez obtenir un résultat semblable à ce qui suit :

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

Notez l'ID Agent Runtime généré. Vous en aurez besoin plus tard.

2. Dans un navigateur Web, ouvrez la console Agent Runtime. Vous devriez voir simulator_agent s'exécuter sur Agent Runtime, avec la collecte de données de télémétrie activée.

5. Configurer une règle d'alerte

Pour détecter automatiquement les erreurs d'exécution de l'agent, vous allez créer une alerte basée sur les journaux dans la console Google Cloud.

1. Accédez à la console Cloud Monitoring > Alertes.

2. Cliquez sur Modifier les canaux de notification. Faites défiler la page jusqu'au type E-mail, puis créez un canal de notification par e-mail à envoyer à votre adresse e-mail personnelle. Cliquez sur Enregistrer.

3. Revenez au tableau de bord "Alertes", puis cliquez sur Créer une règle.
4. Sur la droite de l'écran, cliquez sur Créer une alerte basée sur les journaux.

5. Vous serez redirigé vers l'explorateur de journaux. Collez la requête de journal suivante, en remplaçant par l'ID de votre projet.

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

Cette requête de journal recherche les journaux Error dans votre agent Agent Runtime, où ReasoningEngine est le nom de l'API sous-jacente pour Agent Runtime.

6. Cliquez sur Exécuter la requête. Vous ne verrez aucun journal pour le moment, ce qui est normal.
7. Cliquez sur Actions dans la barre d'outils des résultats, puis sur Créer une alerte de journal.

8. Configurez l'alerte basée sur les journaux. Attribuez un nom à l'alerte (n'importe lequel), puis définissez le niveau de gravité sur Erreur.

9. Cliquez sur Suivant pour accéder à la section "Définir la fréquence des notifications" (conservez les valeurs par défaut).

10. Pour Qui doit être informé ?, configurez l'alerte de sorte qu'elle déclenche le canal de notification par e-mail que vous venez de configurer (par exemple, My Email).
11. Cliquez sur Enregistrer.

6. Déclencher l'incident

Maintenant que l'agent est déployé et surveillé, essayons d'appeler la simulation de marathon de manière à générer une erreur.

1. Dans la console Google Cloud, accédez à la console Agent Runtime.
2. Cliquez sur simulator_agent.
3. Dans la barre d'outils supérieure, cliquez sur Playground. Cela lancera une nouvelle session avec l'agent ADK.

4. Dans la fenêtre de chat de la session, saisissez Test Simulation, puis appuyez sur Entrée pour envoyer la requête.

La simulation du marathon commencera alors, et des milliers de coureurs virtuels parcourront l'itinéraire prévu. Vous devriez voir plusieurs appels d'outils vers get_runner_telemetry et analyze_medical_risk, car l'évaluation de la simulation évalue plusieurs "zones" de la course.

Après quelques minutes, l'agent devrait cesser de s'exécuter et ne renvoyer aucune réponse.

5. Dans un délai d'une minute environ, vous devriez recevoir un e-mail dans votre boîte de réception vous informant d'un nouvel incident dans l'agent.

Cliquez sur Afficher l'incident pour ouvrir la console Cloud Monitoring. Passez à la page suivante pour examiner le problème dans la console.

7. Examiner l'incident dans la console

1. Affichez l'incident dans la console Cloud Monitoring. Des journaux d'erreurs provenant de l'agent Simulator devraient s'afficher.

Dans cette vue, il est difficile de voir exactement à quel moment l'agent a échoué. Pour voir les appels d'outils sous-jacents de l'agent et le flux de raisonnement, nous allons examiner les traces de l'agent.

2. Rouvrez la console Agent Runtime. Cliquez sur simulator_agent, puis ouvrez l'onglet Traces.

3. Cliquez sur la trace la plus récente dans la liste. Ensuite, en haut à droite, cliquez sur Vos trajets. Une vue de trace avec des "spans" individuels devrait s'afficher. Une portée représente un appel de modèle ou d'outil dans le workflow de l'agent.

4. Cliquez sur le dernier segment dans la vue de trace. Il doit être rouge.
5. Cliquez sur Stacktrace. Vous devriez voir des journaux d'erreurs concernant un appel de modèle de l'API Gemini. Plus précisément, une erreur 400: Invalid Argument. Cela indique un problème au niveau de la requête avec une charge utile que l'agent simulateur a envoyée à l'API Gemini.

8. [Facultatif] Utiliser Cloud Assist Investigations pour déboguer

Ne suivez ces étapes que si vous êtes autorisé à utiliser Gemini Cloud Assist (version preview privée). Sinon, passez à la page suivante.

1. Dans la plage en échec, cliquez sur Journaux et événements. Recherchez le journal "Exception" avec le bouton en forme d'étincelle à côté. Cliquez ensuite sur Examiner le journal.

2. Une investigation Cloud Assist est lancée à partir d'une barre latérale sur la droite de l'écran. Le chargement prendra environ trois à cinq minutes.

3. Une fois l'enquête terminée, ouvrez-la.

4. Consultez le récapitulatif de l'investigation.

5. Faites défiler la page vers le bas et consultez les hypothèses. Gemini Cloud Assist aurait dû identifier la ligne spécifique du fichier agent.py de l'agent Simulator qui génère l'erreur 400 de l'API Gemini.

Pour en savoir plus, ouvrons le code source de notre agent et utilisons Antigravity pour trouver la cause première du problème. Passez à la page suivante.

9. Utiliser Antigravity pour identifier la cause première du problème et le corriger

1. Rouvrez Antigravity.
2. Ouvrez Agent Manager en haut à droite de l'écran.

3. Assurez-vous que le modèle est défini sur Gemini 3 Flash et que le mode est Planification.

4. Saisissez le prompt suivant, puis appuyez sur Entrée.

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.    

Vous devriez voir Antigravity examiner le code dans agent.py et rechercher les problèmes pertinents sur GitHub :

L'erreur 400 de l'API Gemini est due au fait que nous dépassons la limite de jetons de contexte d'entrée de Gemini 3 Flash, qui est d'environ un million. Cela se produit parce que nous ne déclenchons pas la compression des événements assez souvent pour résumer efficacement les énormes réponses des appels d'outils des agents du simulateur.

Pour résoudre ce problème, Antigravity doit suggérer d'ajouter un paramètre token_threshold à EventsCompactionConfig afin de compresser périodiquement le contexte à chaque appel une fois que nous avons atteint un certain nombre de jetons.

Cela correspond à la correction suggérée dans ce problème GitHub.

Appliquer la correction à agent.py.

Vérifiez que le résultat ressemble à ceci :

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,
    ),
)

Il est important de définir token_threshold et event_retention_size.

10. Redéployer et valider le correctif

Maintenant que nous avons appliqué le correctif token_threshold au EventCompactionConfig de l'agent ADK, nous pouvons redéployer l'agent Simulator sur Agent Runtime.

1. Ouvrez Antigravity > New Terminal (Nouveau terminal).
2. Définir des variables d'environnement. AGENT_RUNTIME_ID doit correspondre au nom de ressource complet de votre simulator_agent. Vous le trouverez dans la liste des agents de la console Agent Runtime.

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

3. Redéployez l'agent :

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

Cette opération prend quelques minutes. Si l'opération réussit, le message suivant s'affiche :

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

4. Ouvrez la console Agent Runtime. Rouvrez simulator_agent. Cliquez sur Playground.
5. Saisissez le même prompt : Test Simulation, puis appuyez sur Entrée.
6. L'exécution de la simulation Marathon complète du backend devrait prendre quelques minutes. Plusieurs appels d'outils devraient s'afficher. Vous devriez obtenir une réponse semblable à la suivante :

Cela indique que le simulateur a bien fonctionné. ✅

7. Ouvrez la vue "Trace" pour cette session ADK.
8. Vous devriez voir toutes les portées "bleues", sans aucune erreur rouge. Notez que le nombre total de jetons des sessions dépasse la limite de jetons de contexte de l'API Gemini, qui est de 1 million. Ce n'est pas un problème, car EventCompaction s'exécute désormais assez souvent dans chaque appel pour éviter de dépasser la limite de contexte globale pour les appels de modèle individuels.

🎊 Bravo ! Nous avons corrigé l'erreur dans l'agent Simulator.

11. Effectuer un nettoyage

Pour éviter que des frais ne soient facturés sur votre compte Google Cloud, supprimez les ressources créées lors de cet atelier de programmation.

Supprimer l'application Agent Runtime

Vous pouvez supprimer l'instance Reasoning Engine via la console ou à l'aide de la commande gcloud (si vous disposez du nom de la ressource). Pour plus de simplicité, utilisez la console :

1. Accédez à la page Agent Runtime.
2. Sélectionnez simulator_agent > cliquez sur le bouton à trois points sur la droite.
3. Cliquez sur Supprimer.

Supprimer la règle Cloud Monitoring

1. Accédez à la console Cloud Monitoring > Alertes.
2. Faites défiler la page jusqu'à Règles, puis cliquez sur le bouton à trois points pour Supprimer la règle.

12. 🎊 Félicitations !

Félicitations ! Vous venez de déboguer un agent d'IA sur Google Cloud.

Connaissances acquises

• Comment déployer des agents sur Agent Runtime.
• Détecter les erreurs à l'aide des alertes Cloud Monitoring
• Découvrez comment explorer les incidents actifs à l'aide de Cloud Logging et de la vue Trace d'Agent Runtime.
• Découvrez comment examiner les échecs à l'aide de Gemini Cloud Assist.
• Découvrez comment utiliser Antigravity pour identifier la cause première des bugs d'agent et les corriger.
• Comment affiner la compression des événements ADK pour gérer les tours d'agent de longue durée et comportant de nombreux outils.

Étapes suivantes

• En savoir plus sur Agent Runtime
• En savoir plus sur l'Agent Development Kit
• En savoir plus sur les alertes dans Cloud Monitoring
• En savoir plus sur Gemini Cloud Assist