+190 XP

Gemini · Les agents sur Google AI : l'Agent Development Kit

L'Agent Development Kit (ADK) de Google vous permet de construire des agents qui appellent des outils en boucle jusqu'à ce qu'une tâche soit réellement terminée, au lieu de renvoyer une seule réponse au jugé en espérant qu'elle tienne. Vous connaissez déjà le concept d'agent : un modèle capable de décider d'agir, d'observer les résultats, puis d'agir à nouveau. Cette leçon explique comment Google industrialise ce pattern, quand il justifie sa complexité, et comment en livrer un vrai.

Ce qu'est réellement ADK

ADK est un framework open source pour définir des agents en code. Le SDK Python est le plus mature, et il existe aussi des SDK pour Java, Go et TypeScript. C'est le même framework que celui qui fait tourner les produits agents de Google, comme Gemini Enterprise (le produit anciennement appelé Agentspace). Vous définissez un agent, vous lui donnez des outils, vous choisissez un modèle Gemini, et ADK exécute pour vous la boucle raisonner-agir-observer.

Les objets clés :

  • Agent : un modèle, des instructions et un ensemble d'outils.
  • Tool : une fonction Python (ou un outil intégré comme Google Search) que l'agent peut appeler.
  • Runner : le composant qui exécute la boucle et gère les sessions et l'état.

ADK accepte plusieurs modèles mais il est optimisé pour Gemini. Vous développez en local, vous testez dans une interface web intégrée, puis vous déployez sur Vertex AI Agent Engine, le runtime managé de Google Cloud pour les agents. Le code est le même en local et en production.

La place d'ADK par rapport au reste

Vous disposez de plusieurs façons de « faire des agents » sur Google AI, et ce sont moins des concurrents que des niveaux d'abstraction différents :

  • Gems dans l'application Gemini : des personas et des instructions enregistrés. Zéro code, pas de boucle d'outils.
  • Function calling de l'API Gemini : vous câblez la boucle vous-même.
  • ADK : la boucle, l'état, l'orchestration multi-agents et le déploiement sont gérés pour vous.
  • Vertex AI Agent Engine : là où les agents ADK tournent en production.

Si vous avez seulement besoin que le modèle appelle une fonction une fois, vous n'avez pas besoin d'ADK. Utilisez-le quand la tâche comporte plusieurs étapes.

Quand un agent fait mieux qu'un appel unique

Un appel Gemini unique (même avec function calling) est le bon outil quand le travail tient en une étape : classer cet e-mail, extraire ces champs, rédiger cette réponse. Le long contexte et la multimodalité native de Gemini permettent déjà de faire beaucoup en un seul appel.

Un agent se justifie quand le nombre d'étapes n'est pas connu à l'avance et dépend des résultats intermédiaires. Les signes que vous avez franchi cette limite :

  • Le modèle doit chercher, lire ce qu'il a trouvé, puis décider s'il cherche à nouveau.
  • L'entrée de chaque étape dépend de la sortie de l'étape précédente.
  • La tâche mobilise plusieurs outils (recherche, puis calculatrice, puis écriture en base de données).
  • Vous voulez que l'agent réessaie ou change de stratégie quand un outil échoue.

Une tâche du type « fais des recherches sur ce sujet et résume-les » est l'exemple canonique. Impossible de savoir à l'avance combien de recherches il faudra pour bien couvrir un sujet. L'agent en décide à l'exécution. Cette boucle dynamique, dépendante des données, est ce qu'un appel unique ne sait pas faire et ce qu'ADK est conçu pour gérer.

Le coût est réel : plus de latence, plus de tokens, plus de façons d'échouer. Utilisez un modèle Flash pour la boucle quand c'est possible (il est rapide et peu cher), réservez Pro aux étapes qui demandent un raisonnement poussé, et ne recourez jamais à un agent quand un seul appel structuré suffit.

Un agent concret de recherche et de synthèse

Construisons-en un. L'agent reçoit un sujet, utilise le grounding Google Search pour rassembler des informations à jour, boucle jusqu'à en avoir assez, puis rédige une synthèse structurée.

Commencez par préparer l'environnement. Il vous faut le SDK et une clé d'API Gemini depuis Google AI Studio (ou des identifiants Vertex AI si vous déployez sur le Cloud).

