Annotation agentique

Nouveau dans la v2.3.0

Les agents IA sont de plus en plus déployés pour des tâches complexes à plusieurs étapes : naviguer sur le web, écrire du code, appeler des API et orchestrer des sous-agents. Mais évaluer si un agent a vraiment fait ce qu'il fallait exige un jugement humain à une granularité que les outils d'annotation traditionnels ne peuvent pas prendre en charge. Une seule trace d'agent peut contenir des dizaines d'étapes, des appels d'outils, du raisonnement intermédiaire, des captures d'écran et des décisions de branchement. Les annotateurs doivent voir tout ce contexte, y naviguer efficacement et fournir des évaluations structurées à la fois au niveau de la trace et au niveau de chaque étape.

Le système d'annotation agentique de Potato répond à ce besoin avec quatre capacités :

1. 13 convertisseurs de format de traces qui normalisent les journaux d'agents de n'importe quel framework majeur vers un format unifié
2. 5 types d'affichage spécialisés optimisés pour différentes modalités d'agent (tool-use, navigation web, coding, chat, observation en direct)
3. 9 schémas d'annotation prêts à l'emploi couvrant les dimensions d'évaluation d'agents les plus courantes
4. 4 types d'annotation conçus sur mesure pour l'évaluation avancée : évaluation de trajectoire, évaluation par grille, comparaison par paires et annotation de récompense de processus

Convertisseurs de format de traces

Les traces d'agents se présentent dans des formats très différents selon le framework. Potato fournit 13 convertisseurs qui les normalisent en une représentation interne unifiée. Vous spécifiez le convertisseur dans votre configuration, ou vous laissez Potato détecter automatiquement le format.

Référence des convertisseurs

Configuration

Spécifiez le convertisseur dans la configuration de votre projet :

agentic:
  enabled: true
  trace_converter: react
  trace_file: "data/agent_traces.jsonl"

Chaque ligne du fichier de traces doit être un objet JSON contenant la trace brute de l'agent. Le convertisseur s'occupe du reste.

Pour les traces multi-agents où différents agents utilisent différents frameworks, vous pouvez spécifier des convertisseurs par agent :

agentic:
  enabled: true
  trace_converter: multi_agent
  trace_file: "data/multi_agent_traces.jsonl"
  multi_agent:
    agent_converters:
      planner: react
      coder: anthropic
      reviewer: openai

Détection automatique

Si vous ne savez pas quel convertisseur utiliser, définissez trace_converter: auto :

agentic:
  enabled: true
  trace_converter: auto
  trace_file: "data/traces.jsonl"

Potato inspecte les 10 premières traces et sélectionne le convertisseur qui correspond le mieux d'après les signatures de champs. Un avertissement est consigné si la confiance est inférieure à 80 %, auquel cas vous devez spécifier le convertisseur explicitement.

Convertisseurs personnalisés

Si votre framework d'agent ne figure pas dans la liste, vous pouvez écrire un convertisseur en Python :

# converters/my_converter.py
from potato.agentic.base_converter import BaseTraceConverter
 
class MyConverter(BaseTraceConverter):
    name = "my_framework"
 
    def convert(self, raw_trace: dict) -> dict:
        steps = []
        for entry in raw_trace["log"]:
            steps.append({
                "type": entry.get("kind", "action"),
                "content": entry["text"],
                "timestamp": entry.get("ts"),
                "metadata": entry.get("extra", {}),
            })
        return {"steps": steps}

Enregistrez-le dans la configuration :

agentic:
  trace_converter: custom
  custom_converter: "converters/my_converter.py:MyConverter"

Types d'affichage

Une fois les traces converties, Potato les affiche à l'aide de l'un des cinq types d'affichage spécialisés. Chacun est optimisé pour une modalité d'agent différente.

1. Affichage de trace d'agent

L'affichage par défaut pour les agents utilisant des outils (OpenAI function calling, Anthropic tool_use, ReAct, LangChain, etc.). Il affiche chaque étape sous forme de carte avec un codage couleur par type d'étape.

agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace
 
  agent_trace_display:
    # Color coding for step types
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
      system: "#6b7280"
 
    # Collapsible sections
    collapse_observations: true
    collapse_threshold: 500    # characters before auto-collapsing
 
    # Step numbering
    show_step_numbers: true
    show_timestamps: true
 
    # Tool call rendering
    render_json: true          # pretty-print JSON arguments
    syntax_highlight: true     # highlight code in observations

Fonctionnalités :

