Déployer un agent ADK sur Agent Runtime à l'aide de la CLI Agents

1. Présentation

Cet atelier fait partie du cours intensif de cinq jours sur le Vibe coding d'agents IA avec Google de Kaggle. Vous trouverez d'autres ateliers de programmation et ressources sur le site de l'événement.

Dans cet atelier de programmation, vous allez transférer un agent ADK 2.0 d'un environnement de développement local vers un déploiement de niveau production. Vous allez utiliser agents-cli pour empaqueter, valider et héberger votre workflow basé sur un graphique en direct sur Agent Runtime sur Google Cloud.

Pour explorer ce processus de déploiement, vous allez créer un prototype local de l'agent de gestion des notes de frais ambiantes à partir de zéro avant de le déployer dans le cloud. (Pour en savoir plus sur la conception de la logique de base de cet agent, consultez les ateliers de programmation de base sur le site de l'événement Kaggle.) L'agent Ambient Expense simplifie le reporting des dépenses des employés en approuvant instantanément les demandes standards et en signalant les dépenses plus importantes pour examen par un humain. En arrière-plan, il utilise un workflow basé sur un graphique ADK 2.0 pour coordonner ces étapes d'approbation et d'analyse des risques automatisées.

Points abordés

• Comment préparer votre projet Ambient Expense Agent local pour l'hébergement dans le cloud.
• Comment créer les descripteurs de déploiement et les wrappers de production nécessaires.
• Comment effectuer des simulations et déployer votre code directement sur Agent Runtime.
• Découvrez comment surveiller les traces d'exécution de votre agent de production à l'aide de Cloud Trace.

Prérequis

• Un projet Google Cloud actif avec la facturation activée.
• Le SDK gcloud est installé et authentifié.
• Le gestionnaire de paquets uv est installé.
• L'IDE Google Antigravity est installé.

Prérequis

Pour suivre cet atelier de programmation, vous devez maîtriser les éléments suivants :

• Naviguer dans votre système à l'aide d'un terminal.
• Concepts de base du développement Python.
• Concepts fondamentaux de Google Cloud

2. Configurer votre environnement Google Cloud

Avant de déployer, vous devez configurer votre projet Google Cloud et activer les API nécessaires.

👉 Requête 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).

Lorsqu'Antigravity exécute cette requête, il propose et exécute les commandes de terminal gcloud nécessaires pour configurer votre projet et activer les services. Lors de l'étape d'authentification, Antigravity affiche une URL d'autorisation dans le terminal. Cliquez sur le lien pour vous connecter via votre navigateur Web et accorder l'accès. Une fois que vous vous êtes connecté au navigateur, Antigravity reprend l'exécution pour définir les variables d'environnement de votre projet et activer les API requises.

Remarque : Si vous utilisez un nouveau projet, gcloud peut vous inviter à activer d'abord l'API Service Usage. Si vous y êtes invité, suivez le lien fourni dans le terminal pour l'activer dans la console Cloud.

3. Configurer la CLI Agents et les compétences ADK

Pour qu'Antigravity puisse compiler et déployer correctement les agents ADK, il a besoin de l'ensemble de compétences ADK. Il s'agit de références groupées pour l'API ADK, l'échafaudage de projet, le workflow de déploiement agents-cli et l'évaluation. L'installation de la chaîne d'outils agents-cli installe également ces compétences dans votre agent de codage, ce qui lui permet de gérer l'intégralité du cycle de vie de votre agent, de l'échafaudage local au déploiement dans le cloud.

👉 Copiez et collez le prompt suivant dans 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.

Lorsqu'Antigravity exécute ce prompt, il exécute uvx google-agents-cli setup dans le terminal pour installer la CLI et ses compétences associées. Il exécute ensuite agents-cli info pour vérifier l'installation et liste les compétences de domaine nouvellement installées (telles que google-agents-cli-deploy et google-agents-cli-workflow) directement dans le chat.

Remarque pour les utilisateurs d'Antigravity : Au cours de cet atelier de programmation, Antigravity peut générer des plans d'implémentation ou afficher des pop-ups avant d'exécuter des commandes ou d'écrire du code. Veillez à examiner et à approuver ces forfaits ou pop-ups pour permettre à Antigravity de poursuivre les tâches.

