Développement piloté par l’évaluation pour les agents d’IA : contrats, traces et juges
Traitez les évaluations comme des processus CI/CD pour les agents : utilisez des prompts de version en tant que contrats, suivez les exécutions avec OpenTelemetry et Tempo, puis effectuez des tests grâce à des vérifications déterministes et à un juge basé sur un LLM.
Sources: **Eval-Driven Development: A Software Engineering Approach to Production-Grade AI Agents**
La plupart des équipes qui développent de l’IA agente tombent tôt dans le piège des frameworks. La recherche d’un orchestrateur parfait semble être la première étape évidente, mais les frameworks lourds et abstraits s’avèrent ne pas être la solution, et certains d’entre eux se dégradent rapidement entre les mises à jour. Une automatisation des revues de code conçue sans aucun framework a montré à quel point peu de choses étaient nécessaires. Ce qui manquait, c’était quelque chose emprunté à l’ingénierie logicielle classique : les evals, qui fonctionnent comme des systèmes CI/CD pour les agents.
Les evals ne conviennent pas à tous les cas, et ils ne se limitent pas à utiliser un LLM en tant que juge. Les mettre en place correctement fait la différence entre un outil fragile et un système de niveau production.
La pile technique utilisée ici est délibérément open source et n’est pas liée aux services gérés par un fournisseur particulier. Pydantic AI constitue le framework d’agents, une bibliothèque légère axée sur les schémas qui ne gêne pas le fonctionnement et considère les évaluations comme une fonctionnalité de premier plan. Grafana Tempo, associé à un stockage S3, conserve les traces, en remplacement d’une plateforme gérée d’observabilité, tandis que le code généré par l’IA interroge et filtre ces traces pour chaque type d’évaluation.
Pourquoi la plupart des agents ne survivent pas en production
Le signe le plus évident d’un système d’agents qui ne durera pas réside non pas dans le modèle, le framework ou l’ingéniosité de ses prompts, mais dans l’absence de bonnes pratiques d’ingénierie de base. Si un agent ne dispose d’aucun suivi structuré, d’aucune évaluation, d’aucune versionnement des prompts ni d’aucune mesure de sécurité, il s’agit d’une démonstration conceptuelle dont les chances d’échec sont élevées.
Les logiciels traditionnels bénéficient d’une qualité continue grâce aux pipelines CI/CD, aux tests unitaires, aux tests d’intégration et aux tests de régression. Dans le monde non déterministe des agents, le problème majeur réside dans l’absence d’un cadre d’évaluation automatisé ainsi que d’outils de contrôle opérationnel. Pour développer des agents matures, il faut revenir aux principes fondamentaux : une infrastructure ouverte et un flux de travail basé sur l’Eval-Driven Development (EDD) capable de s’adapter à l’échelle.
Le pipeline de production
1. Le contrat : versionner les prompts séparément
Les prompts et les artefacts qui les accompagnent constituent la partie la plus importante d’un système d’agents ; ils ne devraient donc pas être intégrés directement dans le code de l’agent. Le code n’est que le corps du système, facile à stabiliser et à versionner, tandis que les prompts évoluent constamment avec l’amélioration des modèles.
Le pipeline commence par un contrat versionné qui précise ce qui doit être exécuté : l’agent, la demande, le modèle et la politique d’évaluation.
[
{
"agent_id": "financial_market_headlines",
"version": 1,
"agent_model": "openai:gpt-4",
"prompt": "What are today's major financial market headlines?",
"eval": {
"contains": ["market"],
"max_model_requests": 3,
"min_tool_calls": 1,
"max_tool_calls": 5,
"judge_rubric": "The answer should be a useful response to the user's financial markets question. It should summarize market-relevant information, avoid obviously unrelated content, avoid investment advice, and avoid claiming certainty beyond what the retrieved information supports."
}
}
]
Le prompt et la grille d’évaluation sont délibérément courts ici à des fins de démonstration, car les prompts utilisés en production sont généralement longs et détaillés. Le contrat lie le prompt à un prompt d’évaluation utilisant un LLM en tant que juge, ainsi qu’à des vérifications hors LLM telles que la correspondance de mots-clés avec « contains » et un nombre minimal ou maximal d’appels aux outils.
2. Le temps d’exécution : le moteur d’exécution
Le temps d’exécution de l’agent met en œuvre le contrat. Il appelle le modèle, invoque des outils externes via MCP si nécessaire et effectue le travail réel.
Le choix s’est principalement porté sur LangGraph par rapport à Pydantic AI. Python n’est pas la seule option, et même Rust dispose d’une bibliothèque dans Rig. Cependant, la vitesse pure du langage importe peu par rapport au temps d’attente lié à l’inférence du LLM et aux appels réseau vers les outils MCP, ce qui fait que l’écosystème d’IA mature et étendu de Python l’emporte. Pydantic AI a été retenu en raison de son soutien de premier ordre pour les évaluations.
Dans un environnement de production, l’exécution a généralement lieu sur Kubernetes. Il est tentant de sur-engineer en modélisant chaque agent comme une ressource personnalisée, mais les boucles de réconciliation pour des requêtes en constante évolution ralentiront fortement votre vitesse d’exécution. Gardez l’exécution légère.
3. La couche d’observabilité : pas de points aveugles
L’exécution génère des traces, des journaux, des compteurs d’utilisation, des appels aux modèles et outils, des données de latence ainsi que des erreurs, tout cela étant capturé avec OpenTelemetry et stocké dans des systèmes tels que Tempo, Loki et Prometheus. Grafana affiche ensuite ce que fait le système en production.
4. La couche d’évaluation : CI/CD pour l’IA
C’est ici que tout se met en place. Les traces d’exécution provenant de la couche d’observabilité sont directement acheminées vers l’évaluation, où deux types de tests sont effectués sur des traces réelles : des règles déterministes et des jugements non déterministes.
Le cycle ne s’arrête jamais : définir, exécuter, observer, évaluer, améliorer, répéter.
Imposer le déterminisme à un système non déterministe
Les évaluations se divisent en deux catégories. Celles qui sont déterministes peuvent être testées avec précision à l’aide de code simple. Un exemple délibérément simpliste consisterait à demander à un LLM d’additionner deux nombres puis à vérifier la réponse à l’aide d’un test unitaire.
Dans ce cas d’usage, la demande concerne les actualités du marché financier du jour, ce qui signifie que le modèle doit appeler l’outil de recherche web fourni au moins une fois. Cette partie est déterministe et constitue un test utile. De plus, si la sortie doit contenir certaines chaînes de caractères, une vérification de type « Contient » peut le confirmer.
Niveau 1 : tests déterministes en temps réel
Le jeu de tests en temps réel exécute l’agent du jour contre le contrat versionné. Pydantic Evals inclut MaxToolCalls ainsi qu’un vérificateur de texte Contains. Les éléments manquants comme MinToolCalls sont ajoutés sous forme de wrappers simples.
uv run python tests/unittest_eval_agent.py
Les évaluateurs sont réunis selon chaque cas :
evaluators=[
*[Contains(value, case_sensitive=False) for value in case.eval.contains],
MaxModelRequests(case.eval.max_model_requests),
MinToolCalls(case.eval.min_tool_calls),
MaxToolCalls(case.eval.max_tool_calls),
]
Chaque exécution se déroule plusieurs fois, car les modèles sont non déterministes. Le même modèle, avec un prompt et des paramètres identiques, peut utiliser l’outil lors d’une exécution et l’ignorer lors d’une autre. Cela est particulièrement visible avec les modèles moins chers et moins performants ; si l’une des dix exécutions échoue, cela indique que le prompt a besoin de plus de détails. Une exécution avec trois répétitions se présente comme ceci :
(financial-agent2) alex@pop-os:/ssd/ai_works/financial_agent2$ uv run python tests/unittest_eval_agent.py
Running each eval case 3 time(s)
Evaluating task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Evaluation Summary: task
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID ┃ Metrics ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ financial_market_headlines_v1 [1/3] │ tool_calls: 1 │ ✔✔✔✔ │ 18.8s │
│ │ requests: 2 │ │ │
│ │ input_tokens: 1,325 │ │ │
│ │ output_tokens: 278 │ │ │
│ │ cost: 0.0564 │ │ │
├─────────────────────────────────────┼───────────────────────┼────────────┼──────────┤
│ financial_market_headlines_v1 [2/3] │ tool_calls: 1 │ ✔✔✔✔ │ 8.8s │
│ │ requests: 2 │ │ │
│ │ input_tokens: 1,195 │ │ │
│ │ output_tokens: 82 │ │ │
│ │ cost: 0.0408 │ │ │
├─────────────────────────────────────┼───────────────────────┼────────────┼──────────┤
│ financial_market_headlines_v1 [3/3] │ tool_calls: 1 │ ✔✔✔✔ │ 13.5s │
│ │ requests: 2 │ │ │
│ │ input_tokens: 1,292 │ │ │
│ │ output_tokens: 388 │ │ │
│ │ cost: 0.0620 │ │ │
├─────────────────────────────────────┼───────────────────────┼────────────┼──────────┤
│ Averages │ requests: 2.00 │ 100.0% ✔ │ 13.7s │
│ │ output_tokens: 249.3 │ │ │
│ │ tool_calls: 1.00 │ │ │
│ │ cost: 0.0531 │ │ │
│ │ input_tokens: 1,270.7 │ │ │
└─────────────────────────────────────┴───────────────────────┴────────────┴──────────┘
Couche 2 : régression déterministe à partir des traces
La deuxième suite ne réexécute pas l’agent. Elle lit les traces terminées provenant de Tempo :
uv run python tests/regression_eval_traces.py
Il extrait le résultat final, compte le nombre de segments de modèle et d’outil, trouve le contrat enregistré et applique les mêmes règles déterministes qu’auparavant : contient, et l’outil doit être appelé au moins une fois. Un exécution enregistrée peut indiquer :
Trace: ff5a53e3392dc26cd0a2890782be70ec
Eval case: financial_market_headlines v1
Status: PASS
Model requests: 2
Tool calls: 1
contains('market'): PASS
MaxModelRequests: PASS
MaxToolCalls: PASS
C’est peu coûteux et reproductible, car il réévalue les éléments de preuve déjà collectés.
Niveau 3 : tests non déterministes avec un juge en LLM
Le contrat comprend également un critère d’évaluation pour le prompt. Il s’agit encore du même contrat succinct :
[
{
"agent_id": "financial_market_headlines",
"version": 1,
"agent_model": "openai:gpt-4",
"prompt": "What are today's major financial market headlines?",
"eval": {
"contains": ["market"],
"max_model_requests": 3,
"min_tool_calls": 1,
"max_tool_calls": 5,
"judge_rubric": "The answer should be a useful response to the user's financial markets question. It should summarize market-relevant information, avoid obviously unrelated content, avoid investment advice, and avoid claiming certainty beyond what the retrieved information supports."
}
}
]
Puisque l’agent lui-même fonctionne avec GPT-4, le juge a besoin d’un modèle plus puissant, et c’est ici que GPT-5 remplit ce rôle. Il détermine si la réponse était utile et pertinente, si elle exagérait ce que les documents consultés permettent de confirmer, et si elle contenait des conseils d’investissement.
Diviser le critère en plusieurs niveaux offre une autre approche. Des vérifications simples de type NLP peuvent être effectuées par des modèles moins performants, voire par de petits modèles auto-hébergés, et un ensemble de telles tests simples peut donner un résultat proche du jugement de niveau supérieur mentionné précédemment. Ce qui est le mieux dépend du cas d’usage et de la manière dont les tests sont conçus.
Pour aller plus en profondeur, l’article de revue « A Survey on LLM-as-a-Judge » (arXiv 2411.15594) est une lecture intéressante. Selon le cas d’usage, il faudra finalement des systèmes capables de juger le juge, en utilisant des retours d’information humains ou d’autres moyens.
La suite charge le même résultat final enregistré et exécute Pydantic Evals LLMJudge en utilisant le critère d’évaluation défini dans le contrat :
LLMJudge(
rubric=case.eval_case.eval.judge_rubric,
model=args.judge_model,
include_input=True,
score={"evaluation_name": "judge_score", "include_reason": True},
assertion={"evaluation_name": "judge_pass", "include_reason": True},
)
Voici un échec classique détecté par le juge, causé par une instruction courte et vague. Au lieu d’appeler l’outil et de résumer les résultats, le modèle a répondu par un message invitant l’utilisateur à consulter des médias financiers.
uv run python tests/regression_llm_judge_traces.py --sample-percent 50
Trace selection: fetched=1 sampled=1 judging=1 lookback_minutes=1440 sample_percent=50 max_traces=5
Trace case: trace_id=3891f0b8432c9bbcb00e5e8adce1600b agent_id=financial_market_headlines prompt_version=1 answer_chars=207
Judging 1 trace(s) with openai:gpt-5.4
Evaluating task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Evaluation Summary: task
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID ┃ Inputs ┃ Outputs ┃ Scores ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ financial_market_he… │ {'trace_id': │ Today's major │ judge_score: 0.000 │ judge_pass: ✗ │ 469µs │
│ │ '3891f0b8432c9bbcb00 │ financial market │ Reason: The │ Reason: The │ │
│ │ e5e8adce1600b', │ headlines can be │ response does not │ response does not │ │
│ │ 'agent_id': │ found on major │ summarize any actual │ summarize any │ │
│ │ 'financial_market_he │ business and finance │ market headlines or │ actual market │ │
│ │ adlines', │ news outlets │ provide │ headlines or │ │
│ │ 'prompt_version': 1, │ including CNBC, │ market-relevant │ provide │ │
│ │ 'agent_model': │ Yahoo Finance, │ information; it only │ market-relevant │ │
│ │ 'openai:gpt-4', │ Reuters, and │ redirects the user │ information; it │ │
│ │ 'judge_model': │ Bloomberg. For more │ to news websites. It │ only redirects the │ │
│ │ 'openai:gpt-5.4', │ specific stories, │ avoids investment │ user to news │ │
│ │ 'prompt': "What are │ please visit their │ advice, but it is │ websites. It avoids │ │
│ │ today's major │ websites. │ not a useful answer │ investment advice, │ │
│ │ financial market │ │ to the user's │ but it is not a │ │
│ │ headlines?"} │ │ question. │ useful answer to │ │
│ │ │ │ │ the user's │ │
│ │ │ │ │ question. │ │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
├──────────────────────┼──────────────────────┼──────────────────────┼──────────────────────┼─────────────────────┼──────────┤
│ Averages │ │ │ judge_score: 0.000 │ 0.0% ✔ │ 469µs │
└──────────────────────┴──────────────────────┴──────────────────────┴──────────────────────┴─────────────────────┴──────────┘
Un deuxième cas d’échec est présenté ci-dessous. Dans ce cas, le juge a pu se tromper dans son jugement, ou la grille d’évaluation est peut-être trop vague, car le modèle a bien utilisé le moteur de recherche MCP et obtenu des résultats satisfaisants.
uv run python tests/regression_llm_judge_traces.py --sample-percent 10 --lookback-minutes 30
Trace selection: fetched=1 sampled=1 judging=1 lookback_minutes=30 sample_percent=10 max_traces=5
Trace case: trace_id=38fa3a54134d8818c7d7a5afbf50967e agent_id=financial_market_headlines prompt_version=1 answer_chars=654
Judging 1 trace(s) with openai:gpt-5.4
Evaluating task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Evaluation Summary: task
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID ┃ Inputs ┃ Outputs ┃ Scores ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ financial_market_… │ {'trace_id': │ Here are today's │ judge_score: 0.450 │ judge_pass: ✗ │ 441µs │
│ │ '38fa3a54134d8818c │ major financial │ Reason: The │ Reason: The │ │
│ │ 7d7a5afbf50967e', │ market headlines: │ response is │ response is │ │
│ │ 'agent_id': │ │ market-related and │ market-related │ │
│ │ 'financial_market_ │ 1. Wall Street's │ avoids investment │ and avoids │ │
│ │ headlines', │ riskiest trades │ advice, but it │ investment │ │
│ │ 'prompt_version': │ are suddenly back │ mostly lists │ advice, but it │ │
│ │ 1, 'agent_model': │ on top: Chart of │ article headlines │ mostly lists │ │
│ │ 'openai:gpt-4', │ the Day - Yahoo │ and links rather │ article headlines │ │
│ │ 'judge_model': │ Finance │ than providing a │ and links rather │ │
│ │ 'openai:gpt-5.4', │ [Link](https://fi │ useful summary of │ than providing a │ │
│ │ 'prompt': "What │ nance.yahoo.com/) │ the key financial │ useful summary of │ │
│ │ are today's major │ 2. S&P 500 │ market │ the key financial │ │
│ │ financial market │ notches │ developments. │ market │ │
│ │ headlines?"} │ record-high close │ │ developments. │ │
│ │ │ as rate-hike │ │ │ │
│ │ │ worries ease - │ │ │ │
│ │ │ Reuters │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.reuters.com/mar │ │ │ │
│ │ │ kets/us/) │ │ │ │
│ │ │ 3. Treasury │ │ │ │
│ │ │ yields rise as │ │ │ │
│ │ │ U.S. threatens │ │ │ │
│ │ │ Iran with more │ │ │ │
│ │ │ economic │ │ │ │
│ │ │ sanctions - CNBC │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.cnbc.com/) │ │ │ │
│ │ │ 4. Latest stock │ │ │ │
│ │ │ market, financial │ │ │ │
│ │ │ and business news │ │ │ │
│ │ │ - MarketWatch │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.marketwatch.com │ │ │ │
│ │ │ /) │ │ │ │
│ │ │ 5. Latest finance │ │ │ │
│ │ │ and stock market │ │ │ │
│ │ │ news covering the │ │ │ │
│ │ │ Dow, S&P 500, │ │ │ │
│ │ │ banking, │ │ │ │
│ │ │ investing and │ │ │ │
│ │ │ regulation - WSJ │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.wsj.com/finance │ │ │ │
│ │ │ ) │ │ │ │
├────────────────────┼────────────────────┼───────────────────┼────────────────────┼───────────────────┼──────────┤
│ Averages │ │ │ judge_score: 0.450 │ 0.0% ✔ │ 441µs │
└────────────────────┴────────────────────┴───────────────────┴────────────────────┴───────────────────┴──────────┘mar
Effectuer ce type de test sur chaque trace peut devenir trop coûteux et lent. Un échantillonnage aléatoire est une meilleure option. Lorsque le produit offre un moyen de recueillir les retours des utilisateurs, l’ID de la trace permet d’accéder directement aux composants du flux qui ont posé problème, et seuls ceux-ci sont testés. Des produits commerciaux tels que LangSmith et Arize Phoenix couvrent cette fonctionnalité, mais un backend S3 associé à cette stack offre les mêmes capacités, et une configuration docker compose existe pour cela.
Après les tests unitaires initiaux, il devient évident que tant la prompt que la grille d’évaluation nécessitent une mise à jour, et le contrat passe à la version 2 :
{
"id": "financial_market_headlines",
"version": 2,
"agent": "websearch",
"prompt": "Use the web-search tool to find and verify today's major financial-market headlines. Report the 3 to 5 most consequential developments across equities, rates, currencies, commodities, or macroeconomic policy. For each item, state what happened, identify the affected market or region, explain briefly why it matters, and name the source with a link when available. Include the relevant date and units for numerical claims. Cross-check any surprising index level, percentage move, policy decision, or economic release against a second reliable source; if it cannot be verified, omit it or clearly label it as unconfirmed. State when the information was current, distinguish facts from developing reports or interpretation, and say when reliable current information is insufficient. Do not invent facts, present stale information as today's news, or give personalized investment advice.",
"contains": ["market"],
"max_model_requests": 4,
"min_tool_calls": 1,
"max_tool_calls": 7,
"judge_rubric": "The response should provide 3 to 5 current, consequential financial-market developments based on web research. Each item should identify what happened, the affected market or region, why it matters, and its source, preferably with a link. Numerical claims should include meaningful dates and units; surprising figures should be corroborated by a second reliable source or explicitly marked unconfirmed. The answer should state when the information was current, distinguish verified facts from developing reports or interpretation, and acknowledge insufficient evidence rather than inventing details. It must stay relevant, avoid stale news presented as current, avoid unsupported certainty, and avoid personalized investment advice. A polished but uncited answer containing an implausible or unverifiable market figure should fail."
},
De la conception au pipeline de déploiement
Lorsque chaque trace renvoie à son contrat, un pipeline de déploiement peut recueillir différents types de preuves à chaque étape, ce qui en dit plus qu’un simple taux de réussite. Un déploiement doit être évalué selon plusieurs critères :
- le fait que la tâche ait réussi
- la qualité sémantique du résultat
- le bon usage des outils
- le respect des normes de sécurité
- le coût en requêtes et en tokens
- la latence et la fiabilité
Lectures complémentaires
Le blog d’ingénierie d’Anthropic propose un article sur le fonctionnement des évaluations pour les agents IA, disponible à l’adresse https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents, qui aborde la question dans une perspective plus large.
Lectures associées
- Le développement piloté par des spécifications avec des agents de codage IA : un guide pratique — Comment maintenir les agents de codage IA alignés avec les spécifications : le flux de travail en quatre phases, les fichiers AGENTS.md et SPEC.md, les rôles des multiples agents, les niveaux de maturité et le dérive d’intention.
- L’ingénierie agente en cinq couches : des spécifications et des agents parallèles aux règles et à la supervision — Karpathy décrit le passage au-delà du codage basé sur des intuitions. Découvrez les cinq couches de l’ingénierie agente : spécifications, orchestration, règles codifiées, révision humaine et observabilité, ainsi qu’un plan sur une semaine.