Cette page a été traduite par l'API Cloud Translation.

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 du Google Agent Development Kit (ADK).

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 prochaines parties de cette série, à mesure que nous la transformerons en un système multi-agent (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.

Prérequis

Comprendre les concepts de l'IA générative
Maîtrise de base 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 esprit curieux et une soif d'apprendre

Utiliser un compte de facturation d'essai

Pour suivre cet atelier de programmation, vous avez également besoin d'un compte de facturation Google Cloud actif. Si vous n'en avez pas encore, suivez ces étapes pour utiliser un compte de facturation test :

Ouvrez une fenêtre de navigation privée dans votre navigateur.
Accédez à ce portail d'échange.
Connectez-vous avec votre compte Gmail personnel.
Suivez les instructions détaillées du portail.

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

Commencez par créer un projet Google Cloud pour que les activités de cet atelier de programmation soient isolées dans ce nouveau projet uniquement.

Accédez à console.cloud.google.com/projectcreate.
Saisissez les informations requises :

Nom du projet : vous pouvez saisir le nom de votre choix (par exemple, "genai-workshop").
Emplacement : laissez la valeur Aucune organisation.
Compte de facturation : si cette option s'affiche, sélectionnez Compte de facturation d'essai de Google Cloud Platform. Ne vous inquiétez pas si cette option ne s'affiche pas. Passez simplement à l'étape suivante.

Notez l'ID du projet généré, car vous en aurez besoin plus tard.

Si tout est correct, cliquez sur le bouton Créer.

Configurer Cloud Shell

Une fois votre projet créé, suivez les étapes ci-dessous pour configurer Cloud Shell.

1. Lancer Cloud Shell

Accédez à shell.cloud.google.com et, si un pop-up vous demande d'autoriser, cliquez sur Autoriser.

2. Définir un ID de projet

Exécutez la commande suivante dans le terminal Cloud Shell pour définir le bon Project ID. Remplacez <your-project-id> par l'ID de projet que vous avez copié lors de la création du projet ci-dessus.

gcloud config set project <your-project-id>

Vous devriez maintenant voir que le bon projet est sélectionné dans le terminal Cloud Shell. L'ID de projet sélectionné est mis en évidence en jaune.

3. Activer les API requises

Pour utiliser les services Google Cloud, vous devez d'abord activer leurs API respectives pour votre projet. Exécutez les commandes ci-dessous dans le terminal Cloud Shell pour activer les services de 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 isole les dépendances du projet, ce qui évite les conflits avec d'autres projets ou les packages Python globaux du système.

1. Créez un répertoire de projet et accédez-y :

mkdir ai-agents-adk
cd ai-agents-adk

2. Créez et activez un environnement virtuel :

uv venv --python 3.12
source .venv/bin/activate

Le préfixe (ai-agents-adk) s'affiche devant l'invite du terminal, ce qui indique que l'environnement virtuel est actif.

3. Page d'installation d'ADK

uv pip install google-adk

5. Créer un agent

Maintenant que votre environnement est prêt, il est temps de créer la base de votre agent d'IA. L'ADK nécessite quelques fichiers pour définir la logique et la configuration de votre agent :

agent.py : contient le code Python principal de votre agent, qui définit son nom, le LLM qu'il utilise et les instructions de base.
__init__.py : marque le répertoire comme package Python, ce qui aide l'ADK à découvrir et à charger la définition de votre agent.
.env : stocke les informations sensibles et les variables de configuration telles que la clé API, l'ID du projet et l'emplacement.

Cette commande crée un répertoire nommé personal_assistant contenant les trois fichiers essentiels.

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

Ensuite, vous devez vérifier que l'ID de projet indiqué entre crochets [...] est correctement défini. Si c'est le cas, appuyez sur Entrée. Si ce n'est pas le cas, saisissez l'ID de projet correct dans l'invite suivante :

Enter Google Cloud project ID [your-project-id]:

Enfin, appuyez sur Entrée à la question suivante pour utiliser us-central1 comme région pour cet atelier de programmation.

Enter Google Cloud region [us-central1]:

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

6. Explorer les codes d'agent

Pour afficher les fichiers créés, ouvrez le dossier ai-agents-adk dans l'éditeur Cloud Shell.

Cliquez sur Fichier > Ouvrir le dossier… dans le menu du haut.
Recherchez et sélectionnez le dossier ai-agents-adk.
Cliquez sur OK.

Si la barre de menu supérieure ne s'affiche pas, vous pouvez également cliquer sur l'icône des dossiers et sélectionner Ouvrir un dossier.

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

Le fichier .env est souvent masqué par défaut. Pour le rendre visible dans l'éditeur Cloud Shell :

accédez à la barre de menu en haut de l'écran ;
cliquez sur Afficher.
Sélectionnez Afficher/Masquer les fichiers cachés.

Explorez 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="root_agent" : 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 de l'emplacement approprié permet à votre agent de communiquer efficacement avec les services Vertex AI de cette région.

7. 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, exécutez la commande adk run suivante dans le terminal :

adk run personal_assistant

Si tout est configuré correctement, un résultat semblable s'affichera dans votre terminal. Ne vous inquiétez pas des avertissements pour le moment. Tant que vous voyez [user]:, vous pouvez continuer.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

N'hésitez pas à discuter avec l'agent. Saisissez par exemple "bonjour. Que peux-tu faire pour moi ?" et vous devriez recevoir une réponse.

...
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:
...

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.

Dépannage

Cette méthode API requiert l'activation de la facturation.

Si vous recevez le message {‘message': ‘This API method requires billing to be enabled'}, procédez comme suit :

Vérifiez que vous utilisez le bon ID de projet dans le fichier .env.
Accédez à la page Compte de facturation associé et vérifiez si le compte de facturation est déjà associé.
Si ce n'est pas le cas, sélectionnez Compte de facturation d'essai Google Cloud Platform dans les options.

L'API Vertex AI n'a pas été utilisée dans le projet

Si vous recevez un message d'erreur contenant {'message': 'Vertex AI API has not been used in project...'}, activez l'API Vertex AI en saisissant la commande suivante dans le terminal :

gcloud services enable aiplatform.googleapis.com

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

Autres erreurs

Si vous recevez d'autres erreurs qui ne sont pas mentionnées ci-dessus, essayez de recharger l'onglet Cloud Shell dans le navigateur (et réautorisez si vous y êtes invité).

8. Exécuter l'agent sur l'interface utilisateur Web de développement

L'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 votre terminal exécute toujours adk run, saisissez "exit" pour le fermer avant de saisir cette commande :

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)

Vous disposez de deux options pour accéder à l'UI de développement :

Ouvrir via Terminal

Ctrl+clic ou Cmd+clic sur le lien (par exemple, http://localhost:8000), comme indiqué dans le terminal.

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 !

9. Nettoyer (facultatif)

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 ou Cmd+C dans le terminal.

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.

10. Conclusion

Félicitations ! Vous avez créé un agent d'assistant personnel simple à l'aide d'Agent Development Kit (ADK). Vous disposez désormais d'une base solide et d'une bonne compréhension des composants principaux d'un agent ADK.

Dans une prochaine étape, vous pouvez étendre considérablement les capacités de votre agent en lui fournissant des outils pour accéder à des informations en temps réel et interagir avec des services externes. Si vous souhaitez poursuivre votre parcours, le prochain atelier de programmation de cette série, Créer des agents d'IA avec l'ADK : s'outiller pour l'avenir, vous guidera tout au long de ce processus.