> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Évaluez votre agent IA avec Weave
> Évaluez dans Weave des agents IA à tour unique et sur plusieurs tours de conversation grâce au flux de travail des agents et à EvaluationLogger, avec une évaluation effectuée par un juge LLM.
export const GitHubLink = ({url, compact = false}) =>
{compact ? "View source" : <>
GitHub source
}
;
export const ColabLink = ({url}) =>
Try in Colab
;
Contrairement à un simple appel LLM, un agent poursuit un objectif sur plusieurs tours de conversation, en appelant des outils et en agissant en fonction de leurs résultats. Vous ne pouvez donc pas juger un agent en comparant une seule sortie à une chaîne de caractères attendue. Il faut plutôt évaluer son comportement sur l'ensemble d'une trajectoire.
Ce tutoriel vous montre comment évaluer un agent avec Weave à l'aide du flux de travail pour agents. Vous allez créer et instrumenter un petit agent d'assistance client, noter ses runs avec un juge LLM (sur un seul tour et sur plusieurs tours de conversation), puis comparer deux versions de l'agent.
Ce que vous allez apprendre
Ce guide vous montre comment :
* Tracer un agent sous la forme d’une conversation composée de tours de conversation et d’appels d’outils.
* Évaluer chaque run à l’aide d’un juge LLM.
* Comparer deux versions d’un agent côte à côte.
* Évaluer un tour de conversation au sein d’une conversation sur plusieurs tours.
* Transformer un score unique en grille d’évaluation.
Weave organise et stocke ces évaluations ; il n’exécute pas votre agent et ne l’isole pas dans un sandbox, ce qui vous permet de conserver le runtime d’agent dont vous disposez déjà.
Dans ce tutoriel, l’agent s’exécute sur Claude Sonnet et le juge sur Claude Opus. Confier la notation à un modèle différent et plus performant que celui que vous évaluez est une bonne pratique d’évaluation.
Prérequis
Pour suivre ce tutoriel, vous avez besoin des éléments suivants :
* Un [compte CoreWeave Forge](https://id.coreweave.com/signup).
* Python 3.10 ou version ultérieure.
* Les paquets requis, installés avec : `pip install weave anthropic`.
* Une [clé API Anthropic](https://console.anthropic.com/) définie dans la variable d’environnement `ANTHROPIC_API_KEY`.
Créer et tracer l’agent
Dans cet exemple, l’agent utilise deux outils, `lookup_order` et `issue_refund`, pour examiner les demandes de remboursement et y répondre conformément à une politique qui n’autorise les remboursements que dans un délai de 30 jours. L’agent complet, avec les définitions des outils, la boucle du modèle et la conversion des messages, figure dans le notebook associé. Cette section porte sur la partie propre à Weave.
Commencez par initialiser Weave avec votre équipe et votre projet CoreWeave Forge. Remplacez `[YOUR-TEAM]` et `[YOUR-PROJECT]` par vos propres valeurs :
```python lines theme={"system"}
import weave
weave.init(
"[YOUR-TEAM]/[YOUR-PROJECT]",
# Instrumentation manuelle d’un SDK de fournisseur brut : désactivez le patching implicite
# pour éviter qu’il journalise aussi chaque appel comme un Op tracé, ce qui dupliquerait les spans.
settings={"implicitly_patch_integrations": False},
)
```
Par défaut, Weave [patche automatiquement les SDK et frameworks pris en charge](/fr/products/wandb/weave/agent-integration-quickstart) et trace automatiquement les conversations émises par les agents créés avec ceux-ci. Ce tutoriel vous montre comment instrumenter manuellement les appels de l'agent pour tracer ses conversations. Si vous laissez le patching automatique (`implicitly_patch_integrations`) activé, vos conversations seront tracées deux fois : une fois en tant que span Conversation et une fois en tant qu’op tracé.
Tracez l’agent à l’aide de `weave.conversation`. Une conversation contient des tours de conversation, et chaque tour contient l’appel de modèle ainsi que les éventuels appels d’outil :
```python lines highlight="3,4,5,13" theme={"system"}
from weave.conversation import start_conversation, Message, Usage
with start_conversation(agent_name="support-agent", conversation_id=convo_id) as conv:
with conv.start_turn(user_message=user_message) as turn:
with turn.start_llm(model="claude-sonnet-5", provider_name="anthropic") as llm:
response = anthropic_client.messages.create(...) # Votre appel de modèle.
llm.record(
input_messages=[...], # Liste de weave.Message.
output_messages=[...],
usage=Usage(input_tokens=..., output_tokens=...),
)
for call in response_tool_calls: # Votre boucle d’appels d’outils.
with turn.start_tool(name=call.name, arguments=call.arguments) as tool:
tool.result = run_tool(call) # Les dict sont encodés automatiquement.
```
Les extraits de code de ce tutoriel se concentrent sur les appels Weave et utilisent des espaces réservés pour le code de votre propre agent :
* `convo_id` et `new_id()` : un ID unique pour chaque conversation, par exemple un UUID.
* `user_message` : l’entrée de l’utilisateur pour le tour de conversation.
* `anthropic_client` : un client Anthropic initialisé.
* `response_tool_calls` et `run_tool()` : les appels d’outil demandés par le modèle et votre fonction qui les exécute.
* `run_agent_turn()` : la boucle complète de l’agent ; renvoie la réponse finale ainsi qu’une transcription en texte brut de la trajectoire (tours de conversation, appels d’outil, résultats), destinée au juge.
* `judge_task_completion()` : le juge LLM, présenté dans la section suivante.
Les définitions complètes et exécutables de tous ces éléments se trouvent dans le notebook qui accompagne ce tutoriel.
Exécutez une requête et ouvrez le lien Weave affiché. Dans la vue Agents, la conversation apparaît sous la forme d’un tour de conversation, dans lequel sont imbriqués l’appel de modèle et les appels d’outil.
Si vous créez votre agent avec une intégration de framework (Claude Agent SDK, OpenAI Agents), Weave émet automatiquement ces mêmes spans Agents. Laissez le patching implicite activé et n’effectuez pas les appels manuels `start_*`.
Noter l’agent avec un juge LLM
À l’aide d’un modèle juge, l’évaluateur évalue dans quelle mesure l’agent a accompli la tâche, sur la base des critères de réussite de celle-ci, en récompensant le bon résultat plutôt qu’une réponse qui se contente d’être polie. Dans cet exemple, le score correspond à la *réalisation de la tâche*, autrement dit : l’agent a-t-il atteint l’objectif ?
Dans cette section, nous allons définir quelques tâches, écrire le juge, puis exécuter l’évaluation sur ces tâches.
Définissez une petite suite de tâches :
```python lines theme={"system"}
tasks = [
{"task_id": "refund-eligible",
"user_request": "I'd like a refund for order A1001, please.",
"success_criteria": "Agent looks up the order and issues the refund (within 30 days)."},
{"task_id": "refund-too-late",
"user_request": "Please refund my order A1002.",
"success_criteria": "Agent declines politely (outside the 30-day window); must NOT refund."},
{"task_id": "unknown-order",
"user_request": "I want a refund for order Z9999.",
"success_criteria": "Agent reports the order cannot be found and does not refund."},
]
```
L’évaluateur est une simple fonction — Weave n'en impose pas la forme. Ici, il s'agit d'un juge LLM qui évalue `transcript` (la trajectoire en texte brut renvoyée par `run_agent_turn`) au regard des `success_criteria` de la tâche, puis renvoie un dict `{"passed", "reason"}` :
```python lines theme={"system"}
JUDGE_MODEL = "claude-opus-4-8"
def judge_task_completion(task, transcript) -> dict:
"""LLM judge. Returns {'passed': bool, 'reason': str}."""
prompt = (
"Judge the transcript against the success criteria; reward the correct "
"OUTCOME, not a polite reply.\n"
f"USER REQUEST: {task['user_request']}\n"
f"SUCCESS CRITERIA: {task['success_criteria']}\n"
f"TRANSCRIPT:\n{transcript}\n"
'Reply with ONLY a JSON object: {"passed": , "reason": ""}.'
)
reply = anthropic_client.messages.create(
model=JUDGE_MODEL, max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
)
text = "".join(b.text for b in reply.content if b.type == "text")
return json.loads(text) # {"passed": bool, "reason": str}
```
Exécutez la boucle d’évaluation et journalisez-la avec `EvaluationLogger`. Exécutez l’agent dans `log_prediction(...)` afin que la conversation tracée soit associée à la ligne d’évaluation :
```python lines highlight="1,4" theme={"system"}
ev = weave.EvaluationLogger(name="support-agent-eval", model="v1", dataset="support-refund-tasks")
for task in tasks:
with ev.log_prediction(inputs=task) as pred:
with start_conversation(agent_name="support-agent", conversation_id=new_id()) as conv:
reply, transcript = run_agent_turn(conv, task["user_request"])
pred.output = reply
pred.log_score("task_completion", judge_task_completion(task, transcript))
ev.log_summary()
```
Ouvrez le lien de l'évaluation, sélectionnez l'onglet **Evals**, puis ouvrez la ligne de votre run pour afficher son panneau de détails. L'onglet **Appel** répertorie chaque tâche avec une colonne `passed` qui indique le verdict du juge, et l'onglet **Évaluation** comporte un bouton **Voir les spans** qui ouvre la page **Agents** avec les spans tracés liés à cette évaluation.
Organiser et comparer les évaluations
Pour améliorer un agent, vous modifiez son application, puis vous vérifiez si la modification a porté ses fruits. Le prompt système, les outils, le flux de contrôle et le LLM sous-jacent font tous partie de la version du modèle. Pour comparer deux versions, exécutez de nouveau l’évaluation sur l’agent modifié, en l’étiquetant comme une nouvelle version.
Relancez l’évaluation avec une étiquette `model` différente :
```python lines highlight="4" theme={"system"}
# v2 : mêmes tâches et même boucle, mais avec un agent modifié (par ex. un prompt système révisé).
ev = weave.EvaluationLogger(
name="support-agent-eval",
model="v2", # Libellé de la version de l’agent testée.
dataset="support-refund-tasks",
)
# ... même boucle que pour v1, en exécutant l’agent modifié ...
```
Weave vous permet de [comparer des évaluations](/fr/products/wandb/weave/guides/evaluation/compare_evals) afin de déterminer si la v2 progresse ou régresse par rapport à la v1 sur les scores que vous avez journalisés, ainsi qu’en termes de latence et de coût.
Évaluer une conversation sur plusieurs tours
Dans la réalité, une conversation s’étend sur plusieurs tours de conversation, et un agent performant conserve le contexte d’un tour à l’autre. Il ne devrait pas redemander un numéro de commande que l’utilisateur a déjà fourni. Pour tester ce comportement hors ligne, initialisez l’agent avec un historique de conversation fixe, envoyez le message utilisateur suivant, puis évaluez la manière dont il traite ce tour en tenant compte du contexte.
Chaque ligne de jeu de données correspond à un scénario de ce type : les tours précédents, suivis du message auquel l’agent doit répondre. Dans l’exemple ci-dessous, le numéro de commande n’apparaît que dans l’historique ; un bon agent le réutilise donc au lieu de le redemander :
```python lines theme={"system"}
row = {
"conversation_history": [
{"role": "user", "content": "Hi, can you check the status of my order A1001?"},
{"role": "assistant", "content": "Your order A1001 was delivered 5 days ago."},
],
"next_user_message": "Thanks. Actually, I'd like to return it for a refund.",
"success_criteria": "Uses the prior context (order A1001) to issue the refund without re-asking the ID.",
}
with ev.log_prediction(inputs=row) as pred:
with start_conversation(agent_name="support-agent", conversation_id=new_id()) as conv:
reply, transcript = run_agent_turn(
conv, row["next_user_message"], history=row["conversation_history"],
)
pred.output = reply
judge_task = {"user_request": row["next_user_message"], "success_criteria": row["success_criteria"]}
pred.log_score("task_completion", judge_task_completion(judge_task, transcript))
```
Comme pour l’évaluation sur un seul tour de conversation, chaque ligne renvoie à sa transcription complète, ce qui vous permet de vérifier si l’agent a exploité le contexte précédent ou s’il a redemandé le numéro de commande.
Cette approche évalue le tour de conversation suivant à partir d’un historique figé, ce qui constitue la méthode hors ligne la plus pratique. Mesurer de bout en bout une tâche complète sur plusieurs tours de conversation, dans laquelle l’agent pilote l’ensemble de la session, nécessite des tests A/B en conditions réelles, en production, et dépasse le cadre de ce tutoriel.
Étendre vos évaluateurs
Pour évaluer des agents réels, il faut un ensemble de scores couvrant deux dimensions :
* **Fonctionnelle :** exactitude des appels d’outils, respect des instructions et reprise après des erreurs d’outils.
* **Non fonctionnelle :** sécurité et comportement de refus, latence, coût et utilisation hallucinée d’outils.
Ajoutez chacun d’eux sous la forme d’un appel `pred.log_score(...)` supplémentaire dans la même étape. Pour découvrir les types d’évaluateurs fournis par Weave, notamment les évaluateurs prêts à l’emploi et ceux basés sur des classes, ainsi que des conseils pour écrire les vôtres, consultez [Aperçu de l’évaluation](/fr/products/wandb/weave/guides/evaluation/scorers).
Étapes suivantes
Vous avez tracé un agent sous forme de conversation, évalué la réalisation de la tâche pour des interactions à un seul tour et sur plusieurs tours de conversation, et comparé des versions, le tout lié aux transcriptions de l’agent.
* Exécutez la version complète de ce tutoriel dans le [notebook associé](https://colab.research.google.com/github/wandb/docs/blob/main/weave/cookbooks/source/agent_evals.ipynb).
* Découvrez d’autres façons de lier les traces d’un agent à ses résultats d’évaluation, y compris pour les agents qui s’exécutent dans un service distinct ou qui utilisent leur propre instrumentation OTel, dans [Lier les traces d’agent aux évaluations](/fr/products/wandb/weave/guides/evaluation/evaluation_logger#link-agent-traces-to-evaluations).