ADK : des principes de base aux agents multi-outils

1. Introduction

En commençant par les bases et en progressant vers le développement d'agents multi-outils, cet atelier de programmation fournit une introduction complète à la création d'agents avec ADK.

Dans sa forme la plus simple, un agent IA est un système logiciel qui utilise un grand modèle de langage (LLM) comme "moteur de raisonnement" pour atteindre un objectif en effectuant de manière autonome une séquence de tâches.

Si un LLM est un consultant très compétent qui peut vous donner des conseils, un agent d'IA est un ingénieur proactif qui peut utiliser des outils pour exécuter ces conseils.

LLM vs agents

Le cerveau (LLM) : fournit des capacités de raisonnement, de planification et de compréhension du langage naturel. Il décide de ce qui doit être fait.

Les mains (outils) : il s'agit des API, des SDK et des fonctions personnalisées qui permettent à l'agent d'interagir avec le monde réel. Il exécute le plan.

Agent Development Kit (ADK)

Agent Development Kit (ADK) est un framework spécialisé conçu pour simplifier la création, le déploiement et l'orchestration des agents d'IA. Elle fournit les blocs de construction standardisés nécessaires pour transformer un grand modèle de langage statique en un agent dynamique capable d'exécuter du code, d'appeler des API et de gérer des workflows en plusieurs étapes.

Un agent multi-outils est un orchestrateur qui peut sélectionner et séquencer différentes fonctions spécialisées (comme un moteur de recherche, une base de données et une calculatrice) pour résoudre des problèmes complexes. Il détermine intelligemment l'outil à utiliser pour chaque étape et peut transmettre la sortie d'une action en tant qu'entrée pour la suivante afin d'atteindre un objectif final.

Ce que vous allez faire

Dans cet atelier de programmation, vous allez créer un agent "Conseils santé", un conseiller nutritionnel intelligent qui passe d'un simple raisonnement textuel à un outil multifonction puissant. Vous allez commencer par créer un agent conversationnel de base qui comprend les concepts de nutrition, puis vous l'équiperez progressivement d'un outil Storage SDK pour archiver les images d'ingrédients et d'un outil Vision pour "lire" et analyser ces images. À la fin de cet atelier, vous disposerez d'un orchestrateur entièrement fonctionnel capable de prendre une photo d'étiquette alimentaire importée, de la stocker dans un bucket cloud pour la conserver et de fournir immédiatement des "conseils santé" pour chaque ingrédient.

2. Prérequis

Un projet Google Cloud avec la facturation activée
Un navigateur Web

Créer un projet

Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

Activer Cloud Shell

Vous allez utiliser Cloud Shell, un environnement de ligne de commande exécuté dans la console Google Cloud et fourni avec les langages requis. Dans la console Cloud, cliquez sur Activer Cloud Shell en haut à droite :

Une fois connecté à Cloud Shell, vous êtes en principe authentifié, et le projet est défini sur votre ID de projet. Exécutez la commande suivante dans Cloud Shell pour vérifier que vous êtes authentifié :

gcloud auth list

Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet :

gcloud config list project

Si votre projet n'est pas défini, utilisez la commande suivante pour le définir :

gcloud config set project <YOUR_PROJECT_ID>

Consultez la documentation pour connaître les commandes gcloud ainsi que leur utilisation.

Ouvrir l'éditeur

Pour cet atelier de programmation, nous allons utiliser l'éditeur Cloud intégré. Dans la fenêtre Cloud Shell, cliquez sur le bouton "Ouvrir l'éditeur" en haut à droite. Un éditeur VSCode s'ouvre.

3. Configuration d'ADK

Passons au terminal Cloud Shell que nous avons activé dans la section précédente :

Créer et activer un environnement virtuel (recommandé)

À partir de votre terminal Cloud Shell, créez un environnement virtuel :

python -m venv .venv

Activez l'environnement virtuel :

source .venv/bin/activate

