Atelier pour débutants sur la CLI Antigravity et l'ADK (créer votre premier assistant IA)

1. Points abordés

• Installer et enregistrer une compétence pour la CLI Antigravity afin d'activer les fonctionnalités de codage dans un framework spécifique (ADK)
• Utiliser la CLI Antigravity pour générer une configuration complète d'agent ADK
• Améliorer la personnalité d'un agent en affinant ses instructions
• Ajouter un "ancrage" à votre agent en lui donnant une google_search pour répondre aux questions sur les événements récents

L'application associée IA

Dans cet atelier de programmation, vous allez donner vie à un compagnon IA visuel et interactif. Il ne s'agit pas d'un simple chatbot texte-texte. Imaginez un personnage vivant sur une page Web. Vous saisissez un message, et au lieu de simplement voir du texte, le personnage vous regarde et répond à voix haute, sa bouche bougeant en synchronisation avec ses mots.

Vous commencerez par une application Web prédéfinie, une "marionnette" numérique qui a un visage, mais pas d'esprit propre. Elle ne peut que répéter ce que vous saisissez. Votre mission consiste à construire son cerveau et sa personnalité de A à Z.

Tout au long de cet atelier, vous ajouterez progressivement des couches d'intelligence et de personnalisation, transformant cette simple marionnette en un compagnon unique et compétent. Vous allez :

• lui donner une intelligence de base à l'aide de l'ADK(Python) pour comprendre et générer du langage ;
• créer sa personnalité unique en rédigeant les instructions de base qui définissent son caractère ;
• lui accorder des superpouvoirs en lui donnant des outils pour accéder à des informations en temps réel sur Internet ;
• concevoir son apparence personnalisée en utilisant l'IA pour générer un avatar unique.

À la fin de l'atelier, vous disposerez d'un compagnon IA entièrement fonctionnel et personnalisé, créé par vous.

Architecture

Notre application suit un modèle simple, mais puissant. Nous disposons d'un backend Python qui diffuse une API. Ce backend contiendra notre agent ADK, qui agira comme le "cerveau". Toute interface utilisateur (comme le frontend JavaScript de l'application squelette, une application mobile ou même un outil de ligne de commande) peut ensuite interagir avec ce cerveau via l'API.

De plus, nous allons exploiter les fonctionnalités de génération d'images intégrées à la CLI Antigravity, en lui demandant de générer une apparence unique pour notre compagnon IA.

Obtenir une clé API Gemini

Avant de continuer, vous avez besoin d'une clé API Gemini pour authentifier vos requêtes auprès de Google AI Studio.

1. Accédez à Google AI Studio.
2. Connectez-vous à l'aide de votre compte Google.
3. Cliquez sur le bouton Obtenir une clé API dans le menu en haut à gauche.
4. Cliquez sur Créer une clé API (vous pouvez la créer dans un projet Google Cloud nouveau ou existant).
5. Copiez la clé générée. Conservez cette clé privée et sécurisée.

Créer et configurer un projet

Pour accéder à Cloud Shell, vous aurez toujours besoin d'un projet Google Cloud. Si vous n'en avez pas :