bash
pip install google-adk
export GOOGLE_API_KEY="your-key-here"
export GOOGLE_GENAI_USE_VERTEXAI=FALSE

Passons à l'agent. ADK fournit un outil intégré google_search qui ancre les réponses dans des résultats Google Search en direct, vous n'avez donc pas à coder vous-même la mécanique de recherche.

python
from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="research_summarizer",
    model="gemini-2.5-flash",
    description="Researches a topic and writes a sourced summary.",
    instruction=(
        "You are a research assistant. Given a topic, search for "
        "current, credible information. Run multiple searches if the "
        "first results are thin or one-sided. Stop when you can cover "
        "the topic accurately. Then write a summary with: a two-line "
        "overview, 3 to 5 key findings as bullets, and a 'Sources' "
        "list. Never state a fact you did not find in results."
    ),
    tools=[google_search],
)

La chaîne du modèle est la seule chose à modifier pour essayer un modèle plus récent. Les modèles de la famille Gemini 3 fonctionnent aussi ici ; consultez la page des modèles pour connaître les noms actuels avant d'en figer un en production.

C'est l'instruction qui fait l'essentiel du travail. Elle indique à l'agent *quand boucler* (« lance plusieurs recherches si les premiers résultats sont maigres ») et *quand s'arrêter* (« quand tu peux couvrir le sujet avec exactitude »). Des conditions d'arrêt floues sont la première cause d'agents qui bouclent indéfiniment ou abandonnent trop tôt.

L'exécuter en local

ADK vous donne une interface de développement pour observer la boucle, y compris chaque appel d'outil et le raisonnement du modèle entre les étapes. Depuis le dossier qui contient votre agent :

bash
adk web

Cela ouvre une interface locale dans le navigateur où vous saisissez un sujet et regardez l'agent chercher, observer, chercher à nouveau, puis rédiger. Voir les étapes intermédiaires, c'est ainsi que vous déboguez vos instructions. Si l'agent cherche une fois et s'arrête, votre condition d'arrêt est trop lâche. S'il cherche huit fois pour un sujet simple, resserrez-la.

Pour l'exécuter sans interface, ADK expose un `Runner` que vous pouvez appeler depuis votre propre code ou encapsuler dans une API.

Pourquoi le grounding compte ici

L'outil google_search fait plus qu'une simple recherche. C'est le grounding avec Google Search, qui injecte des résultats réels dans le modèle et renvoie les métadonnées des sources. Pour un agent de recherche, c'est la différence entre une synthèse assurée et une synthèse *exacte*. Sans grounding, le modèle écrit à partir de données d'entraînement qui ont une date limite. Avec, l'agent lit le web d'aujourd'hui. Appliquez toujours le grounding aux agents qui avancent des faits sur le monde actuel.

Ajouter un outil personnalisé

La recherche intégrée convient, mais les vrais agents ont besoin de *vos* outils : une fonction qui interroge votre base de données, publie sur Slack ou écrit dans une Google Sheet. Dans ADK, un outil est une fonction Python typée avec une docstring claire. La docstring s'adresse au modèle plus qu'à vous : c'est la description que le modèle lit pour décider quand l'appeler.

python
def save_summary(topic: str, summary: str) -> dict:
    """Saves a finished research summary to the team archive.

    Args:
        topic: The researched topic, used as the record title.
        summary: The full formatted summary text to store.

    Returns:
        A dict with 'status' and the saved record 'id'.
    """
    record_id = _write_to_store(topic, summary)
    return {"status": "ok", "id": record_id}

Ajoutez-la à la liste tools de l'agent, à côté de google_search. L'agent peut maintenant chercher *et* archiver dans une même boucle. Rédigez les docstrings d'outils comme si vous expliquiez la fonction à une nouvelle recrue brillante : ce qu'elle fait, ce que signifie chaque argument, ce qu'elle renvoie. Des docstrings bâclées amènent le modèle à appeler les outils au mauvais moment ou à leur passer des arguments absurdes.

Une contrainte à surveiller : les outils intégrés d'ADK comme google_search obéissent à des règles de combinaison avec les outils personnalisés qui varient selon le modèle. En cas de doute, répartissez les responsabilités entre plusieurs agents.

