Évaluer les agents IA : Guide complet de l'annotation humaine des traces d'agents

Les métriques automatisées vous disent à quelle fréquence un agent réussit. L'évaluation humaine vous dit pourquoi il échoue, où il se trompe et comment le corriger. Ce guide vous accompagne dans la mise en place d'un pipeline complet d'évaluation humaine pour les agents IA en utilisant les fonctionnalités d'annotation agentique de Potato.

Nous allons évaluer un agent de style ReAct qui répond à des questions en cherchant sur le web. À la fin de ce guide, vous aurez :

Importé des traces d'agents dans Potato
Configuré l'affichage des traces d'agents
Mis en place des schémas d'annotation globaux et par étape
Exécuté la tâche d'annotation
Exporté des résultats d'évaluation structurés

Prérequis

Installez Potato 2.3.0 ou ultérieur :

bash

pip install --upgrade potato-annotation

Vous aurez également besoin de traces d'agents à évaluer. Ce guide utilise des traces ReAct, mais la même approche fonctionne pour l'ensemble des 12 formats supportés.

Étape 1 : Préparer vos traces d'agents

Une trace ReAct est une séquence d'étapes de Pensée, Action et Observation. Voici un exemple minimal. Créez un fichier à l'emplacement data/traces.jsonl :

json

{
  "trace_id": "trace_001",
  "task": "What is the capital of Australia and what is its population?",
  "trace": [
    {"type": "thought", "content": "I need to find the capital of Australia and its population. Let me search for this."},
    {"type": "action", "content": "search", "action_input": "capital of Australia"},
    {"type": "observation", "content": "Canberra is the capital city of Australia. It was chosen as the capital in 1908 as a compromise between Sydney and Melbourne."},
    {"type": "thought", "content": "The capital is Canberra. Now I need to find its population."},
    {"type": "action", "content": "search", "action_input": "Canberra population 2025"},
    {"type": "observation", "content": "Canberra has a population of approximately 467,000 as of 2025, making it the eighth-largest city in Australia."},
    {"type": "thought", "content": "I now have both pieces of information. The capital of Australia is Canberra with a population of approximately 467,000."},
    {"type": "action", "content": "finish", "action_input": "The capital of Australia is Canberra, with a population of approximately 467,000 as of 2025."}
  ],
  "ground_truth": "Canberra, approximately 467,000"
}

Chaque ligne du fichier JSONL correspond à une trace d'agent complète. Le champ trace contient le journal étape par étape. Le champ task indique ce que l'agent devait accomplir.

Notes sur le format des traces

Pour les traces avec appels de fonctions OpenAI, le format est différent :

json

{
  "trace_id": "oai_001",
  "task": "Find cheap flights from NYC to London",
  "messages": [
    {"role": "user", "content": "Find cheap flights from NYC to London"},
    {"role": "assistant", "content": null, "tool_calls": [{"function": {"name": "search_flights", "arguments": "{\"from\": \"NYC\", \"to\": \"LHR\"}"}}]},
    {"role": "tool", "name": "search_flights", "content": "{\"flights\": [{\"airline\": \"BA\", \"price\": 450}, {\"airline\": \"AA\", \"price\": 520}]}"},
    {"role": "assistant", "content": "I found flights from NYC to London. The cheapest is British Airways at $450."}
  ]
}

Le convertisseur de Potato gère ces différences. Il suffit de spécifier le bon nom de convertisseur.

Étape 2 : Créer la configuration du projet

Créez config.yaml :

yaml

task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task
 
# --- Agentic annotation settings ---
agentic:
  enabled: true
  trace_converter: react
  display_type: agent_trace
 
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    collapse_threshold: 400
    show_step_numbers: true
    show_timestamps: false
    render_json: true
    syntax_highlight: true

Cela indique à Potato de :

Charger les traces depuis data/traces.jsonl
Utiliser le convertisseur ReAct pour analyser le champ trace
Afficher les traces en utilisant l'affichage de traces d'agent avec des cartes d'étapes codées par couleur

Étape 3 : Concevoir vos schémas d'annotation

