Évaluer avec adk eval

Tests et évaluation : deux questions différentes

Les tests de la leçon précédente répondent à « le code fait-il ce qu'il doit ? ». L'évaluation répond à « le modèle, dans ce code, se comporte-t-il correctement ? » : appelle-t-il les bons outils, avec les bons arguments, et sa réponse est-elle bonne ? Elle s'exécute sur le vrai modèle, donc elle coûte : on la lance avant une mise en production ou un changement de modèle, pas à chaque commit.

flowchart LR
  ES["due_diligence.evalset.json : cas attendus"] --> E["adk eval"]
  C["test_config.json : métriques et seuils"] --> E
  A["root_agent + vrai modèle"] --> E
  E --> R["Résumé : réussi / échoué"]
  E --> H[".adk/eval_history/*.json : détail"]

Installer le module d'évaluation

Dans la version installée, adk eval refuse de démarrer sans dépendances supplémentaires :

Error: Eval module is not installed, please install via `pip install "google-adk[eval]"`.

pip install "google-adk[eval]==2.10.0"

Le jeu d'évaluation

Un eval set est un fichier JSON qui contient des cas (eval_cases). Chaque cas décrit une conversation : le message utilisateur et ce qu'on attend, ici la liste des outils que le pipeline doit appeler.

{
  "eval_set_id": "due_diligence",
  "eval_cases": [{
    "eval_id": "cartonnerie_belval",
    "conversation": [{
      "invocation_id": "inv-belval",
      "user_content": {"role": "user", "parts": [{"text": "Due diligence du fournisseur : Cartonnerie Belval"}]},
      "intermediate_data": {"tool_uses": [
        {"name": "consulter_registre", "args": {"fournisseur": "Cartonnerie Belval"}},
        {"name": "consulter_finances", "args": {"fournisseur": "Cartonnerie Belval"}},
        {"name": "consulter_reputation", "args": {"fournisseur": "Cartonnerie Belval"}},
        {"name": "approuver_rapport", "args": {}}
      ]}
    }],
    "session_input": {"app_name": "due_diligence", "user_id": "eval", "state": {}}
  }]
}

Choisir la métrique

Sans fichier de configuration, ADK 2.10 applique les critères par défaut tool_trajectory_avg_score: 1.0 et response_match_score: 0.8. Ni l'un ni l'autre ne convient tel quel :

ANY_ORDER tolère aussi un approuver_rapport refusé puis accepté : seul compte que l'appel attendu ait eu lieu.

{
  "criteria": {
    "tool_trajectory_avg_score": {"threshold": 1.0, "match_type": "ANY_ORDER"}
  }
}

Si vous ne passez pas --config_file_path, adk eval cherche test_config.json dans le dossier du fichier d'eval set.

Lancer l'évaluation

Depuis le dossier parent de l'application :

adk eval due_diligence due_diligence/due_diligence.evalset.json
# un seul cas d'un jeu :  due_diligence/due_diligence.evalset.json:cartonnerie_belval
# détail en console :     --print_detailed_results

Le premier argument est le dossier de l'agent (son nom devient app_name), les suivants les fichiers d'eval set. Les résultats détaillés sont écrits dans due_diligence/.adk/eval_history/.

Exercice : un cas qui doit refuser

Ajoutez un cas fournisseur_inconnu pour « Société Imaginaire ». Quels outils attendez-vous, et quel piège de la métrique ANY_ORDER faut-il garder en tête ?

Résultat obtenu

adk eval réel avec la clé d'API (gemini-3.5-flash) le 2026-10-15 :

Using evaluation criteria: criteria={'tool_trajectory_avg_score': BaseCriterion(threshold=1.0,
  include_intermediate_responses_in_final=False, match_type='ANY_ORDER')} …
*********************************************************************
Eval Run Summary
due_diligence:
  Tests passed: 1
  Tests failed: 0

Métriques lues dans .adk/eval_history/…evalset_result.json :

cartonnerie_belval
  tool_trajectory_avg_score 1.0
  tool_call_count_v1 4.0
  inference_call_count_v1 11.0
  token_usage_v1 34089.0
  invocation_duration_v1 45.339

Ordre de grandeur pour un dossier : 11 appels au modèle, environ 34 000 tokens, 45 secondes.

Je sais faire

• Installer google-adk[eval] et lancer adk eval
• Écrire un eval set avec des trajectoires d'outils attendues
• Choisir ANY_ORDER pour un pipeline parallèle et connaître sa limite
• Lire les métriques d'efficacité (appels, tokens, durée)