Multi-agents : quand une seule boucle ne suffit pas

La vraie puissance d'ADK apparaît avec les systèmes multi-agents : un agent coordinateur qui délègue à des sous-agents spécialisés. Dans notre exemple, vous pourriez avoir un agent researcher (recherche uniquement) et un agent writer (mise en forme et archivage), avec un coordinator qui fait le routage entre eux.

C'est important parce que chaque agent reste concentré. Un agent ciblé avec trois outils se comporte de façon bien plus fiable qu'un agent qui en jongle dix. Vous définissez les sous-agents et les confiez à un parent via le paramètre sub_agents ; le parent décide qui traite quoi. Commencez avec un seul agent, et ne découpez que lorsque ses instructions deviennent longues et pleines de conditions.

Vérification des acquis

1. Qu'est-ce qui distingue fondamentalement un agent (construit avec ADK) d'un appel Gemini unique avec function calling ?

2. D'après la leçon, quand un agent justifie-t-il vraiment sa complexité supplémentaire par rapport à un appel unique ?

3. Quel est le rôle de l'objet Runner dans ADK ?

CHOIX MULTIPLES

4. Sélectionnez TOUTES les affirmations qui décrivent correctement les différents « niveaux d'abstraction » pour faire des agents sur Google AI.

Sélectionnez toutes les réponses correctes.

CHOIX MULTIPLES

5. Sélectionnez TOUS les signes indiquant qu'une tâche a franchi la limite et nécessite un agent plutôt qu'un appel unique.

Sélectionnez toutes les réponses correctes.

Passer en production sur Vertex AI

Le adk web local sert à construire. La production, c'est Vertex AI Agent Engine, un service managé qui héberge votre agent, gère les sessions, assure la montée en charge et s'intègre au reste de Vertex AI. Le même code d'agent se déploie avec des modifications minimes ; vous passez essentiellement de l'authentification par clé d'API à l'authentification Vertex AI et vous pointez ADK vers votre projet Google Cloud.

Ce que vous gagnez en déployant sur Agent Engine plutôt que sur votre propre serveur :

  • Sessions et état managés : la mémoire de conversation persiste sans que vous ayez à construire une base de données pour cela.
  • Montée en charge et monitoring : l'agent tourne comme un endpoint managé avec une observabilité intégrée.
  • Contrôles entreprise : il vit dans votre projet Google Cloud, sous vos règles IAM et VPC, ce qui compte dès que l'agent touche des données internes.

Pour les agents qui agissent sur des données de l'entreprise, ce dernier point est la raison même d'être sur Vertex plutôt que d'appeler l'API Gemini brute depuis un script.

L'évaluation : l'étape qu'on saute

Un agent qui fonctionne en démo et un agent qui fonctionne sur des entrées réelles sont deux choses différentes. ADK intègre une capacité d'évaluation : vous définissez des cas de test (une entrée plus le comportement attendu ou la trajectoire d'outils attendue), et ADK exécute l'agent sur ces cas et note à la fois la réponse finale et *les outils appelés, dans quel ordre*.

