Créer des agents IA avec ADK : les bases

1. Avant de commencer

Bienvenue dans la première partie de la série "Créer des agents d'IA avec ADK" ! Dans cette série d'ateliers de programmation pratiques, vous allez vous lancer dans un voyage passionnant pour créer votre propre agent d'IA intelligent à l'aide de l'Agent Development Kit (ADK) de Google.

Nous commencerons par les bases absolues, en vous guidant dans la configuration de votre environnement de développement et la création d'un agent conversationnel de base. À la fin de cet atelier de programmation, vous aurez créé votre première IA interactive, prête à être développée dans les parties suivantes de cette série, à mesure que nous la transformerons en un système multi-agents (SMA) sophistiqué.

Vous pouvez effectuer cet atelier de programmation dans votre environnement local ou sur Google Cloud. Pour une expérience optimale, nous vous recommandons d'utiliser Cloud Shell depuis l'environnement Google Cloud. Cloud Shell fournit également 5 Go de stockage persistant dans le répertoire $HOME. Cela est utile pour stocker des scripts, des fichiers de configuration ou des dépôts clonés.

Remarque : Si vous choisissez de travailler en local, vous devrez peut-être effectuer des étapes de configuration, d'installation et d'authentification supplémentaires, qui ne sont pas abordées dans la section de configuration de l'environnement de cet atelier.

Prérequis

• Comprendre les concepts de l'IA générative
• Maîtrise des bases de la programmation Python
• Vous maîtrisez la ligne de commande / le terminal.

Points abordés

• Configurer un environnement Python
• Créer un agent d'assistant personnel simple à l'aide d'ADK
• Exécuter, tester et déboguer l'agent

Prérequis

• Un ordinateur qui fonctionne et un réseau Wi-Fi fiable
• Un navigateur, tel que Chrome, pour accéder à la console Google Cloud
• Un projet Google Cloud avec facturation activée
• Un esprit curieux et une soif d'apprendre

2. Introduction

Le monde de l'IA générative évolue rapidement, et les agents d'IA sont actuellement un sujet brûlant. Un agent d'IA est un programme informatique intelligent conçu pour agir en votre nom, un peu comme un assistant personnel. Elle peut percevoir son environnement numérique, prendre des décisions et agir pour atteindre des objectifs spécifiques sans contrôle humain direct. Considérez-le comme une entité proactive et autonome, capable d'apprendre et de s'adapter pour accomplir des tâches.

Fondamentalement, un agent d'IA utilise un grand modèle de langage (LLM) comme "cerveau" pour comprendre et raisonner. Cela lui permet de traiter des informations provenant de diverses sources, comme du texte, des images et des sons. L'agent utilise ensuite cette compréhension pour créer un plan et exécuter une série de tâches afin d'atteindre un objectif prédéfini.

Vous pouvez désormais créer facilement vos propres agents IA, même sans expertise approfondie, grâce à des frameworks prêts à l'emploi comme Agent Development Kit (ADK). Nous allons commencer ce parcours en construisant un agent d'assistant personnel pour vous aider dans vos tâches. C'est parti !

3. Configurer les services Google Cloud

Créer un projet Google Cloud

Cet atelier de programmation part du principe que vous avez déjà créé un projet Google Cloud pour lequel la facturation est activée. Si vous n'avez pas encore de projet, suivez ces étapes pour en créer un :

Sélectionner ou créer un projet Google Cloud

• Accédez à la console Google Cloud.
• En haut de l'écran, cliquez sur le menu déroulant du sélecteur de projet (à côté du logo Google Cloud).
• Sélectionnez un projet existant ou créez-en un.

Activer la facturation

• Assurez-vous que la facturation est activée pour le projet Google Cloud sélectionné.
• Pour savoir comment vérifier si la facturation est activée sur un projet, suivez les instructions de la documentation Google Cloud Billing.

Remarque : La facturation doit être activée même pour les services de la version sans frais, car c'est le mécanisme utilisé par Google Cloud pour suivre l'utilisation des ressources. Cela dit, vous ne serez facturé que si votre utilisation dépasse les limites du forfait sans frais ou si vous utilisez des services payants.

Configurer Cloud Shell

Assurons-nous maintenant que vous êtes correctement configuré dans Cloud Shell, une interface de ligne de commande pratique directement dans la console Google Cloud.

Lancer Cloud Shell

En haut à droite de la console Google Cloud, vous verrez une icône en forme de terminal (>_). Cliquez dessus pour activer Cloud Shell.

Autoriser l'accès