Conseil concernant les quotas : Si vous manquez de quota pendant les tests ou le développement, passez à un autre modèle disponible dans Antigravity.

4. Créer votre projet d'agent

Maintenant que votre environnement cloud est configuré et que vous avez installé les compétences de la CLI, vous êtes prêt à générer la base de code locale pour votre agent. Dans cette étape, vous allez utiliser Antigravity pour créer un prototype d'agent Ambient Expense entièrement fonctionnel et compatible avec ADK 2.0.

Remarque pour les utilisateurs de Kaggle 5 Days of AI Agents : Si vous avez réussi l'atelier de programmation Vibecode Ambient Expense Agent pour le jour 4 et que vous préférez déployer votre codebase d'agent personnalisé existante, vous pouvez ignorer cette étape d'échafaudage et passer à l'étape suivante.

👉 Requête 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.

Lorsqu'Antigravity exécute cette requête, il utilise les compétences d'échafaudage nouvellement installées pour exécuter agents-cli scaffold create expense-agent --adk dans le terminal. Il vérifiera ensuite le code du prototype généré et l'ajustera pour s'assurer que votre expense-agent implémente correctement le seuil d'approbation automatique $100 et le flux d'examen human-in-the-loop dans son workflow de graphique Agent Development Kit (ADK).

5. Préparer le déploiement en production

Agent Runtime est un service Google Cloud entièrement géré qui vous permet de déployer, de gérer et de faire évoluer des agents IA en production. Agent Runtime gère les complexités opérationnelles de l'hébergement, en offrant un environnement avec état doté de fonctionnalités telles que la gestion des sessions, la mémoire à long terme et les bacs à sable d'exécution de code sécurisé.

Pourquoi déployer sur Agent Runtime ?

Lorsque vous créez des agents localement avec Antigravity, votre agent s'exécute sur votre ordinateur local par rapport à localhost. Bien qu'ils soient parfaits pour le prototypage rapide, les agents locaux cessent de s'exécuter dès que vous fermez votre ordinateur portable.

Le déploiement de votre agent dans Agent Runtime transfère votre workflow dans un environnement Google Cloud entièrement géré et toujours actif. Cela établit un point de terminaison de backend sécurisé et en direct qui reste actif 24h/24 et 7j/7. Dans le prochain atelier de programmation, vous allez créer une interface Web qui se connecte directement à ce point de terminaison cloud, ce qui donnera à votre agent une URL publique.

De plus, Agent Runtime fournit une infrastructure dédiée optimisée spécifiquement pour les agents d'IA, offrant des fonctionnalités intégrées telles que :

• Exécution avec état gérée : gestion de session intégrée et persistance de la mémoire à long terme au cours des tours de conversation.
• Bac à sable sécurisé : exécute de manière sécurisée les appels d'outils dynamiques et le code généré par l'agent dans des environnements isolés.
• Observabilité Enterprise : flux de télémétrie prêt à l'emploi directement vers Cloud Trace et Cloud Logging.

Pour héberger votre agent sur Agent Runtime, vous devez améliorer le répertoire de votre projet en local avec des descripteurs de production, des schémas et des wrappers de point de terminaison.

👉 Requête Antigravity :

Scaffold the production deployment files for Agent Runtime.

Lorsqu'Antigravity exécute cette invite, il exécute agents-cli scaffold enhance --deployment-target agent_runtime --yes dans la racine de votre projet. Cette commande analyse votre répertoire et génère automatiquement les éléments suivants :

• app/agent_runtime_app.py : wrapper de service de niveau production.
• deployment_metadata.json : schéma de mise en page utilisé par Agent Runtime pour lancer des ressources.

La logique de votre agent principal dans app/agent.py reste entièrement intacte et préservée.

6. Empaquetage et validation locale

Avant de lancer un import dans le cloud, verrouillez vos packages et exécutez un test à blanc local pour identifier les conflits de dépendances potentiels.

👉 Requête Antigravity :

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