Installer ADK

pip install google-adk

4. Clé API Google

Créez une clé API Google à l'aide d'AI Studio :

Accédez à https://aistudio.google.com/, puis cliquez sur Get API Key dans le menu en bas à gauche.

Une fenêtre "Clés API" s'affiche. Cliquez sur "Créer une clé API" dans cette fenêtre :

Un pop-up s'affiche pour vous inviter à créer une clé. Nommez la clé : healthy-hints-key

Accédez au menu déroulant "Choisir un projet importé".

Cliquez sur Import Project. Une fenêtre latérale listant tous vos projets Google Cloud s'affiche. Sélectionnez celui sur lequel vous souhaitez travailler.

Cliquez sur "Importer".

Le menu déroulant est alors mis à jour pour refléter le projet que vous venez d'importer. Sélectionnez le projet dans le menu déroulant. Cliquez sur "Créer une clé". La liste des clés API créées s'affiche. Cliquez sur l'icône de copie de la clé API que vous venez de créer.

5. Exemple d'agent

Dans le terminal Cloud Shell, créez un répertoire racine pour votre agent à l'emplacement de votre choix dans le projet :

adk create healthy_hints

Vous pouvez choisir n'importe quel modèle, mais pour cet atelier de programmation, nous allons utiliser gemini-2.5-flash.

Pour cet atelier de programmation, nous utiliserons Google AI. Collez la clé API que vous avez créée à l'étape précédente.

Ouvrons le dossier que nous venons de créer. Dans le menu le plus à gauche, cliquez sur l'icône , puis sur Fichier > Ouvrir le dossier. Sélectionnez le dossier healthy_hints qui vient d'être créé. Il se trouve généralement dans le dossier /home/<username>.
La structure du dossier healthy_hints se présente généralement comme suit :

Vous verrez un fichier .env contenant votre clé API Google. Vous pouvez utiliser ce fichier pour définir n'importe quelle variable d'environnement.
Un autre fichier nommé agent.py est également créé. Il s'agit de notre fichier d'agent principal. C'est là qu'un exemple d'agent racine est créé. Examinons de près le contenu de ce fichier. Nous importons d'abord llm_agent depuis ADK. Nous utilisons ensuite le DSL ADK pour créer l'agent racine. Nous spécifions le nom du modèle comme Gemini-2.5-flash, nommons l'agent et fournissons une description détaillée. L'instruction est l'élément le plus important. C'est là que nous indiquons à l'agent ce qu'il doit faire en langage naturel.
Cet exemple d'agent est assez générique. Il répondra simplement à toutes les questions des utilisateurs.
Exécutons maintenant cet agent en local. Vous pouvez interagir avec cet agent de deux manières : via l'interface de ligne de commande (CLI) et via le Web.
CLI : exécutez la commande suivante en dehors du répertoire healthy_hints.

adk run healthy_hints

Si vous vous trouvez dans le répertoire healthy_hints, exécutez la commande suivante :

adk run .

Un résultat semblable à celui-ci s'affiche :

N'hésitez pas à écrire "bonjour" ou toute autre question. La réponse peut être différente pour chacun, c'est la nature de l'IA générative.

Web : exécutez la commande suivante à partir du répertoire parent de healthy_hints :

adk web

6. Agent multi-outils

Un outil est un élément de code modulaire (généralement une fonction ou une API) qui permet à un agent d'interagir avec le monde au-delà de ses connaissances internes.

Types d'outils dans ADK

Outils de fonction : logique personnalisée que vous écrivez vous-même. Par exemple, une fonction qui se connecte à votre base de données spécifique ou un "analyseur de journaux" personnalisé pour le format unique de votre entreprise.
Outils intégrés : fonctionnalités prêtes à l'emploi fournies par Google ou ADK, telles que la recherche Google, l'interpréteur de code ou le moteur RAG Google.
Agents-as-Tools: : dans les systèmes avancés "Multi-tool" ou "Multi-agent", un agent spécialisé peut servir d'outil à un autre. Par exemple, un "Agent de recherche" peut être un outil utilisé par un "Agent de gestion de la recherche".

