Évaluez votre agent IA avec Weave

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.
Python 3.10 ou version ultérieure.
Les paquets requis, installés avec : pip install weave anthropic.
Une clé API Anthropic 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 :

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 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 :

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 :

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"} :

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": <bool>, "reason": "<one sentence>"}.'
    )
    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 :

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 :

# 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 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 :

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.

É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é.
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.

​Ce que vous allez apprendre

​Prérequis

​Créer et tracer l’agent

​Noter l’agent avec un juge LLM

​Organiser et comparer les évaluations

​Évaluer une conversation sur plusieurs tours

​Étendre vos évaluateurs

​Étapes suivantes

Ce que vous allez apprendre

Prérequis

Créer et tracer l’agent

Noter l’agent avec un juge LLM

Organiser et comparer les évaluations

Évaluer une conversation sur plusieurs tours

Étendre vos évaluateurs

Étapes suivantes