Lorsqu'Antigravity exécute cette invite, il exécute d'abord uv lock dans le terminal pour générer un fichier de verrouillage déterministe, ce qui garantit des versions de bibliothèque cohérentes dans le cloud. Il exécute ensuite agents-cli deploy --dry-run pour vérifier la validité de la configuration et prévisualiser les étapes de déploiement sans provisionner de ressources cloud. Vous pouvez examiner le résultat de l'exécution à blanc dans le terminal pour vérifier que tous les fichiers et paramètres sont corrects.

7. Déployer sur Agent Runtime

Déployez votre agent Ambient Expense sur Agent Runtime.

👉 Requête Antigravity :

Deploy this agent to Agent Runtime.

Lorsqu'Antigravity exécute cette requête, il active la compétence google-agents-cli-deploy et exécute agents-cli deploy --project YOUR_PROJECT_ID --region us-west1. Le processus d'empaquetage, d'importation et de provisionnement d'Agent Runtime prend généralement 5 à 10 minutes. Antigravity surveillera la progression du déploiement dans le terminal et, une fois terminé, affichera l'URL de votre point de terminaison actif.

💡 Conseil de pro (gérer les fenêtres de délai avant expiration) : Si vous préférez ne pas bloquer votre terminal pendant les déploiements longs, vous pouvez demander à Antigravity d'utiliser l'indicateur --no-wait pour démarrer le déploiement de manière asynchrone et vérifier la progression ultérieurement à l'aide de agents-cli deploy --status.

Si vous rencontrez des problèmes lors du déploiement de votre agent, envisagez d'utiliser une autre région. L'outil de sélection de région Google Cloud peut vous aider à déterminer la région la mieux adaptée à votre projet en fonction de la latence, du prix et de l'empreinte carbone.

8. Tester votre agent

Une fois votre agent déployé, vous pouvez vérifier qu'il approuve automatiquement les petites dépenses et signale correctement les dépenses plus importantes pour une vérification par un humain.

👉 Demandez à Antigravity de vérifier le moteur déployé en direct :

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.

Remarque : Lorsque Antigravity exécute cette invite de test sur votre point de terminaison actif, s'il rencontre des erreurs de déploiement ou d'exécution, il tente automatiquement de résoudre le problème, d'appliquer les corrections de code nécessaires et de redéployer l'agent pour vous.

Vous pouvez également tester votre agent manuellement à l'aide de l'aperçu du terrain de jeu de la console Cloud. Pour ouvrir le bac à sable :

1. Dans la console Google Cloud, utilisez le menu de navigation pour sélectionner Agent Platform > Déploiements.
2. Sélectionnez l'agent déployé dans la liste des déploiements.
3. Cliquez sur le bouton Playground pour ouvrir l'interface de chat de test interactive.

👉 Pour tester l'approbation automatique (moins de 100 $), collez la charge utile JSON suivante dans la zone de chat :

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

Vous devriez recevoir une réponse JSON indiquant le résultat du nœud auto_approve avec l'état "approved" (approuvé).

👉 Pour tester le flux Human-in-the-Loop (HITL), collez la charge utile JSON suivante.

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

Cela déclenchera l'agent review_agent, émettra l'alerte d'avertissement, puis mettra l'exécution en pause, ce qui générera un RequestInput (Human-in-the-loop) demandant une approbation.

9. Surveiller et observer votre agent de production

Avec Agent Runtime, la télémétrie est automatiquement câblée. Chaque interaction, appel de modèle et exécution d'outil transmet des journaux et des spans en temps réel à votre projet.

1. Inspecter les traces : ouvrez la console Cloud Trace pour auditer les cartes de transactions en direct, les latences des modèles et les étapes d'exécution des outils.
2. Journaux d'audit : utilisez Cloud Logging pour inspecter la sortie standard en temps réel et les traces de pile de diagnostic.

3. Analytics agrégés : si l'indicateur --bq-analytics a été activé lors de l'échafaudage, interrogez vos journaux dans BigQuery à l'aide de SQL pour afficher les ratios d'approbation et les tendances des tours de conversation.

La requête SQL suivante fournit un exemple de calcul des taux d'approbation. Vous pouvez demander à Antigravity de personnaliser cette requête pour votre projet et votre ensemble de données BigQuery spécifiques :

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. (Facultatif) Vérifier l'enregistrement dans le registre d'agents

