Atelier

Lesson 1 — Le cas d'usage et l'architecture

Le cas d'usage et l'architecture

4 min read

This content is not translated yet. Showing the original version.

Le cas d'usage et l'architecture

Le besoin

Une équipe produit veut chaque semaine une note courte : « Qu'est-ce qui a changé sur tel sujet ? ». Elle exige trois choses :

  1. des faits récents (le modèle seul s'arrête à sa date d'entraînement) ;
  2. des sources cliquables pour vérifier chaque point ;
  3. un format stable : synthèse, points clés, incertitudes.

L'ancrage consiste à appuyer la réponse du modèle sur des documents extérieurs. Avec l'outil intégré google_search, c'est Gemini qui décide de lancer des requêtes Google, lit les résultats et rédige sa réponse. Votre code ne fait aucune requête web : il reçoit la réponse et des métadonnées :

Champ de grounding_metadataContenu
web_search_queriesles requêtes réellement lancées
grounding_chunksles pages utilisées (web.title, web.uri)
grounding_supportsquels passages de la réponse s'appuient sur quelles pages
search_entry_pointun bloc HTML de suggestions de recherche à afficher (règles d'usage de Google)

Avec l'outil intégré google_search, qui exécute la recherche Google ?

La contrainte : un outil intégré ne se mélange pas librement

Notre agent a besoin de google_search et d'une fonction maison (date_du_jour). Or la documentation d'ADK (page « Tool limitations ») indique que certains outils intégrés, dont Google Search et l'exécution de code, ne peuvent pas être combinés avec d'autres outils dans un même agent. Nous l'avons vérifié avec ADK 2.10 et gemini-3.5-flash : l'API refuse la requête (leçon suivante, erreur 400 réelle).

La solution recommandée : plusieurs agents.

flowchart TB
  subgraph NON["Refusé par l'API"]
    A1["Un seul agent"] --> T1["google_search"]
    A1 --> T2["date_du_jour()"]
  end
  subgraph OUI["Notre architecture"]
    P["analyste_recherche"] --> F["date_du_jour()"]
    P --> AT["AgentTool(chercheur_web)"]
    AT --> CW["chercheur_web"]
    CW --> GS["google_search (seul)"]
  end

AgentTool emballe un agent pour qu'il apparaisse comme un outil fonction aux yeux de l'agent principal. L'agent principal ne voit donc que des fonctions : la contrainte est respectée.

Pourquoi AgentTool résout-il la contrainte ?

Le parcours d'une question

  1. L'agent principal appelle date_du_jour pour situer « dernières nouveautés ».
  2. Il découpe la question en 2 ou 3 sous-questions et appelle chercheur_web pour chacune.
  3. Un callback sur le chercheur relève les pages réellement utilisées, les numérote et les ajoute au texte renvoyé.
  4. L'agent principal rédige le rapport en citant les numéros [n].
  5. run.py ajoute la liste des sources depuis l'état de session : ce n'est pas le modèle qui écrit les URL.

Exercice : choisir l'architecture

Pour chacun de ces besoins, dites si un seul agent suffit ou s'il faut un sous-agent : (a) recherche web seule, réponse en texte ; (b) recherche web + enregistrement du rapport dans un fichier via une fonction ; (c) exécution de code seule sur des données fournies.

Voir la solution
  • (a) Un seul agent avec tools=[google_search].
  • (b) Sous-agent : la fonction d'enregistrement est un outil maison, elle ne peut pas cohabiter avec google_search. Agent principal avec [enregistrer_rapport, AgentTool(chercheur)]. Variante : enregistrer le fichier dans run.py, après l'agent, sans outil du tout.
  • (c) Un seul agent avec code_executor=BuiltInCodeExecutor() (voir le lab « Analyste de données CSV »).

Résultat obtenu

Premiers événements du run réel python run.py (gemini-3.5-flash, 2026-10-15) : l'agent principal appelle la fonction puis trois fois le sous-agent.

[outil] date_du_jour({})
[outil] chercheur_web({'request': 'Google Agent Development Kit ADK dernieres nouveautes annonces fonctionnalités'})
[outil] chercheur_web({'request': 'Google Agent Developer Kit ADK features updates Vertex AI Firebase'})
[outil] chercheur_web({'request': 'Google ADK Agent Development Kit documentation framework release notes'})

Je sais faire

  • Expliquer ce qu'est l'ancrage et ce que contiennent les métadonnées d'ancrage
  • Citer la contrainte des outils intégrés dans ADK
  • Dessiner une architecture agent principal + AgentTool + sous-agent de recherche
  • Expliquer pourquoi les URL viennent des métadonnées et pas du modèle
Next