Si vous y êtes invité, cliquez sur Autoriser pour accorder à Cloud Shell les autorisations nécessaires pour interagir avec votre projet Google Cloud.

Valider votre compte :

Une fois Cloud Shell chargé, vérifions que vous utilisez le bon compte Google Cloud. Exécutez la commande suivante :

gcloud auth list

Le résultat de la commande doit ressembler à ce qui suit dans le terminal :

Credentialed Accounts

ACTIVE: *
ACCOUNT: [e-mail]

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Changer de compte (si nécessaire) :

Si le compte actif n'est pas celui que vous souhaitez utiliser pour cet atelier de programmation, passez au bon compte à l'aide de cette commande, en remplaçant <[e-mail]> par l'adresse e-mail que vous utiliserez pour cet atelier :

gcloud config set account <[e-mail]

Confirmer votre projet

Ensuite, vérifions que Cloud Shell est configuré pour utiliser le bon projet Google Cloud. Exécutez la commande suivante :

gcloud config list project

Une liste de configurations s'affiche. Recherchez la section [core] et assurez-vous que la valeur du projet correspond à l'ID du projet Google Cloud que vous souhaitez utiliser pour cet atelier de programmation :

[core]
project = <current-project-id>

Définir votre projet (si nécessaire)

Si la valeur project ID est incorrecte, définissez-la sur le projet de votre choix à l'aide de la commande suivante :

gcloud config set project <your-desired-project-id>

Activer les API requises

Pour utiliser les services Google Cloud, vous devez d'abord activer leurs API respectives pour votre projet. L'exécution des commandes ci-dessous dans le terminal Cloud Shell permet d'activer tous les services dont vous aurez besoin pour cet atelier de programmation :

gcloud services enable aiplatform.googleapis.com

Si l'opération a abouti, Operation/... finished successfully s'affiche dans votre terminal.

4. Créez un environnement virtuel Python

Avant de commencer un projet Python, il est recommandé de créer un environnement virtuel. Cela permet d'isoler les dépendances du projet, ce qui évite les conflits avec d'autres projets ou les packages Python globaux du système. Étant donné que l'Agent Development Kit (ADK) nécessite Python 3.9 ou une version ultérieure, nous utiliserons un outil tel que uv pour gérer l'environnement virtuel et nous assurer que la bonne version de Python est utilisée.

uv est un outil moderne, rapide et efficace pour gérer les projets et les environnements Python. Il combine des fonctionnalités que l'on trouve habituellement dans des outils tels que pip, venv, pip-tools et pipx. Il est écrit en Rust pour plus de rapidité.

uv est déjà disponible dans Cloud Shell. Nous pouvons donc commencer immédiatement.

Vérifier si uv est correctement installé

uv --version

Créer un dossier de projet pour votre agent IA

uv init ai-agents-adk
cd ai-agents-adk

Créer un environnement virtuel avec Python 3.12

uv venv --python 3.12

Installez la bibliothèque Google ADK dans votre environnement virtuel.

uv add google-adk

Vérifier si vous avez bien installé le package google-adk

uv pip list | grep google-adk

Si une ligne de résultat avec google-adk et sa version s'affiche, vous pouvez passer à l'étape suivante.

5. Créer un agent

Maintenant que votre environnement de développement est configuré et prêt, il est temps de poser les bases de votre agent d'IA. Le kit de développement d'agent (ADK) simplifie ce processus, en ne nécessitant que quelques fichiers essentiels pour définir la logique et la configuration de base de votre agent.

Ces trois fichiers fonctionnent ensemble pour rendre votre agent détectable, exécutable et configurable :

• agent.py : il s'agit du cœur de votre agent. Il contient le code Python principal qui définit le comportement de votre agent, y compris son nom, le grand modèle de langage (LLM) qu'il utilise comme "cerveau" et les instructions de base qui guident ses réponses.
• __init__.py : en Python, le fichier __init__.py marque un répertoire comme package Python. Pour l'ADK, c'est essentiel, car cela aide le framework à découvrir et à charger la définition de votre agent à partir de agent.py. Dans les projets ADK simples, il contient souvent une seule ligne pour importer votre module agent, ce qui rend votre agent accessible au programme d'exécution ADK.
• .env : ce fichier (abréviation de "environnement") est utilisé pour stocker les informations sensibles et les variables de configuration dont votre agent a besoin, telles que les clés API, les ID de projet et les zones géographiques. Il est recommandé de conserver ces informations dans un fichier .env distinct pour des raisons de sécurité et de portabilité, car cela évite de coder en dur les données sensibles directement dans votre code. Il vous permet également de modifier facilement les configurations sans modifier la logique principale de votre agent.