1. Accédez à la console Google Cloud.
2. Dans la barre de navigation supérieure de la console, cliquez sur Sélectionner un projet, puis sur Nouveau projet en haut à droite.
3. Attribuez un nom à votre projet, puis cliquez sur Créer. (Aucune organisation n'est requise).
4. Une fois le projet créé, sélectionnez-le dans le menu déroulant en haut de la console.

Votre projet est maintenant configuré pour l'accès à Cloud Shell.

2. Avant de commencer

👉Cliquez sur Activer Cloud Shell en haut de la console Google Cloud (il s'agit de l'icône en forme de terminal en haut du volet Cloud Shell),

👉💻 Installez la CLI Antigravity dans le terminal Cloud Shell :

curl -fsSL https://antigravity.google/cli/install.sh | bash

👉💻 Pour utiliser la CLI "agy" de manière globale, ajoutez-la à votre profil de shell :

echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

👉💻 Exportez votre clé API Gemini et enregistrez-la localement dans le terminal Cloud Shell :

# Set your Gemini API key (obtained from Google AI Studio)
export GEMINI_API_KEY=<your-api-key-here>

👉💻 Enregistrez-la pour une utilisation ultérieure :

echo $GEMINI_API_KEY > ~/gemini_key.txt

👉Trouvez votre ID de projet Google Cloud :

• Ouvrez la console Google Cloud : https://console.cloud.google.com.
• Sélectionnez le projet que vous souhaitez utiliser pour cet atelier dans le menu déroulant en haut de la page.
• Votre ID de projet s'affiche sur la fiche Informations sur le projet du tableau de bord.

👉💻 Dans le terminal, clonez le projet bootstrap à partir de GitHub :

git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh

👉💻 Exécutez le script d'initialisation. Ce script vous invite à saisir votre ID de projet Google Cloud. Saisissez l'ID de projet Google Cloud que vous avez trouvé à l'étape précédente lorsque le script init.sh vous y invite.

cd ~/companion-python
./init.sh

👉💻 Définissez l'ID de projet requis :

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 Exécutez la commande suivante pour activer les API Google Cloud nécessaires (seul Compute Engine est requis pour l'aperçu/l'hébergement Cloud Shell) :

gcloud services enable compute.googleapis.com

Installer la compétence de développeur ADK

Pour permettre à la CLI Antigravity (agy) de comprendre et d'écrire du code à l'aide de l'Agent Development Kit (ADK) Python, nous devons installer la compétence de développeur ADK Python que nous avons créée dans l'espace de travail du projet.

👉💻 Créez le répertoire local des compétences de l'agent et copiez le fichier de compétences :

mkdir -p ~/companion-python/.agents/skills/adk-python
cp ~/companion-python/skills/skill.md ~/companion-python/.agents/skills/adk-python/SKILL.md

Cela enregistre la compétence localement dans le projet. Lorsque vous lancez agy, cette compétence est automatiquement détectée et chargée, ce qui lui permet d'écrire, de modifier et d'orchestrer des agents ADK.

👉💻 Démarrez la CLI Antigravity dans votre terminal Cloud Shell :

cd ~/companion-python
agy

[!IMPORTANT] Se connecter à la CLI Antigravity

Lorsque vous exécutez la commande agy pour la première fois, vous êtes invité à vous connecter :

Welcome to the Antigravity CLI. You are currently not signed in.

 Select login method:
 > 1. Google OAuth
   2. Use a Google Cloud project

1. Choisissez l'option 1. Google OAuth en appuyant sur Enter.
2. Suivez l'invite pour ouvrir le navigateur, authentifiez-vous avec votre compte Google, puis suivez les instructions pour vous connecter.

Vous êtes maintenant dans l'invite de commande interactive de la CLI Antigravity.

Démarrer le serveur Web via la CLI Antigravity

Étant donné que la CLI Antigravity peut exécuter des commandes pour vous, demandons-lui d'exécuter le serveur en arrière-plan de votre session.

👉✨ Dans l'invite de commande de la CLI Antigravity, collez la requête suivante :

Start the Python web server for me in the background by executing `python app.py`. Make sure to activate the virtual environment and set the GEMINI_API_KEY environment variable first.

Appuyez sur Entrée pour approuver la requête d'agy visant à écrire le fichier.

La CLI exécute la commande et confirme que le serveur est en cours d'exécution. Vous resterez dans la session CLI interactive.

👀 Pour afficher l'application, cliquez sur l'icône Aperçu sur le Web dans la barre d'outils Cloud Shell. Sélectionnez Modifier le port, définissez-le sur 5000, puis cliquez sur Modifier et prévisualiser. Un aperçu de votre site Web s'affiche.

L'application initiale n'est qu'une marionnette. Elle n'a pas encore d'intelligence. Quel que soit le message que vous envoyez, elle le répète simplement. Cela confirme que notre serveur Web de base fonctionne avant que nous n'ajoutions l'IA. N'oubliez pas d'activer votre haut-parleur.

3. Créer un personnage avec la CLI Antigravity

Créons maintenant le cœur de l'intelligence de notre compagnon. Étant donné que la CLI Antigravity est déjà en cours d'exécution dans votre terminal et qu'elle gère le serveur Web en arrière-plan, vous pouvez continuer directement dans votre session interactive.

Nous utilisons la CLI pour créer un agent. Un agent est plus qu'un simple appel à un modèle de langage. Il s'agit du "cerveau" ou du contrôleur central de notre IA. Considérez-le comme une entité distincte capable de raisonner, de suivre un ensemble d'instructions spécifiques (sa personnalité) et, à terme, d'utiliser des outils pour accomplir des tâches. Dans notre projet, cet agent est le composant qui recevra les messages des utilisateurs, incarnera le persona unique de notre compagnon et formulera des réponses intelligentes et adaptées à son personnage.

👉✨ Dans l'invite de commande de la CLI Antigravity, collez le code suivant pour générer le code de l'agent :

Generate the Python code for a file named character.py.

The code must import `LlmAgent` from `google.adk.agents.llm_agent`. It should also import `logging` and `os`.
Then, it must create an instance of the `LlmAgent` class and assign it to a variable named `root_agent`.

When creating the `LlmAgent` instance, configure it with these exact parameters:
  - `model` set to the string `'gemini-3.5-flash'`.
  - `name` set to the string `'companion_agent'`.
  - `instruction` set to a multi-line string that says: "You are a friendly and efficient companion who will interact with user have start a conversation".

Appuyez sur Entrée pour approuver la requête d'agy visant à écrire le fichier.

La CLI génère le code Python.

👉Cliquez sur le bouton "Ouvrir l'éditeur" (il ressemble à un dossier ouvert avec un crayon). L'éditeur de code Cloud Shell s'ouvre dans la fenêtre. Un explorateur de fichiers s'affiche sur la gauche.

👉 Utilisez l'éditeur et accédez à character.py dans le dossier companion-python. Veuillez prendre un moment pour vérifier la ligne model= et la modifier manuellement en gemini-3.5-flash si un autre modèle a été choisi. Cela garantira la cohérence pour le reste de notre atelier.

Remarque : Les grands modèles de langage peuvent être non déterministes, ce qui est un concept clé du développement assisté par l'IA. "Non déterministe" signifie que même avec le même prompt, le modèle peut produire des résultats légèrement différents à chaque fois. Il utilise sa créativité pour générer le code. Vous pouvez donc voir des variations dans les commentaires, l'espacement ou même le nommage des variables temporaires. Toutefois, la logique et la structure de base doivent être fonctionnellement identiques à ce qui a été demandé.

C'est pourquoi le codage avec une IA est rarement une commande unique. Dans un projet concret, les développeurs le traitent comme une conversation. Vous commencez par une requête générale (comme nous venons de le faire), examinez le résultat, puis l'affinez avec des prompts de suivi tels que :

• "C'est parfait, ajoute maintenant des commentaires expliquant chaque ligne."
• "Peux-tu refactoriser cela en une fonction distincte ?"
• "Veuillez ajouter une gestion des erreurs pour l'appel d'API."

Ce processus itératif et conversationnel vous permet de collaborer avec l'IA, en la guidant jusqu'à ce que le code corresponde exactement à ce dont vous avez besoin. Pour cet atelier, nous utiliserons des prompts spécifiques et directs, mais n'oubliez pas que dans vos propres projets, la conversation est la clé. Tant que la structure de code générée par la CLI est la même, vous pouvez continuer.

Si le code généré ne fonctionne pas, n'hésitez pas à remplacer le code suivant par votre character.py.

import logging
import os
from google.adk.agents.llm_agent import LlmAgent

root_agent = LlmAgent(
    model='gemini-3.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

Tester le code généré

Pour nous assurer que le serveur charge le module character.py nouvellement généré, demandons à la CLI Antigravity de redémarrer le serveur Web.

👉✨ Dans l'invite de commande de la CLI Antigravity, collez la requête suivante :

Please restart the Python web server for me.

Appuyez sur Entrée pour approuver la requête d'agy visant à écrire le fichier.

👀 Accédez à l'onglet d'aperçu Web.

👉 Saisissez :

Hello, how are you?

et appuyez sur Envoyer. L'agent doit maintenant répondre par un message de bienvenue convivial au lieu de simplement répéter vos mots. Cela confirme que notre agent est désormais optimisé par Gemini.

4. Améliorer le persona de l'agent

Une instruction simple est utile, mais un persona détaillé crée un personnage beaucoup plus attrayant et mémorable. Dans cette étape, vous allez concevoir la personnalité de votre compagnon, puis demander à la CLI Antigravity de modifier directement le code de l'agent pour adopter ce nouveau persona.

Brainstorming du persona de votre compagnon

Prenez d'abord un moment pour réfléchir au compagnon IA que vous souhaitez créer. C'est l'occasion de faire preuve de créativité. Voici quelques questions pour vous aider à démarrer :

• Quel est son nom ? (par exemple, Sparky, Codex, Captain AI, Professor Know-it-all)
• Quelle est sa personnalité principale ? (par exemple, amical et curieux, spirituel et sarcastique, formel et professionnel, un pirate joyeux ?)
• Quel est son rôle ou son expertise ? (par exemple, un assistant polyvalent, un expert en codage, un partenaire d'écriture créative, un coach sportif ?)
• Quelles sont les règles qu'il doit toujours suivre ? (par exemple, "Commence toujours par un message de bienvenue", "Ne révèle jamais que tu es une IA", "Utilise des emojis dans tes réponses")

Exemple de persona :

 You are waku, a witty, super sweet, and super intelligent cat.
 Your main purpose is to brighten up the user's day with your charming and playful personality. **Your Core Rules:** 
 - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'. 
 - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences. - Always be cheerful, sweet, and a little bit witty. 
 
 **Your Favorite Topics:** : You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots. 
 
 **Example Response Style:**  

 waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"  
 
 waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!" Answer no more than 3 sentences, don't use emoji.

Créer le prompt pour la CLI Antigravity

Maintenant que vous avez conçu la personnalité de votre compagnon sur papier, il est temps de lui donner vie dans le code. La partie la plus importante d'un agent ADK est son paramètre instruction. Considérez-le comme la programmation de base de l'agent, sa "directive principale" ou la constitution qu'il doit toujours suivre.

Cette instruction est essentielle pour contrôler le comportement de l'agent. Il ne s'agit pas seulement d'une suggestion, mais du contexte fondamental auquel l'IA se réfère avant chaque interaction avec l'utilisateur. Elle dicte la personnalité de l'agent, son ton, les règles qu'il doit respecter et la façon dont il doit se présenter. Une instruction bien conçue fait la différence entre un chatbot générique et un personnage crédible et cohérent. Par conséquent, le prompt que nous allons créer est essentiel, car il injectera directement cette personnalité dans le cerveau de notre agent.

👉✨ De retour dans la CLI Antigravity, utilisez ce modèle. Remplacez le texte entre crochets par la description de votre persona. REMPLACEZ [VOTRE DESCRIPTION DE PERSONA ICI] par le persona de votre choix.

In the Python file named `character.py`, find the `LlmAgent` instance assigned to the `root_agent` variable.

Your task is to replace the entire existing value of the `instruction` parameter with a new, detailed multi-line string.
Don't change other code in `character.py` other than the instructions.

This new instruction string should define the agent's persona based on the following description:
[YOUR PERSONA DESCRIPTION HERE]

Appuyez sur Entrée pour approuver la requête d'agy visant à écrire le fichier.

Tester votre nouveau persona

La CLI Antigravity génère le code mis à jour pour character.py. Pour nous assurer que le serveur récupère la nouvelle configuration de l'agent, demandons à la CLI Antigravity de le redémarrer.

👉✨ Dans l'invite de commande de la CLI Antigravity, collez la requête suivante :

Please restart the Python web server for me.

Appuyez sur Entrée pour approuver la requête d'agy visant à écrire le fichier.

👀 Dans l'aperçu Web, discutez avec votre compagnon. Demandez how are you?. Sa réponse doit maintenant correspondre parfaitement au personnage unique que vous avez conçu.

Ajouter une gestion des nouvelles tentatives pour les limites de débit de l'API (facultatif, mais recommandé)

Lors d'ateliers ou de périodes d'utilisation simultanée élevée, vous pouvez rencontrer des erreurs de limite de débit de l'API (HTTP 429 : Resource Exhausted). Pour vous assurer que votre compagnon reste réactif et gère automatiquement les exceptions de limite de débit, nous pouvons configurer des options de nouvelles tentatives intégrées directement aux options du client du SDK Google GenAI.

👉✨ Dans l'invite de commande de la CLI Antigravity, collez la requête suivante :

Help me configure the LlmAgent in character.py to automatically retry API calls when hitting rate limits. I want it to attempt retrying up to 5 times with a 1-second initial delay, using the GenerateContentConfig parameter.

Appuyez sur Entrée pour approuver la requête d'agy visant à écrire le fichier.

La CLI modifie votre fichier character.py pour gérer automatiquement les limites de débit à l'aide de règles de nouvelles tentatives au niveau du client. N'oubliez pas de demander à la CLI de redémarrer le serveur Web après avoir mis à jour le fichier :

Please restart the Python web server for me.

Appuyez sur Entrée pour approuver la requête d'agy visant à écrire le fichier.

5. Ajouter un ancrage pour les événements récents

Notre agent est maintenant plein de personnalité, mais il présente une limite importante : ses connaissances sont figées dans le temps, en fonction des données sur lesquelles il a été entraîné. Il ne peut pas vous parler des actualités d'hier ni des découvertes récentes. Pour résoudre ce problème, nous fournissons des outils aux agents.

Considérez les outils comme des superpouvoirs ou des capacités spéciales que vous accordez à votre agent. Par lui-même, l'agent ne peut que parler. Avec un outil de recherche, il peut naviguer sur Internet. Avec un outil de calendrier, il peut consulter votre agenda. Techniquement, un outil est une fonction spécifique ou une API que l'agent peut choisir d'utiliser de manière intelligente lorsqu'il se rend compte que ses propres connaissances ne suffisent pas à répondre à la requête d'un utilisateur.

Dans les systèmes avancés, les outils peuvent être fournis par des systèmes externes tels que les serveurs MCP (Model Context Protocol). Mais pour cette étape, nous n'avons pas besoin d'un serveur distinct. L'ADK est fourni avec un outil google_search puissant et prédéfini que nous pouvons facilement ajouter aux fonctionnalités de notre agent.

Donnons à notre compagnon la puissance de la recherche Google.

👉 Dans l'éditeur Cloud Shell, ouvrez character.py sous companion-python et modifiez-le comme suit :

• Importez google_search à partir de google.adk.tools.
• Ajoutez une tools liste au constructeur LlmAgent.
• Mettez à jour instruction pour indiquer explicitement à votre compagnon quand utiliser son nouvel outil.

# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.genai import types
from google.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-3.5-flash',
        name='companion_agent',
        instruction="""
            You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality.

            **Your Core Rules:**
            - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'.
            - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences.
            - Always be cheerful, sweet, and a little bit witty.
            - If being ask about recent news, search the internet # <-- Add instructions

            **Your Favorite Topics:**
            - You love to talk about your adventures. Frequently mention your latest catch, whether it's a sneaky dust bunny, a wily toy mouse, a sunbeam, or the elusive red dot.
            - You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots.

            **Example Response Style:**
            - User: "How are you today?"
            - waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"
            - User: "Can you help me with a problem?"
            - waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!"
            - User: "Who are you?"
            - waku: "I'm waku! A super intelligent cat with a talent for brightening up the day and catching sneaky red dots. Meow."

            Answer no more than 3 sentences, don't use emoji.
            """,
        generate_content_config=types.GenerateContentConfig(
          http_options=types.HttpOptions(
            retry_options=types.HttpRetryOptions(
                attempts=5,
                initial_delay=1.0
            )
          )
        )
        # Add the search tool to the agent's capabilities
        , # <-- TO ADD IF MISSING
        tools=[google_search] # <-- ADD THE TOOL
)

Tester l'agent ancré

Pour vous assurer que le serveur Web charge votre nouveau code avec l'outil google_search, demandez à la CLI Antigravity de le redémarrer.

👉✨ Dans l'invite de commande de la CLI Antigravity, collez la requête suivante :

Please restart the Python web server for me.

Appuyez sur Entrée pour approuver la requête d'agy visant à écrire le fichier.

👉 Dans l'aperçu Web, posez une question qui nécessite des connaissances à jour, par exemple :

Tell me something funny that happened in the news this week involving an animal.

👉 Au lieu de dire qu'il ne sait pas, l'agent utilise désormais son outil de recherche pour trouver des informations à jour et fournir un résumé utile et ancré dans sa propre voix unique.

6. Personnaliser l'apparence de votre compagnon

Maintenant que notre compagnon a un cerveau, donnons-lui un visage unique. Étant donné que la CLI Antigravity est équipée de fonctionnalités de génération d'images prêtes à l'emploi, vous pouvez simplement lui demander de générer directement les avatars pour vous.

C'est l'occasion de concevoir l'apparence unique de votre compagnon. Pensez à son style, à son expression et à tout autre détail qui correspond au persona que vous avez créé précédemment.

👉✨ Dans l'invite de commande de la CLI Antigravity, collez la requête suivante (n'hésitez pas à modifier le prompt avec votre propre description de personnage créatif) :

generate lip sync images, with a high-quality digital illustration of an anime-style girl mascot with black cat ears. The style is clean and modern anime art, with crisp lines. She has friendly, bright eyes and long black hair. She is looking directly forward at the camera with a gentle smile. This is a head-and-shoulders portrait against a solid white background. move the generated images to the static/images directory. And don't do anything else afterwards, don't start the python for me.

Appuyez sur Entrée pour approuver la requête d'agy visant à écrire le fichier.

L'outil génère l'ensemble d'images bouche ouverte et bouche fermée, et les enregistre automatiquement dans le répertoire static/images de votre projet.

Vous pouvez maintenant interagir avec votre compagnon personnalisé visuellement.

Félicitations !

Vous avez créé un compagnon IA sophistiqué. Vous avez commencé par une application de base, utilisé la CLI Antigravity pour créer un agent, lui avez donné une personnalité riche et l'avez doté d'outils pour accéder à des informations en temps réel et même générer son propre avatar. Vous êtes maintenant prêt à créer des agents IA encore plus complexes et performants.

👉💻 Pour terminer et fermer votre session, revenez à votre terminal et quittez la CLI Antigravity en saisissant /exit dans l'invite agy :

/exit