L'agent ADK et sa sortie structurée

Première exécution réelle de l'évaluation, 20 h 48 : l'agent ne répond plus. Les journaux défilent : 112 appels à un outil Filtre et 73 à google:python_interpreter, deux outils qui n'existent pas. Le modèle avait reçu un paramètre filtres: list[Filtre] (des objets imbriqués) et s'était mis à « écrire du Python » au lieu d'appeler l'outil, en boucle, jusqu'au quota. Cette leçon construit l'agent et montre les trois réglages qui l'ont rendu fiable.

Le mécanisme : un outil, un format de sortie, deux bornes

flowchart TD
  Q["Question + historique de la conversation"] --> CB["before_agent_callback : tour_requetes = []"]
  CB --> M["Gemini 2.5 Flash<br/>instruction = méthode + catalogue + date du jour"]
  M -->|"appel d'outil"| T["interroger(métriques, dimensions, filtres texte, période, tri, limite, graphique)"]
  T -->|"ErreurSemantique / RequeteRefusee"| M
  T -->|"ok : extrait des lignes"| ST["state.tour_requetes += SQL, lignes, spec, coût"]
  ST --> M
  M -->|"set_model_response (output_schema)"| R["Reponse : reponse, limites[], suites[]"]
  M -.->|"max_llm_calls = 8"| X["arrêt propre : réponse d'échec"]

Le modèle ne renvoie jamais les données à l'interface. Les lignes, le SQL, la spécification du graphique et le coût vont dans l'état de session (tool_context.state), que l'API lit après le tour. Le texte du modèle ne sert qu'à commenter. Un chiffre inventé dans la phrase ne peut donc pas contaminer le tableau ni le graphique, qui viennent de BigQuery.

La mise en œuvre

L'outil : des paramètres plats

def interroger(
    metriques: list[str],
    tool_context: ToolContext,
    dimensions: Optional[list[str]] = None,
    filtres: Optional[list[str]] = None,          # « pays=France », « categorie!=Socks|Underwear »
    date_debut: Optional[str] = None,
    date_fin: Optional[str] = None,
    tri: Optional[str] = None,
    ordre: Literal["asc", "desc"] = "desc",
    limite: int = 100,
    graphique: Optional[Literal["nombre", "ligne", "barres", "lignes_multiples", "carte_chaleur"]] = None,
) -> dict:
    """Interroge les ventes via la couche sémantique et renvoie le résultat. ..."""

ADK construit la déclaration de fonction à partir de la signature et de la docstring. Avec list[Filtre] (un modèle Pydantic), la déclaration contenait un $defs et une référence $ref ; Gemini 2.5 Flash a répondu par des appels Filtre(...) séparés puis par du pseudo-code. Avec des chaînes dimension=valeur1|valeur2, analysées par Filtre.depuis_texte côté code, le même modèle produit du premier coup :

CALL interroger {"metriques": ["articles_vendus"], "filtres": ["categorie=Jeans", "pays=France"],
                 "date_debut": "2025-01-01", "date_fin": "2026-01-01", "dimensions": []}

Les erreurs de compilation et de garde-fou reviennent au modèle sous forme de {"statut": "refus", "erreur": "..."}. Le message contient la correction (« Valeurs exactes : ... | Brasil | ... »), ce qui suffit au modèle pour réessayer.

La sortie structurée

class Reponse(BaseModel):
    reponse: str = Field(description="Réponse en français, 2 à 5 phrases, chiffres arrondis et unités.")
    limites: list[str] = Field(description="1 à 3 limites ou précautions de lecture du résultat.")
    suites: list[str] = Field(description="3 questions de suite pertinentes, formulées comme l'utilisateur.")

Agent(name=APP, model=Gemini(model=config.MODEL, retry_options=types.HttpRetryOptions(initial_delay=2, attempts=5)),
      instruction=lambda ctx: instruction(), tools=[interroger], output_schema=Reponse,
      before_agent_callback=reinitialiser_tour,
      generate_content_config=types.GenerateContentConfig(temperature=0))