• Cartes d'étape avec une bordure gauche colorée indiquant le type (pensée, action, observation, erreur)
• Sections repliables pour les longues observations ou sorties d'outils (seuil configurable)
• Mise en forme JSON pour les arguments d'appels d'outils et les réponses structurées
• Coloration syntaxique pour les blocs de code dans les observations
• Chronologie des étapes en barre latérale montrant la trace complète d'un coup d'œil
• Navigation saut-vers-étape pour les longues traces

2. Affichage de trace d'agent web

Conçu sur mesure pour les agents de navigation web (WebArena, VisualWebArena, enregistrements de navigateur bruts). Affiche les captures d'écran avec des superpositions SVG indiquant où l'agent a cliqué, saisi ou fait défiler.

agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
 
  web_agent_display:
    # Screenshot rendering
    screenshot_max_width: 900
    screenshot_quality: 85
 
    # SVG overlay for agent actions
    overlay:
      enabled: true
      click_marker: "circle"       # circle, crosshair, or arrow
      click_color: "#ef4444"
      click_radius: 20
      type_highlight: "#3b82f6"    # highlight for text input fields
      scroll_indicator: true
 
    # Filmstrip view
    filmstrip:
      enabled: true
      thumbnail_width: 150
      show_action_labels: true
 
    # DOM snapshot display
    show_dom_snapshot: false        # optional raw DOM view
    show_url_bar: true
    show_action_description: true

Fonctionnalités :

• Galerie de captures d'écran avec affichage en taille réelle et zoom
• Superpositions SVG montrant les cibles de clic (cercles rouges), les zones de saisie de texte (surlignages bleus) et les directions de défilement
• Vue pellicule en bas montrant toutes les captures en miniatures pour une navigation rapide
• Description d'action sous chaque capture (ex. : « Cliquer sur le bouton "Add to Cart" »)
• Barre d'URL affichant l'URL de la page courante à chaque étape
• Comparaison avant/après pour les étapes qui modifient le contenu de la page

3. Affichage de chat interactif

Pour évaluer les agents conversationnels et les chatbots. Prend en charge deux sous-modes : chat en direct où les annotateurs interagissent avec l'agent en temps réel, et revue de trace où les annotateurs évaluent une conversation enregistrée.

agentic:
  enabled: true
  display_type: interactive_chat
 
  interactive_chat_display:
    mode: trace_review         # or "live_chat"
 
    # Trace review settings
    trace_review:
      show_system_prompt: false
      show_token_counts: true
      show_latency: true
      message_grouping: turn    # "turn" or "message"
 
    # Live chat settings (when mode: live_chat)
    live_chat:
      proxy: openai             # agent proxy to use
      max_turns: 20
      timeout_seconds: 60
      show_typing_indicator: true
      allow_regenerate: true
 
    # Common settings
    show_role_labels: true
    role_colors:
      user: "#3b82f6"
      assistant: "#6E56CF"
      system: "#6b7280"
      tool: "#22c55e"

Le mode revue de trace affiche une conversation enregistrée avec, en option, le nombre de tokens et la latence par message. Les annotateurs peuvent noter des tours individuels ou la conversation entière.

Le mode chat en direct connecte les annotateurs à un agent en cours d'exécution via le système de proxy d'agent (voir ci-dessous). Les annotateurs conversent avec l'agent, puis annotent la conversation obtenue.

4. Affichage de trace de coding

Conçu sur mesure pour les sessions d'agents de coding (Claude Code, Aider, SWE-Agent). Affiche les diffs de code avec coloration syntaxique, les sorties de terminal en blocs sombres et les lectures de fichiers avec numéros de ligne.

agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified           # unified or split
    terminal_theme: dark
    show_file_tree: true
    collapse_long_output: true
    collapse_threshold: 50        # lines
    show_line_numbers: true
    syntax_highlight: true

Fonctionnalités :

• Vue de diff unifiée avec surlignage rouge/vert pour les opérations d'édition
• Blocs de terminal sombres pour les sorties de commandes bash/shell
• Blocs de code numérotés pour les opérations de lecture de fichiers
• Barre latérale d'arborescence de fichiers montrant tous les fichiers modifiés pendant la session
• Longues sorties repliables pour le contenu verbeux de terminal ou de fichier

Voir Annotation d'agent de coding pour la référence complète.

5. Affichage d'agent en direct

Observation en temps réel des agents IA avec des contrôles pour l'intervention humaine. Prend en charge les agents de navigation web et les agents de coding.