Utilisez les commandes ci-dessous pour créer ces fichiers dans un dossier dédié à votre agent d'assistant personnel :

uv run adk create personal_assistant

Une fois la commande exécutée, vous serez invité à choisir quelques options pour configurer votre agent. Pour la première étape, choisissez l'option 1 pour utiliser le modèle gemini-2.5-flash, un modèle rapide et efficace, idéal pour les tâches conversationnelles.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

Pour la deuxième étape, choisissez Vertex AI (option 2), la plate-forme d'IA gérée et performante de Google Cloud, comme fournisseur de services backend.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

Enfin, vous serez invité à confirmer l'ID et la région de votre projet Google Cloud. Si vous souhaitez utiliser les valeurs préremplies (current-project-id et current-region), appuyez simplement sur Entrée pour chaque question.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

Un résultat semblable devrait s'afficher dans votre terminal.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

Cliquez ensuite sur le bouton Ouvrir l'éditeur en haut de la fenêtre Cloud Shell. En cliquant sur ce bouton, vous serez redirigé vers la fenêtre de l'éditeur, qui vous permettra d'explorer plus facilement le contenu de vos fichiers. Le changement peut prendre un certain temps. Si vous êtes bloqué sur un écran de chargement pendant plus de quelques minutes, essayez d'actualiser votre navigateur.

Remarque : Vous pouvez utiliser un éditeur de ligne de commande comme Vim, mais vous devrez connaître les commandes pour ouvrir et quitter Vim par vous-même.

Une fois la fenêtre de l'éditeur entièrement chargée, accédez au dossier personal-assistant. Vous verrez les fichiers nécessaires mentionnés ci-dessus (agent.py, __init__.py et .env). Examinons leur contenu.

Si vous ne voyez pas le fichier .env dans le dossier, accédez à la barre de menu en haut de l'écran, cliquez sur "Affichage", puis sélectionnez Afficher/Masquer les fichiers cachés. Il s'agit d'un paramètre courant, car les fichiers .env sont souvent masqués par défaut pour éviter toute exposition accidentelle.

Examinons le contenu de chaque fichier.

agent.py

Ce fichier instancie votre agent à l'aide de la classe Agent de la bibliothèque google.adk.agents.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents import Agent : cette ligne importe la classe Agent nécessaire à partir de la bibliothèque ADK.
• root_agent = Agent(...) : vous créez ici une instance de votre agent d'IA.
• name="personal_assistant" : identifiant unique de votre agent. C'est ainsi que l'ADK reconnaîtra votre agent et le désignera.
• model="gemini-2.5-flash" : ce paramètre essentiel spécifie le grand modèle de langage (LLM) que votre agent utilisera comme "cerveau" sous-jacent pour comprendre, raisonner et générer des réponses. gemini-2.5-flash est un modèle rapide et efficace adapté aux tâches conversationnelles.
• description="..." : fournit un résumé concis de l'objectif ou des capacités de l'agent. La description est plutôt destinée à la compréhension humaine ou à d'autres agents d'un système multi-agent pour comprendre ce que fait cet agent particulier. Il est souvent utilisé pour la journalisation, le débogage ou l'affichage d'informations sur l'agent.
• instruction="..." : il s'agit de l'invite système qui guide le comportement de votre agent et définit sa personnalité. Elle indique au LLM comment il doit agir et quel est son objectif principal. Dans ce cas, elle définit l'agent comme un "assistant utile". Cette instruction est essentielle pour définir le style et les capacités conversationnelles de l'agent.

init.py

Ce fichier est nécessaire pour que Python reconnaisse personal-assistant comme un package, ce qui permet à ADK d'importer correctement votre fichier agent.py.

from . import agent

• from . import agent : cette ligne effectue une importation relative, indiquant à Python de rechercher un module nommé agent (qui correspond à agent.py) dans le package actuel (personal-assistant). Cette simple ligne garantit que lorsque l'ADK tente de charger votre agent personal-assistant, il peut trouver et initialiser le root_agent défini dans agent.py. Même s'il est vide, c'est la présence de __init__.py qui fait du répertoire un package Python.

.env

Ce fichier contient des configurations spécifiques à l'environnement et des identifiants sensibles.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