Dans cet atelier de programmation, nous allons aborder les outils de fonction. Maintenant, faisons progresser notre agent et rendons-le polyvalent.

Ajoutons une méthode get_weather dans agent.py.

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

Modifions le fichier agent.py et changeons le nom, la description et les instructions de l'agent :

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

Jusqu'à présent, nous n'avons créé qu'un seul outil. Créons maintenant plusieurs outils :

Créons une autre méthode appelée get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

Modifions également notre agent pour qu'il appelle cet outil :

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

Nous avons modifié la description, les instructions et les outils en conséquence. Maintenant, exécutons cet agent mis à jour. Cette fois, l'agent répondra en indiquant l'heure et la météo actuelles.

7. Intégration d'un SDK

Maintenant que nous savons comment utiliser plusieurs outils. Prenons quelques exemples concrets. Créons un agent de conseils pour la santé. Notre objectif est d'importer une image contenant une liste d'ingrédients dans notre agent. Celui-ci nous indiquera ensuite si chaque ingrédient est sain ou non.

Commençons par créer un bucket dans Google Cloud Storage pour importer l'image. Ouvrez un nouvel onglet et accédez à https://console.cloud.google.com/. Dans la barre de recherche, saisissez "cloud storage". Sélectionnez ensuite Cloud Storage sous "Produits et pages" :

Vous êtes alors redirigé vers la page de présentation de Google Cloud Storage. Cliquez sur le bouton Create bucket. Sur la page de création du bucket, saisissez son nom. Le nom peut être n'importe quel élément, mais pour cet atelier de programmation, nous allons le définir sur healthy-hints-bucket-kolkata . Conservez les autres valeurs par défaut, puis cliquez sur le bouton Create.

Créons un fichier nommé requirements.txt et ajoutons-y google-cloud-storage. Nous allons utiliser le SDK Storage Python pour importer l'image dans Storage.

Commençons par installer les dépendances :

pip install -r requirements.txt

Vous devrez peut-être commencer par activer l'API Storage. Pour ce faire, exécutez la commande suivante dans votre terminal :

gcloud services enable storage.googleapis.com

Ajoutons à présent un nouvel outil pour importer l'image.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

Mettons à jour notre agent pour qu'il utilise le nouvel outil :

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

Nous allons maintenant ajouter un autre outil pour lire les ingrédients de l'image. Ajoutons google-cloud-vision dans requirements.txt et installons la nouvelle dépendance.

pip install -r requirements.txt

Là encore, vous devrez peut-être activer l'API Vision au préalable. Pour ce faire, exécutez la commande suivante dans votre terminal :

gcloud services enable vision.googleapis.com

Ajoutons maintenant un outil read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

Mettons à jour notre agent pour qu'il utilise cet outil.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. Conclusion

Félicitations, vous avez terminé l'atelier de programmation "Conseils pour une vie saine" ! Vous avez réussi à transformer une IA standard de générateur de texte en agent multitâche proactif. En utilisant l'ADK pour intégrer l'API Vision et le SDK Cloud Storage, vous avez donné à votre agent les "yeux" pour lire les étiquettes et la "mémoire" pour les archiver. Vous avez vu comment l'agent décide de manière autonome quand enregistrer un fichier et comment interpréter des données brutes pour fournir des conseils de santé concrets.

À l'avenir, ces principes serviront de modèle pour tout système automatisé. Que vous gériez une infrastructure cloud ou que vous créiez des assistants personnels, le principe de base reste le même : définir des outils spécialisés et laisser l'agent orchestrer la logique. Ensuite, essayez d'ajouter d'autres outils, comme une "base de données nutritionnelles" ou un "outil d'e-mailing", pour étendre l'impact de votre agent.