L'évaluation d'agents nécessite généralement des jugements au niveau de la trace (l'agent a-t-il réussi ?) et des jugements au niveau de l'étape (chaque étape était-elle correcte ?). Ajoutons les deux.

Ajoutez ce qui suit à config.yaml :

yaml

annotation_schemes:
  # --- Schémas au niveau de la trace ---
 
  # 1. Réussite de la tâche (la métrique la plus importante)
  - annotation_type: radio
    name: task_success
    description: "Did the agent successfully complete the task?"
    labels:
      - "Success"
      - "Partial Success"
      - "Failure"
    label_requirement:
      required: true
    sequential_key_binding: true
 
  # 2. Exactitude de la réponse (si la tâche a une vérité terrain)
  - annotation_type: radio
    name: answer_correctness
    description: "Is the agent's final answer factually correct?"
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Cannot Determine"
    label_requirement:
      required: true
 
  # 3. Note d'efficacité
  - annotation_type: likert
    name: efficiency
    description: "Did the agent use an efficient path to the answer?"
    min: 1
    max: 5
    labels:
      1: "Very Inefficient (many unnecessary steps)"
      3: "Average"
      5: "Optimal (no wasted steps)"
 
  # 4. Notes en texte libre
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations"
    label_requirement:
      required: false
 
  # --- Schémas au niveau de l'étape ---
 
  # 5. Exactitude par étape
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    description: "Was this step correct and useful?"
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Unnecessary"
 
  # 6. Type d'erreur par étape (affiché uniquement quand l'étape n'est pas correcte)
  - annotation_type: per_turn_rating
    name: error_type
    target: agentic_steps
    description: "What type of error occurred?"
    rating_type: multiselect
    labels:
      - "Wrong tool/action"
      - "Wrong arguments"
      - "Hallucinated information"
      - "Reasoning error"
      - "Redundant step"
      - "Premature termination"
      - "Other"
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]

Cette conception de schéma vous donne :

Une métrique binaire de réussite/échec pour l'analyse de haut niveau
Une note d'exactitude pour évaluer la réponse finale
Un score d'efficacité pour comparer les stratégies d'agents
Des notes par étape pour identifier exactement où les agents se trompent
Une taxonomie d'erreurs conditionnelle qui n'apparaît que lorsqu'une étape pose problème

Étape 4 : Configurer la sortie et démarrer le serveur

Ajoutez les paramètres de sortie à config.yaml :

yaml

output_annotation_dir: "output/"
output_annotation_format: "jsonl"
 
# Optionnel : exporter aussi en Parquet pour l'analyse
parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd

config.yaml complet pour référence :

yaml

task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task
 
agentic:
  enabled: true
  trace_converter: react
  display_type: agent_trace
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    collapse_threshold: 400
    show_step_numbers: true
    render_json: true
    syntax_highlight: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    description: "Did the agent successfully complete the task?"
    labels: ["Success", "Partial Success", "Failure"]
    label_requirement:
      required: true
    sequential_key_binding: true
 
  - annotation_type: radio
    name: answer_correctness
    description: "Is the agent's final answer factually correct?"
    labels: ["Correct", "Partially Correct", "Incorrect", "Cannot Determine"]
    label_requirement:
      required: true
 
  - annotation_type: likert
    name: efficiency
    description: "Did the agent use an efficient path?"
    min: 1
    max: 5
    labels:
      1: "Very Inefficient"
      3: "Average"
      5: "Optimal"
 
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations"
    label_requirement:
      required: false
 
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    description: "Was this step correct?"
    rating_type: radio
    labels: ["Correct", "Partially Correct", "Incorrect", "Unnecessary"]
 
  - annotation_type: per_turn_rating
    name: error_type
    target: agentic_steps
    description: "Error type"
    rating_type: multiselect
    labels:
      - "Wrong tool/action"
      - "Wrong arguments"
      - "Hallucinated information"
      - "Reasoning error"
      - "Redundant step"
      - "Premature termination"
      - "Other"
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"
 
parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd

Démarrez le serveur :

bash

potato start config.yaml -p 8000

Ouvrez http://localhost:8000 dans votre navigateur.

Étape 5 : Le flux d'annotation

Quand un annotateur ouvre une trace, il voit :

La description de la tâche en haut (la requête utilisateur originale)
Les cartes d'étapes montrant la trace complète de l'agent, codée par couleur et par type :
- Cartes violettes pour les pensées/raisonnements
- Cartes bleues pour les actions/appels d'outils
- Cartes vertes pour les observations/résultats
- Cartes rouges pour les erreurs
Les contrôles de notation par étape à côté de chaque carte d'étape
Les schémas au niveau de la trace sous l'affichage de la trace

Le flux typique :

Lire la description de la tâche pour comprendre ce que l'agent devait faire
Parcourir les étapes de la trace en notant chacune d'elles
Pour toute étape notée « Partiellement correcte » ou « Incorrecte », sélectionner le(s) type(s) d'erreur
Noter la trace globale (réussite, exactitude, efficacité)
Ajouter des notes si nécessaire
Soumettre et passer à la trace suivante

Conseils pour les annotateurs

Développez les observations réduites pour vérifier que l'agent a traité les informations correctement
Comparez la réponse finale avec la vérité terrain (si disponible) avant de noter la réussite de la tâche
Notez les étapes « Inutiles » séparément des étapes « Incorrectes » -- une étape inutile gaspille de l'effort mais n'introduit pas d'erreurs
Utilisez la barre latérale de chronologie des étapes pour accéder directement à des étapes spécifiques dans les longues traces

Étape 6 : Analyser les résultats

Après l'annotation, analysez les résultats de manière programmatique.

Analyse basique avec pandas

python

import pandas as pd
import json
 
