Évaluation d'agent en direct

Nouveau dans la v2.4.0

L'évaluation d'agent en direct permet aux annotateurs de regarder un agent IA naviguer sur le web en temps réel et d'annoter son comportement pendant qu'il tourne, plutôt qu'après coup. L'agent prend des captures d'écran, les envoie à un LLM de vision, reçoit des actions et les exécute dans un navigateur sans interface. Chaque étape est diffusée en direct sur l'écran de l'annotateur.

Prérequis

pip install playwright anthropic
playwright install chromium
export ANTHROPIC_API_KEY=your_key_here

Configuration

live_agent:
  endpoint_type: anthropic_vision
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 4096
    temperature: 0.3
  system_prompt: |
    You are a web browsing agent. Complete the given task efficiently.
    At each step, describe your thought, then output an action.
  max_steps: 30
  step_delay: 1.0
  viewport:
    width: 1280
    height: 720
  allow_takeover: true
  allow_instructions: true
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: agent_trace
      type: live_agent
      label: "Live Agent Session"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_controls: true

Référence de configuration

Format des données

Chaque instance fournit la tâche et l'URL de départ :

{
  "id": "task_001",
  "task_description": "Search for climate change on Wikipedia and find the year it was first described",
  "start_url": "https://en.wikipedia.org"
}

Déroulé pour l'annotateur

1. L'annotateur lit la description de la tâche et clique sur Start Agent
2. Un navigateur Chromium sans interface démarre et se connecte au LLM
3. Les captures d'écran arrivent en direct dans la visionneuse à mesure que l'agent navigue : chaque étape montre la capture, la réflexion de l'agent et l'action effectuée
4. L'annotateur peut intervenir depuis le panneau de commandes :
   • Pause / Reprise — arrêter l'agent entre deux étapes
   • Envoyer des instructions — injecter un message dans le contexte de l'agent en cours d'exécution
   • Prendre la main — passer en navigation manuelle
   • Arrêter — mettre fin à la session avant terme
5. Quand la session se termine (réussite, échec ou max_steps atteint), la trace est enregistrée et l'affichage bascule en mode relecture
6. L'annotateur remplit les schémas d'annotation pour évaluer la performance de l'agent

Raccourcis clavier

Ajouter des schémas d'annotation

Associez l'affichage d'agent en direct à n'importe quel schéma d'annotation de Potato :

annotation_schemes:
  - annotation_type: radio
    name: task_success
    description: "Did the agent complete the task?"
    labels:
      - name: "Yes, fully"
      - name: "Partially"
      - name: "No"
  - annotation_type: likert
    name: efficiency
    description: "How efficiently did the agent work?"
    min_label: "Very inefficient"
    max_label: "Very efficient"
  - annotation_type: text
    name: errors_observed
    description: "Describe any errors or unnecessary steps"
  - annotation_type: span
    name: error_steps
    description: "Mark any steps where the agent made an error"
    labels:
      - name: hallucination
      - name: wrong_target
      - name: unnecessary_action

Exemple complet

task_name: "Live Agent Evaluation Study"
task_dir: "."
 
live_agent:
  endpoint_type: anthropic_vision
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 4096
    temperature: 0.3
  max_steps: 25
  step_delay: 1.5
  viewport:
    width: 1280
    height: 720
  allow_takeover: true
  allow_instructions: true
  history_window: 5
 
data_files:
  - "tasks.jsonl"
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: agent_trace
      type: live_agent
      label: "Live Session"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_controls: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    description: "Did the agent complete the task?"
    labels:
      - name: "Yes"
      - name: "Partially"
      - name: "No"
  - annotation_type: likert
    name: efficiency
    description: "Rate the agent's efficiency"
    min_label: "Very inefficient"
    max_label: "Very efficient"
  - annotation_type: text
    name: notes
    description: "Notes on agent behavior"
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Architecture

L'agent en direct tourne dans un thread d'arrière-plan de Flask. Les captures d'écran et les changements d'état sont diffusés vers le navigateur par Server-Sent Events (SSE). Les commandes de l'annotateur (pause, instruction, reprise en main, arrêt) appellent des points de terminaison REST qui se synchronisent avec ce thread.