• GOOGLE_GENAI_USE_VERTEXAI : indique à l'ADK que vous avez l'intention d'utiliser le service Vertex AI de Google pour vos opérations d'IA générative. Cela est important pour exploiter les services gérés et les modèles avancés de Google Cloud.
• GOOGLE_CLOUD_PROJECT : cette variable contiendra l'identifiant unique de votre projet Google Cloud. L'ADK en a besoin pour associer correctement votre agent à vos ressources cloud et pour activer la facturation.
• GOOGLE_CLOUD_LOCATION : spécifie la région Google Cloud dans laquelle se trouvent vos ressources Vertex AI (par exemple, us-central1). L'utilisation du bon emplacement permet à votre agent de communiquer efficacement avec les services Vertex AI de cette région.

6. Exécuter l'agent sur le terminal

Une fois les trois fichiers en place, vous êtes prêt à exécuter l'agent directement depuis le terminal. Pour ce faire, vous devez ouvrir la fenêtre Terminal. Cliquez sur Terminal dans la barre de menu, puis sélectionnez Nouveau terminal.

Une fois le terminal disponible, vous pouvez démarrer l'agent à l'aide de la commande adk run. Comme il s'agit d'une nouvelle fenêtre de terminal et que nous utilisons uv, vous devez d'abord accéder au dossier ai-agent-adk, puis ajouter le préfixe uv run à la commande adk run.

Saisissez les commandes suivantes dans le terminal :

cd ai-agents-adk
uv run adk run personal_assistant

Si tout est configuré correctement, un résultat semblable s'affiche dans votre terminal.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

N'hésitez pas à discuter avec l'agent. Vous remarquerez que la sortie est parfois mise en forme avec Markdown, ce qui peut être difficile à lire dans le terminal. À l'étape suivante, nous utiliserons l'UI de développement pour une expérience beaucoup plus riche, semblable à celle d'une application de chat.

7. Exécuter l'agent dans l'UI de développement

Agent Development Kit offre également un moyen pratique de lancer votre agent en tant qu'application de chat à l'aide de son interface utilisateur de développement. Utilisez simplement la commande adk web au lieu de adk run..

Si vous êtes toujours dans la session précédente, saisissez simplement exit dans le terminal pour la fermer. Une fois la session précédente fermée, saisissez la commande suivante dans le terminal :

uv run adk web

Un résultat semblable à celui-ci doit s'afficher dans le terminal :

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.

+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Deux options s'offrent à vous pour accéder à l'UI de développement :

1. Ouvrir via Terminal

• Ctrl+clic ou Cmd+clic sur les URL (par exemple, http://localhost:8000) à partir du terminal.

2. Ouvrir avec l'aperçu sur le Web

• Cliquez sur le bouton Aperçu sur le Web.
• Sélectionnez Modifier le port.
• Saisissez le numéro de port (par exemple, 8000)
• Cliquez sur Modifier et prévisualiser.

L'interface utilisateur de type application de chat s'affiche alors dans votre navigateur. N'hésitez pas à discuter avec votre assistant personnel via cette interface. Vous remarquerez que la mise en forme Markdown s'affiche désormais correctement. Cette UI vous permet également de déboguer et d'examiner chaque événement de messagerie, l'état de l'agent, les demandes des utilisateurs et bien plus encore. Bonnes discussions !

8. Effectuer un nettoyage

Comme cet atelier de programmation n'implique aucun produit à longue durée d'exécution, il suffit d'arrêter vos sessions d'agent actives (par exemple, l'instance adk web dans votre terminal) en appuyant sur Ctrl+C dans le terminal.

Attention : NE PASSEZ PAS à ces étapes si vous prévoyez de continuer la série d'ateliers de programmation, car vous devrez répéter certaines actions dans le prochain atelier.

Supprimer les dossiers et fichiers du projet d'agent

Si vous souhaitez uniquement supprimer le code de votre environnement Cloud Shell, utilisez les commandes suivantes :

cd ~
rm -rf ai-agents-adk

Désactiver l'API Vertex AI

Pour désactiver l'API Vertex AI que vous avez activée précédemment, exécutez la commande suivante :

gcloud services disable aiplatform.googleapis.com

Arrêter l'intégralité du projet Google Cloud

Si vous souhaitez arrêter complètement votre projet Google Cloud, consultez le guide officiel pour obtenir des instructions détaillées.

9. Conclusion

Félicitations ! Vous avez créé un agent d'assistant personnel simple à l'aide de l'Agent Development Kit (ADK).

Comme vous l'avez peut-être remarqué, cet agent d'assistance personnelle n'est pas encore très performant (par exemple, il ne peut pas accéder à Internet pour obtenir les dernières informations). Dans le prochain atelier de programmation de cette série "Créer des agents d'IA avec ADK", vous apprendrez à doter votre agent assistant personnel de fonctions et d'outils. À très bientôt !