agentic:
  enabled: true
  display_type: live_agent

Fonctionnalités :

• Streaming en temps réel des actions de l'agent via Server-Sent Events
• Pause/Reprise de l'agent entre les étapes
• Envoi d'instructions pour rediriger l'agent en cours de tâche
• Prise en main du contrôle manuel
• Retour arrière vers tout point de contrôle précédent (les agents de coding utilisent des points de contrôle basés sur git)
• Branchement et rejeu depuis n'importe quel point de contrôle avec des instructions différentes

Voir Évaluation d'agent en direct et Agent de coding en direct pour les détails de configuration.

Types d'annotation avancés

Au-delà des notations par tour et des schémas prêts à l'emploi, Potato inclut quatre types d'annotation conçus sur mesure pour l'évaluation structurée d'agents.

Évaluation de trajectoire (trajectory_eval)

Localisation des erreurs étape par étape avec des taxonomies d'erreurs hiérarchiques et un score de gravité. Chaque étape reçoit une note de justesse, un type d'erreur, un niveau de gravité et une justification optionnelle. Un compteur de score courant se décrémente en fonction de la gravité.

annotation_schemes:
  - annotation_type: trajectory_eval
    name: step_eval
    error_taxonomy:
      reasoning:
        - logical_error
        - incorrect_assumption
      action:
        - wrong_tool
        - wrong_arguments
        - premature_termination
    severity_weights:
      minor: -1
      major: -5
      critical: -10

Voir l'article de blog sur l'évaluation de trajectoire pour un guide complet.

Évaluation par grille (rubric_eval)

Évaluation multicritères en grille de style MT-Bench. Définissez des critères personnalisés et une échelle de notation. Les annotateurs notent chaque critère indépendamment.

annotation_schemes:
  - annotation_type: rubric_eval
    name: agent_rubric
    criteria:
      - name: correctness
        description: "Did the agent produce the correct result?"
      - name: efficiency
        description: "Did the agent take an efficient path?"
      - name: safety
        description: "Did the agent avoid unsafe actions?"
    scale: 5
    scale_labels:
      1: "Very Poor"
      3: "Acceptable"
      5: "Excellent"

Voir le tutoriel d'évaluation par grille pour les instructions de configuration.

Comparaison par paires

Comparez deux traces d'agent côte à côte avec trois modes :

• Binaire : cliquez pour sélectionner A ou B (avec égalité optionnelle)
• Échelle : curseur de « A bien meilleur » à « B bien meilleur »
• Multidimension : A/B/égalité indépendants par dimension avec justification obligatoire

annotation_schemes:
  - annotation_type: pairwise
    name: agent_comparison
    mode: multi_dimension
    dimensions:
      - correctness
      - efficiency
      - safety
    require_justification: true
    allow_tie: true

Voir le guide de comparaison par paires pour les trois modes.

Annotation de récompense de processus

Annotation binaire de justesse étape par étape, optimisée pour l'entraînement des modèles de récompense de processus. Deux modes : première erreur (cliquez sur la première étape erronée, le reste est marqué automatiquement) et par étape (notez chacune indépendamment).

annotation_schemes:
  - annotation_type: process_reward
    name: prm
    mode: first_error    # or per_step

Voir Annotation de récompense de processus pour la référence complète.

Notations par tour

Pour les évaluations de dialogue et à plusieurs étapes, vous avez souvent besoin de notations sur des tours individuels plutôt que (ou en plus) de la trace globale. Potato prend en charge l'annotation par tour pour tout type d'affichage.

annotation_schemes:
  # Overall trace rating
  - annotation_type: likert
    name: overall_quality
    description: "Rate the overall quality of this agent trace"
    min: 1
    max: 5
    labels:
      1: "Very Poor"
      5: "Excellent"
 
  # Per-turn ratings
  - annotation_type: per_turn_rating
    name: step_correctness
    description: "Was this step correct?"
    target: agentic_steps        # binds to trace steps
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Unnecessary"
 
  - annotation_type: per_turn_rating
    name: step_explanation
    description: "Explain any issues with this step"
    target: agentic_steps
    rating_type: text
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]

Les notations par tour apparaissent en ligne à côté de chaque carte d'étape. Le bloc conditional vous permet d'afficher des questions de suivi uniquement lorsque certaines notations sont sélectionnées, gardant ainsi l'interface épurée.

Format de sortie par tour

Les annotations par tour sont enregistrées avec les index d'étape :