ADK 2.10 accepte output_schema avec des outils : il ajoute un outil interne set_model_response que le modèle appelle en dernier. L'interface reçoit un JSON validé ; les « questions de suite » deviennent des boutons sans analyse de texte fragile. instruction est une fonction pour que la date du jour soit recalculée à chaque tour (« le mois dernier » change le 1er du mois).

La conversation

Assistant.demander() réutilise la session ADK quand l'interface renvoie un conversation_id. Le modèle voit donc l'historique et comprend « Et par rayon, trimestre par trimestre ? » après une question sur le chiffre d'affaires mensuel (capture de la leçon suivante).

Lancez une question réelle en ligne de commande :

.venv/bin/python -m assistant.agent "Quel est le taux de retour au Brésil par rayon en 2025 ?"

Résultat obtenu le 2026-10-15 :

En 2025, le taux de retour au Brésil était de 28,4 % pour le rayon Femme et de 27,1 % pour le rayon Homme.

[barres] 2 lignes, 31.5 Mo facturés
SELECT
  p.department AS departement,
  SAFE_DIVIDE(COUNTIF(oi.status = 'Returned'), COUNTIF(oi.status IN ('Complete', 'Returned'))) AS taux_retour
FROM `bigquery-public-data.thelook_ecommerce.order_items` AS oi
LEFT JOIN `bigquery-public-data.thelook_ecommerce.products` AS p ON p.id = oi.product_id
LEFT JOIN `bigquery-public-data.thelook_ecommerce.users` AS u ON u.id = oi.user_id
WHERE oi.created_at < CURRENT_TIMESTAMP()
  AND oi.created_at >= TIMESTAMP(@date_debut)
  AND oi.created_at < TIMESTAMP(@date_fin)
  AND u.country IN UNNEST(@f0)
GROUP BY 1
ORDER BY taux_retour DESC
LIMIT 100

Limites :
- Le taux de retour est calculé sur les articles livrés (statut Complete + Returned), les commandes en cours ne sont pas prises en compte.
- Le Brésil est orthographié 'Brasil' dans les données.

« Brésil » est devenu Brasil grâce au catalogue, et la limite citée est la définition du YAML, mot pour mot. Les tests tests/test_agent.py rejouent ce circuit avec un faux modèle scripté (une valeur fausse, refusée avant BigQuery, puis corrigée) : make test le vérifie sans réseau.

Ce qui casse en production

La règle de décision

• Un seul outil tant que les questions se ramènent à « métriques × axes × filtres × période ». Ajoutez un second outil (par exemple une recherche de valeurs de marque) seulement quand l'évaluation montre une famille d'échecs qu'il résout.
• output_schema dès qu'une interface consomme la réponse ; texte libre seulement pour un chat sans boutons.
• Température 0 : la même question doit produire la même requête, sinon l'évaluation n'a pas de sens.

Pratique

Exercice. Ajoutez dans Reponse un champ confiance: Literal["haute", "moyenne", "basse"] et la règle qui le remplit. Où placez-vous la règle : dans l'instruction du modèle, ou dans le code après le tour ? Justifiez.

def confiance(requetes: list[dict], question_refusee: bool) -> str:
    if question_refusee or not requetes:
        return "basse"
    derniere = requetes[-1]
    if len(requetes) > 2 or len(derniere["lignes"]) >= 500:   # corrections multiples ou limite atteinte
        return "moyenne"
    return "haute"

• Je sais pourquoi les paramètres d'outil doivent rester plats
• Je sais où vivent les données d'un tour (état de session) et pourquoi pas dans le texte
• Je sais borner une boucle d'agent avec RunConfig(max_llm_calls=...)
• J'ai lancé python -m assistant.agent sur une question réelle