Annotator (browser)  <── SSE stream ──  Flask Server  ── Playwright ──► Headless Browser
                     ──► REST control ─►              ◄── LLM API ────► Claude Vision

Les captures d'écran sont enregistrées dans {task_dir}/live_sessions/ et servies via l'API pour la vue en pellicule.

Exportation des traces

Quand une session se termine, Potato exporte automatiquement la trace complète en JSON compatible web_agent_trace, avec :

• Toutes les étapes, avec captures d'écran, actions, réflexions et observations
• Les instructions envoyées en cours d'exécution par l'annotateur
• Les horodatages et les métadonnées de configuration de l'agent
• Les événements de reprise en main par l'annotateur

Les sessions en direct terminées peuvent donc être relues plus tard avec la visionneuse standard d'annotation d'agent web.

Dépannage

« Playwright is not installed » — lancez pip install playwright && playwright install chromium.

« Anthropic API key required » — définissez la variable d'environnement ANTHROPIC_API_KEY ou utilisez api_key: ${ANTHROPIC_API_KEY} dans votre configuration.

L'agent paraît lent — chaque étape demande un appel d'API au LLM (3 à 10 secondes en général). L'indicateur de réflexion s'affiche pendant le traitement du LLM. Réduisez history_window pour accélérer les longues sessions.

Les captures d'écran ne se chargent pas — vérifiez que task_dir est accessible en écriture et qu'il reste de l'espace disque sur le serveur.

Backends d'agents de coding

Au-delà des agents de navigation web, Potato prend en charge l'observation en direct des agents de coding. Trois backends sont disponibles.

Ollama (local, sans clé d'API)

Faites tourner l'évaluation d'agents de coding avec des modèles entièrement locaux, sans clé d'API.

live_agent:
  endpoint_type: coding_agent
  backend: ollama
  ai_config:
    model: qwen2.5-coder:7b
    host: "http://localhost:11434"
  max_steps: 50
  project_dir: "./workspace"

API Anthropic

Utilisez Claude avec usage d'outils pour l'évaluation d'agents de coding.

live_agent:
  endpoint_type: coding_agent
  backend: anthropic
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 8192
  max_steps: 50
  project_dir: "./workspace"

Claude Agent SDK

Toutes les capacités de Claude Code, pour les sessions d'agents de coding avancées.

live_agent:
  endpoint_type: coding_agent
  backend: claude_agent_sdk
  ai_config:
    max_turns: 50
  project_dir: "./workspace"

Voir Observation d'un agent de coding en direct pour la référence complète, y compris le retour arrière, le branchement et l'exportation des trajectoires.

Retour arrière et points de contrôle

Pour les sessions d'agents de coding, Potato crée un commit git après chaque modification de fichier. Cela permet :

• Un retour arrière en un clic vers n'importe quel point de contrôle antérieur
• Le branchement et la relecture — tenter une autre approche à partir de n'importe quel point de contrôle
• Un historique complet de chaque état de fichier pour la relecture

Les points de contrôle sont gérés automatiquement, sur une branche git dédiée par session.

Trajectoires qui bifurquent

Quand un annotateur revient en arrière et tente une autre approche, Potato crée une trajectoire qui bifurque. Les deux branches sont conservées dans la sortie, ce qui produit des données d'entraînement pour :

• Les modèles de récompense de processus — étiquettes de justesse par étape sur toutes les branches
• L'apprentissage de préférences — quelle branche a donné le meilleur résultat
• Les jeux de données de revue de code — comparer la qualité du code entre approches

Pour aller plus loin

• Observation d'un agent de coding en direct — observation d'agents de coding avec Ollama, Anthropic et le Claude SDK
• Annotation d'agent web — relire des traces d'agents préenregistrées
• Annotation agentique — panorama des formats de traces d'agents et des convertisseurs
• Annotation de récompense de processus — collecte de données d'entraînement PRM
• Support IA — intégration de LLM pour l'aide à l'annotation

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