# Load annotations
annotations = []
with open("output/annotations.jsonl") as f:
    for line in f:
        annotations.append(json.loads(line))
 
df = pd.DataFrame(annotations)
 
# Task success rate
success_counts = df.groupby("annotations").apply(
    lambda x: x.iloc[0]["annotations"]["task_success"]
).value_counts()
print("Task Success Distribution:")
print(success_counts)
 
# Average efficiency rating
efficiency_scores = [
    a["annotations"]["efficiency"]
    for a in annotations
    if "efficiency" in a["annotations"]
]
print(f"\nAverage Efficiency: {sum(efficiency_scores) / len(efficiency_scores):.2f}")

Analyse des erreurs au niveau des étapes

python

# Collect all step-level errors
error_counts = {}
for ann in annotations:
    step_errors = ann["annotations"].get("error_type", {})
    for step_idx, errors in step_errors.items():
        for error in errors:
            error_counts[error] = error_counts.get(error, 0) + 1
 
print("Error Type Distribution:")
for error, count in sorted(error_counts.items(), key=lambda x: -x[1]):
    print(f"  {error}: {count}")

Analyse avec DuckDB (via Parquet)

python

import duckdb
 
# Overall success rate
result = duckdb.sql("""
    SELECT value, COUNT(*) as count
    FROM 'output/parquet/annotations.parquet'
    WHERE schema_name = 'task_success'
    GROUP BY value
    ORDER BY count DESC
""")
print(result)

Étape 7 : Passer à l'échelle

Pour des projets d'évaluation plus importants (des centaines ou des milliers de traces), considérez ces configurations :

Annotateurs multiples

Assignez plusieurs annotateurs par trace pour l'accord inter-annotateurs :

yaml

annotation_task_config:
  total_annotations_per_instance: 3
  assignment_strategy: random

Utiliser des schémas pré-construits

Pour une mise en place rapide, utilisez les schémas pré-construits d'évaluation d'agents de Potato :

yaml

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy
  - preset: agent_efficiency

Contrôle qualité

Activez les instances de référence pour le suivi de la qualité :

yaml

phases:
  training:
    enabled: true
    data_file: "data/training_traces.jsonl"
    passing_criteria:
      min_correct: 4
      total_questions: 5

Adaptation pour d'autres types d'agents

OpenAI Function Calling

yaml

agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace

Anthropic Tool Use

yaml

agentic:
  enabled: true
  trace_converter: anthropic
  display_type: agent_trace

Systèmes multi-agents (CrewAI/AutoGen)

yaml

agentic:
  enabled: true
  trace_converter: multi_agent
  display_type: agent_trace
  multi_agent:
    agent_converters:
      researcher: react
      writer: anthropic
      reviewer: openai

Pour les agents web, passez à l'affichage d'agent web :

yaml

agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
  web_agent_display:
    screenshot_max_width: 900
    overlay:
      enabled: true
    filmstrip:
      enabled: true

Consultez Annoter les agents de navigation web pour un guide dédié.

Résumé

L'évaluation humaine des agents IA nécessite des outils spécialisés. Le système d'annotation agentique de Potato fournit :

12 convertisseurs pour normaliser les traces de n'importe quel framework
3 types d'affichage optimisés pour les agents utilisant des outils, la navigation web et les agents conversationnels
Des notations par tour pour l'évaluation au niveau des étapes
9 schémas pré-construits couvrant les dimensions d'évaluation courantes
L'export Parquet pour une analyse en aval efficace

L'insight clé est que l'évaluation d'agents n'est pas simplement « l'agent a-t-il obtenu la bonne réponse ? » -- c'est « l'agent a-t-il raisonné correctement à chaque étape ? » L'annotation par étape révèle des schémas d'erreurs que les métriques agrégées manquent.

Pour aller plus loin

Documentation de l'annotation agentique
Annoter les agents de navigation web
Solo Mode -- combiner l'annotation agentique avec l'évaluation collaborative humain-LLM
Best-Worst Scaling -- classer les sorties d'agents de manière comparative
Export Parquet -- export efficace pour l'analyse

Évaluer les agents IA : Guide complet de l'annotation humaine des traces d'agents

Prérequis

Étape 1 : Préparer vos traces d'agents

Notes sur le format des traces

Étape 2 : Créer la configuration du projet

Étape 3 : Concevoir vos schémas d'annotation

Étape 4 : Configurer la sortie et démarrer le serveur

Étape 5 : Le flux d'annotation

Conseils pour les annotateurs

Étape 6 : Analyser les résultats

Analyse basique avec pandas

Analyse des erreurs au niveau des étapes

Analyse avec DuckDB (via Parquet)

Étape 7 : Passer à l'échelle

Annotateurs multiples

Utiliser des schémas pré-construits

Contrôle qualité

Adaptation pour d'autres types d'agents

OpenAI Function Calling

Anthropic Tool Use

Systèmes multi-agents (CrewAI/AutoGen)

Agents de navigation web

Résumé

Pour aller plus loin