Pour permettre à d'autres services, développeurs ou agents de votre organisation de découvrir et d'utiliser votre agent de dépenses de manière sécurisée, vous devez l'enregistrer dans le registre des agents de l'entreprise (Gemini Enterprise).

Comme vous avez déployé votre agent sur Agent Runtime, il est automatiquement enregistré dans le registre d'agents. Toute mise à jour ou suppression ultérieure de votre agent dans Agent Runtime sera également automatiquement synchronisée avec le registre d'agents.

👉 Demandez à Antigravity de vérifier l'enregistrement automatique de votre agent :

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

Lorsqu'Antigravity exécute cette invite, il exécute agents-cli publish gemini-enterprise --list dans le terminal. Cette requête interroge le registre d'agents et liste tous les agents Gemini Enterprise enregistrés dans votre projet. Vous pouvez ainsi vérifier que votre agent Ambient Expense est actif et détectable dans votre organisation.

11. Effectuer un nettoyage

Participants au cours Kaggle : si vous suivez cet atelier dans le cadre du cours 5-Day AI Agents de Kaggle et que vous prévoyez de passer à l'atelier suivant (Vibecode and Deploy a Frontend for an ADK Agent) pour créer le client frontend et l'intégration Pub/Sub, ne supprimez pas l'agent que vous avez déployé. Vous aurez besoin de cette infrastructure cloud active pour le prochain atelier.

Pour éviter que des frais ne soient facturés en permanence sur votre compte Google Cloud, vous devez arrêter et nettoyer les ressources déployées lorsque vous avez terminé.

👉 Requête 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.

Lorsqu'Antigravity exécute cette requête, il automatise l'ensemble du processus de nettoyage des ressources :

1. Supprimer l'agent déployé : il lit deployment_metadata.json pour obtenir l'ID de l'environnement d'exécution de l'agent à distance, puis supprime par programmation l'instance de moteur en direct de Vertex AI.
2. Nettoyer l'espace de travail local : supprime le fichier deployment_metadata.json obsolète de la racine de votre projet.
3. Nettoyer Artifact Registry : exécute gcloud artifacts docker images delete pour supprimer les images de conteneurs créées d'Artifact Registry, libérant ainsi de l'espace de stockage cloud.

12. Félicitations

Félicitations ! Vous avez déployé et validé un agent Ambient Expense de qualité production sur Google Cloud.

Ce que vous avez appris

• Configuration de Google Cloud : identifiants du projet configurés et API de plate-forme requises activées.
• Outils et compétences : agents-cli installé et compétences associées à ADK chargées dans Antigravity.
• Scaffolding de production : scaffolding Agent Runtime généré pour un agent ADK 2.0.
• Validation locale : création de fichiers de verrouillage déterministes (uv lock) et exécution de vérifications en mode simulation.
• Déploiement cloud : hébergez votre agent en production sur une infrastructure Agent Runtime gérée.
• Observabilité et analyse : exécution tracée dans Cloud Trace et télémétrie analysée dans BigQuery.
• Enterprise Discovery : enregistrement automatique validé dans le registre des agents Enterprise.

Et maintenant ?

• Effectuer des analyses BigQuery : interrogez les journaux de télémétrie de votre agent dans BigQuery pour analyser les taux d'approbation et les tendances des tours de conversation au fil du temps.
• Atelier de programmation "Vibe to Live" : utilisez Google Antigravity pour développer un client d'interface sur Cloud Run et le connecter directement au point de terminaison de votre backend Agent Runtime en direct.

Gagnez votre badge Kaggle 5-Day AI Agents 🎉

Vous avez suivi cet atelier dans le cadre du cours intensif de cinq jours Agents IA : cours intensif de vibe coding avec Google de Kaggle ? Demandez votre badge d'obtention :

Obtenir le badge "5 jours avec les agents d'IA"

Références

• Documentation Agent Development Kit (ADK)
• Environnements d'exécution Gemini Enterprise Agent Platform
• Guide de référence d'Agents CLI (agents-cli)
• Présentation du registre d'agents Gemini Enterprise
• Documentation Google Cloud Trace