Ce contrôle de trajectoire est propre aux agents et pèse lourd. Un appel unique s'évalue sur sa seule sortie. Un agent s'évalue aussi sur son *chemin*, car un agent qui obtient la bonne réponse par hasard (ou qui brûle vingt appels d'outils pour y arriver) n'est pas prêt pour la production. Construisez quelques cas d'évaluation avant de déployer, et relancez-les à chaque modification d'instruction.

Un modèle mental réaliste

Voyez ADK comme la couche qui transforme Gemini, de « un modèle capable de suggérer un appel d'outil » en « un processus qui mène une tâche à son terme ». Le modèle reste le cerveau. ADK, c'est la boucle, la mémoire, le routage, le déploiement et le harnais de test autour. Vous apportez des instructions précises (surtout les conditions d'arrêt), des outils bien décrits et des cas d'évaluation. ADK et Vertex s'occupent du reste.

Points clés

  • Ne recourez à un agent que lorsque les étapes sont dynamiques. Si le travail tient en une étape, utilisez un seul appel Gemini avec grounding. Les agents ajoutent de la latence, du coût et des modes de défaillance ; ils doivent se justifier.
  • Les conditions d'arrêt se trouvent dans l'instruction. La plupart des agents qui s'emballent ou qui bâclent se corrigent en disant explicitement au modèle quand continuer et quand terminer, pas en changeant de modèle.
  • Les docstrings d'outils sont des prompts. Le modèle choisit les outils et les arguments d'après la docstring. Rédigez chacune clairement, avec des arguments typés et une valeur de retour décrite.
  • Appliquez le grounding à tout ce qui est factuel avec l'outil intégré google_search, pour que les synthèses reflètent le web en direct et non la date limite d'entraînement.
  • Développez avec `adk web`, déployez sur Vertex AI Agent Engine, et conditionnez les déploiements aux évaluations ADK qui vérifient la trajectoire d'outils, pas seulement la réponse finale.

Questions fréquentes

Qu'est-ce que l'Agent Development Kit (ADK) de Google ?

ADK est le framework open source de Google pour construire des agents IA en code : vous définissez un agent (un modèle, des instructions et des outils), et ADK exécute la boucle raisonner-agir-observer, gère les sessions et l'état, et prend en charge le routage multi-agents. Le SDK Python est le plus mature, des versions Java, Go et TypeScript existent aussi. C'est le même framework qui fait tourner les produits d'agents de Google, comme Gemini Enterprise.

Quand ai-je réellement besoin d'un agent plutôt que d'un simple appel à Gemini ?

Un simple appel à Gemini suffit quand le travail tient en une étape : classer un e-mail, extraire des champs, rédiger une réponse. Passez à un agent quand le nombre d'étapes n'est pas connu à l'avance et que chaque étape dépend du résultat précédent, par exemple lancer une recherche, lire ce qui revient, puis décider s'il faut chercher à nouveau. Un agent coûte plus de latence, plus de tokens et multiplie les points de défaillance : cette complexité doit se justifier.

Quelle différence entre les Gems, le function calling de l'API Gemini, ADK et Vertex AI Agent Engine ?

Ce sont différents niveaux d'une même idée, pas des concurrents. Les Gems de l'application Gemini sont des personas enregistrées, sans code ni boucle d'outils ; le function calling de l'API Gemini permet au modèle de proposer un appel, mais c'est vous qui câblez la boucle ; ADK gère la boucle, l'état, l'orchestration multi-agents et le déploiement ; Vertex AI Agent Engine est le runtime managé de Google Cloud où les agents ADK tournent en production.

Comment empêcher un agent ADK de boucler indéfiniment ou de s'arrêter trop tôt ?

Corrigez la condition d'arrêt dans l'instruction, pas dans le modèle. Indiquez explicitement quand continuer et quand terminer, par exemple « lance plusieurs recherches si les premiers résultats sont maigres, arrête-toi quand tu peux traiter le sujet avec précision ». Faites tourner l'agent dans l'interface de développement locale avec `adk web` et observez les appels d'outils : une seule recherche puis arrêt signifie que la condition est trop lâche, huit recherches sur un sujet simple qu'elle est trop floue.

Comment ajouter mon propre outil à un agent ADK ?

Dans ADK, un outil est une fonction Python typée ajoutée à la liste `tools` de l'agent. La docstring s'adresse au modèle plus qu'à vous : c'est ce que le modèle lit pour décider quand appeler la fonction. Décrivez donc ce qu'elle fait, le sens de chaque argument et ce qu'elle renvoie. Des docstrings bâclées amènent le modèle à appeler les outils au mauvais moment ou à leur passer des arguments absurdes.

Comment évaluer un agent IA avant de le mettre en production ?

Évaluez le chemin, pas seulement la réponse. ADK intègre une fonction d'évaluation : vous définissez des cas de test avec une entrée et le comportement attendu ou la trajectoire d'outils attendue, puis ADK note à la fois la réponse finale et les outils appelés, dans quel ordre. Un agent qui tombe sur la bonne réponse par hasard, ou qui consomme vingt appels d'outils pour y arriver, n'est pas prêt pour la production. Construisez quelques cas d'évaluation avant de déployer et relancez-les après chaque modification d'instruction.