{
  "id": "trace_042",
  "annotations": {
    "overall_quality": 3,
    "step_correctness": {
      "0": "Correct",
      "1": "Correct",
      "2": "Incorrect",
      "3": "Correct"
    },
    "step_explanation": {
      "2": "The agent searched for the wrong product name"
    }
  }
}

Système de proxy d'agent

Pour les tâches d'évaluation en direct où les annotateurs interagissent avec un agent en temps réel, Potato fournit une couche de proxy d'agent. Le proxy se place entre l'interface d'annotation et le backend de l'agent, en journalisant la conversation complète pour une revue ultérieure.

agentic:
  enabled: true
  display_type: interactive_chat
 
  agent_proxy:
    type: openai                 # openai, http, or echo
 
    # OpenAI proxy
    openai:
      model: "gpt-4o"
      api_key: ${OPENAI_API_KEY}
      system_prompt: "You are a helpful customer service agent."
      temperature: 0.7
      max_tokens: 1024

Types de proxy

Le proxy OpenAI transmet les messages à une API compatible avec OpenAI :

agent_proxy:
  type: openai
  openai:
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
    system_prompt: "You are a helpful assistant."
    temperature: 0.7

Le proxy HTTP transmet les messages à n'importe quel point de terminaison HTTP (votre propre serveur d'agent) :

agent_proxy:
  type: http
  http:
    url: "https://my-agent.example.com/chat"
    method: POST
    headers:
      Authorization: "Bearer ${AGENT_API_KEY}"
    request_template:
      messages: "{{messages}}"
      session_id: "{{session_id}}"
    response_path: "response.content"
    timeout_seconds: 30

Le proxy echo renvoie le message de l'utilisateur (utile pour les tests et le développement de l'UI) :

agent_proxy:
  type: echo
  echo:
    prefix: "[Echo] "
    delay_ms: 500

Schémas d'annotation prêts à l'emploi

Potato fournit 9 schémas d'annotation conçus spécifiquement pour l'évaluation d'agents. Utilisez-les directement ou comme point de départ pour vos propres schémas.

Chargez un schéma prêt à l'emploi par son nom :

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

Ou combinez des presets avec des schémas personnalisés :

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
 
  # Custom schema alongside presets
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations about this agent trace"
    label_requirement:
      required: false

Exemple complet : évaluer un agent ReAct

Voici une configuration complète pour évaluer des traces d'agent de style ReAct avec des notations par étape :

# project config
task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/react_traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task_description
 
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: 300
    show_step_numbers: true
    render_json: true
 
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_efficiency
 
  - annotation_type: text
    name: failure_reason
    description: "If the agent failed, describe what went wrong"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Données d'entrée d'exemple (data/react_traces.jsonl) :

{
  "trace_id": "react_001",
  "task_description": "Find the population of Tokyo and compare it to New York City",
  "trace": [
    {"type": "thought", "content": "I need to find the population of both cities. Let me search for Tokyo first."},
    {"type": "action", "content": "search", "action_input": "Tokyo population 2024"},
    {"type": "observation", "content": "Tokyo has a population of approximately 13.96 million in the city proper..."},
    {"type": "thought", "content": "Now I need to find New York City's population."},
    {"type": "action", "content": "search", "action_input": "New York City population 2024"},
    {"type": "observation", "content": "New York City has a population of approximately 8.34 million..."},
    {"type": "thought", "content": "Tokyo (13.96M) has about 67% more people than NYC (8.34M)."},
    {"type": "action", "content": "finish", "action_input": "Tokyo has ~13.96 million people vs NYC's ~8.34 million, making Tokyo about 67% larger by population."}
  ]
}

Démarrez le serveur :

potato start config.yaml -p 8000

Pour aller plus loin

• Annotation d'agent de coding — rendu des diffs, sorties de terminal, arborescence de fichiers pour les agents de coding
• Annotation de récompense de processus — données d'entraînement PRM avec modes première-erreur et par étape
• Annotation de revue de code — commentaires en ligne et verdicts de style PR GitHub
• Agent de coding en direct — observation en temps réel d'agents de coding avec retour arrière et branchement
• Évaluation d'agent en direct — observation en temps réel d'agents web
• Annotation d'agent web — revue de traces d'agents web préenregistrées
• Évaluer les agents IA : un guide complet — déroulé d'un projet complet d'évaluation d'agents
• Formats d'exportation — exporter les données d'évaluation d'agents

Pour les détails d'implémentation, consultez la documentation source.