Skip to content

Observation d'un agent de coding en direct

Regardez des agents de coding travailler en temps réel, avec pause, retour arrière et branchement. Trois backends pris en charge : Ollama pour les modèles locaux, l'API Anthropic et le Claude Agent SDK.

Nouveau dans la v2.4.0

L'annotation de traces statiques vous dit ce qu'un agent a fait. L'observation en direct vous dit ce qu'un agent fait en réponse à une intervention humaine. Le mode agent de coding en direct de Potato permet aux annotateurs de regarder un agent de coding travailler en temps réel — lire des fichiers, modifier du code, lancer des tests — et d'intervenir à tout moment. Mettez l'agent en pause, envoyez de nouvelles instructions, revenez à un point de contrôle antérieur, ou faites bifurquer la trajectoire pour explorer d'autres approches.

Les données d'annotation obtenues sont plus riches que celles des seules traces statiques. Vous récupérez la trajectoire complète horodatée, les interventions de l'annotateur, les points de branchement et les données comparatives issues des chemins alternatifs. Ces données servent directement à entraîner des modèles de récompense de processus, des modèles de préférence et des évaluateurs de suivi d'instructions.

Prérequis

  • Python 3.10+
  • Git (le système de points de contrôle s'appuie sur des commits git)
  • L'un des backends d'agent suivants :
    • Ollama pour l'inférence de modèles en local (aucune clé d'API nécessaire)
    • ANTHROPIC_API_KEY pour accéder à l'API Anthropic
    • Claude Agent SDK pour l'expérience complète de l'agent Claude Code

Backends

Potato prend en charge trois backends pour exécuter des agents de coding. Chacun lance l'agent dans un sous-processus et diffuse ses actions vers l'interface d'annotation en temps réel.

1. Ollama (modèles locaux)

Faites tourner des agents de coding en local, sans clé d'API. Ollama offre une inférence rapide pour les modèles à poids ouverts. C'est le meilleur choix pour le développement, les tests, et les situations où les données ne peuvent pas quitter la machine.

Installation :

bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
 
# Pull a coding-capable model
ollama pull qwen2.5-coder:7b
 
# Or a larger model for better performance
ollama pull deepseek-coder-v2:16b

Configuration :

yaml
agentic:
  enabled: true
  display_type: coding_trace
  live_agent:
    enabled: true
    backend: ollama
    model: qwen2.5-coder:7b
 
    ollama:
      host: "http://localhost:11434"    # Ollama server URL
      temperature: 0.2
      num_ctx: 8192                     # context window size
      num_predict: 2048                 # max tokens per response
      keep_alive: "5m"                  # keep model loaded in memory
 
    # Agent capabilities
    tools:
      - read_file
      - edit_file
      - write_file
      - bash
      - glob
      - grep
    max_steps: 50
    step_timeout_seconds: 60

2. API Anthropic

Utilisez les modèles Claude via l'API Anthropic. Bonnes performances en coding et prise en charge de l'usage d'outils. Nécessite une clé d'API.

Installation :

bash
# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."
 
# Or add to .env file
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

Configuration :

yaml
agentic:
  enabled: true
  display_type: coding_trace
  live_agent:
    enabled: true
    backend: anthropic
    model: claude-sonnet-4-20250514
 
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
      max_tokens: 4096
      temperature: 0.2
      system_prompt: |
        You are a coding assistant working on a software project.
        Read files before editing them. Run tests after making changes.
        Explain your reasoning before each action.
 
    # Agent capabilities
    tools:
      - read_file
      - edit_file
      - write_file
      - bash
      - glob
      - grep
    max_steps: 100
    step_timeout_seconds: 120

3. Claude Agent SDK

Le Claude Agent SDK offre l'expérience complète de l'agent Claude Code : orchestration automatique des outils, gestion du contexte et raisonnement sur plusieurs fichiers. C'est le backend le plus capable, mais il faut installer le SDK.

Installation :

bash
# Install the Claude Agent SDK
pip install claude-agent-sdk
 
# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

Configuration :

yaml
agentic:
  enabled: true
  display_type: coding_trace
  live_agent:
    enabled: true
    backend: claude_agent_sdk
 
    claude_agent_sdk:
      api_key: ${ANTHROPIC_API_KEY}
      model: claude-sonnet-4-20250514
      max_turns: 100
      permission_mode: auto           # auto-approve tool use
      enable_thinking: true           # show extended thinking
 
    max_steps: 100
    step_timeout_seconds: 180

Commandes

L'interface d'annotation propose quatre commandes qui permettent aux annotateurs d'orienter le comportement de l'agent.

Pause / Reprise

Cliquez sur Pause pour arrêter l'agent entre deux étapes. L'agent termine son étape en cours puis attend. L'annotateur peut examiner l'état courant, inspecter les fichiers et décider s'il laisse l'agent continuer ou s'il intervient. Cliquez sur Reprendre pour le laisser poursuivre.

yaml
live_agent:
  controls:
    pause_resume:
      enabled: true
      auto_pause_on_error: true      # pause when a command fails
      auto_pause_after_steps: 0      # pause after N steps (0 = disabled)
      keyboard_shortcut: "Space"

Envoyer des instructions

Pendant que l'agent est en pause, les annotateurs peuvent lui envoyer de nouvelles instructions pour le réorienter. C'est utile quand l'agent s'engage sur une mauvaise piste, ou quand l'annotateur veut tester la façon dont l'agent réagit à une consigne.

yaml
live_agent:
  controls:
    send_instructions:
      enabled: true
      placeholder: "Type instructions for the agent..."
      inject_as: system_message      # "system_message" or "user_message"
      keyboard_shortcut: "Enter"
      presets:
        - "Try a different approach"
        - "Read the error message more carefully"
        - "Check the test file for expected behavior"
        - "Revert your last change and try again"

Les instructions sont injectées dans le contexte de conversation de l'agent. L'option inject_as détermine si elles apparaissent comme message système (consigne qui fait autorité) ou comme message utilisateur (conseil dans le fil de la conversation).

Retour arrière

Le retour arrière ramène le projet à un point de contrôle git antérieur. Chaque modification de fichier faite par l'agent est commitée automatiquement, si bien que l'annotateur peut cliquer sur n'importe quelle étape passée de la chronologie et revenir exactement à cet état. Le contexte de conversation de l'agent est tronqué en conséquence.

yaml
live_agent:
  controls:
    rollback:
      enabled: true
      show_checkpoint_diff: true     # show what will be undone
      require_confirmation: true     # "Are you sure?" dialog
      keyboard_shortcut: "Ctrl+Z"

Bifurquer et rejouer

Le branchement combine retour arrière et envoi d'instructions. L'annotateur revient à un point de contrôle et envoie des instructions différentes, ce qui crée une trajectoire qui bifurque. C'est utile pour recueillir des données de préférence : vous pouvez explorer deux approches à partir du même point de départ et comparer les résultats.

yaml
live_agent:
  controls:
    branch:
      enabled: true
      max_branches: 5                # maximum branches from any checkpoint
      branch_naming: auto            # "auto" or "manual"
      compare_view: true             # side-by-side branch comparison
      keyboard_shortcut: "Ctrl+B"

La vue de comparaison affiche deux branches côte à côte et met en évidence l'endroit où elles divergent. Les annotateurs peuvent noter quelle branche a donné le meilleur résultat, ce qui produit des paires de préférence pour l'entraînement DPO.

Système de points de contrôle git

Le mode agent en direct utilise git pour suivre chaque modification de fichier. Cela donne un retour arrière fiable, du branchement et un historique complet des changements.

Fonctionnement

  1. Avant le démarrage de l'agent, Potato crée une branche git nommée potato-session-{session_id}
  2. Après chaque modification de fichier (édition, écriture, création, suppression), Potato commite automatiquement avec un message descriptif
  3. Chaque commit est marqué comme point de contrôle et apparaît dans la chronologie
  4. Le retour arrière utilise git checkout pour restaurer le répertoire de travail à n'importe quel point de contrôle
  5. Le branchement crée une nouvelle branche git à partir du commit du point de contrôle

Configuration

yaml
live_agent:
  git_checkpoints:
    enabled: true
    branch_prefix: "potato-session"
    commit_message_format: "Step {step}: {tool} {file_path}"
    auto_commit: true
    cleanup_on_complete: false       # delete session branches when done
    require_clean_working_dir: true  # fail if there are uncommitted changes

Gestion manuelle des points de contrôle

bash
# List all Potato session branches
git branch | grep potato-session
 
# View checkpoints for a session
git log potato-session-abc123 --oneline
 
# Clean up old session branches
python -m potato.cleanup_sessions --older-than 7d

Format des données

Les données d'entrée d'une tâche d'agent de coding en direct précisent la description de la tâche et, éventuellement, un fichier ou un répertoire de départ :

json
{
  "id": "task_001",
  "task_description": "Fix the bug in src/parser.py where empty input causes a crash",
  "project_dir": "/path/to/project",
  "start_file": "src/parser.py",
  "test_command": "python -m pytest tests/test_parser.py -v",
  "context_files": [
    "src/parser.py",
    "tests/test_parser.py"
  ]
}
ChampObligatoireDescription
idOuiIdentifiant unique de la tâche
task_descriptionOuiCe que l'agent doit faire
project_dirOuiChemin du répertoire du projet
start_fileNonFichier à montrer d'emblée à l'agent
test_commandNonCommande pour vérifier le correctif
context_filesNonFichiers à précharger dans le contexte de l'agent

Référence de configuration

Configuration complète d'une tâche d'observation d'agent de coding en direct :

yaml
task_name: "Live Coding Agent Observation"
task_dir: "."
 
data_files:
  - "data/coding_tasks.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
agentic:
  enabled: true
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified
    diff_context_lines: 3
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    file_tree:
      enabled: true
      position: left
      click_to_navigate: true
 
  live_agent:
    enabled: true
    backend: anthropic
    model: claude-sonnet-4-20250514
 
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
      max_tokens: 4096
      temperature: 0.2
 
    tools:
      - read_file
      - edit_file
      - write_file
      - bash
      - glob
      - grep
 
    max_steps: 100
    step_timeout_seconds: 120
 
    controls:
      pause_resume:
        enabled: true
        auto_pause_on_error: true
        keyboard_shortcut: "Space"
      send_instructions:
        enabled: true
        inject_as: system_message
        presets:
          - "Try a different approach"
          - "Read the error message carefully"
          - "Run the tests first"
      rollback:
        enabled: true
        require_confirmation: true
      branch:
        enabled: true
        max_branches: 5
        compare_view: true
 
    git_checkpoints:
      enabled: true
      branch_prefix: "potato-session"
      auto_commit: true
      cleanup_on_complete: false
 
annotation_schemes:
  # Per-step ratings during observation
  - annotation_type: trajectory_eval
    name: step_quality
    description: "Rate each agent step as you observe it"
    steps_key: agentic_steps
    correctness_options:
      - "Good"
      - "Acceptable"
      - "Unnecessary"
      - "Incorrect"
 
  # Overall task completion after agent finishes
  - annotation_type: radio
    name: task_completion
    description: "Did the agent complete the task?"
    labels:
      - "Fully Complete"
      - "Partially Complete"
      - "Failed"
 
  # Branch comparison (when branching is used)
  - annotation_type: radio
    name: branch_preference
    description: "Which branch produced a better result?"
    labels:
      - "Branch A"
      - "Branch B"
      - "Both Equal"
      - "Both Failed"
 
  # Notes on the observation
  - annotation_type: text
    name: observation_notes
    description: "Describe what you observed and any interventions you made"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Exportation des trajectoires qui bifurquent

Quand les annotateurs utilisent le branchement, la sortie contient l'arbre de branchement complet. Ce format est conçu pour entraîner des modèles de préférence et des modèles de récompense de processus à partir de trajectoires comparatives.

json
{
  "id": "task_001",
  "annotator": "observer_01",
  "root_branch": {
    "branch_id": "main",
    "steps": [
      {"step": 0, "type": "file_read", "file": "src/parser.py", "rating": "Good"},
      {"step": 1, "type": "edit", "file": "src/parser.py", "rating": "Incorrect"}
    ],
    "children": [
      {
        "branch_id": "branch_1",
        "branch_point": 1,
        "instruction": "Try a different approach -- use a try/except block instead",
        "steps": [
          {"step": 2, "type": "edit", "file": "src/parser.py", "rating": "Good"},
          {"step": 3, "type": "terminal", "command": "pytest", "rating": "Good"}
        ],
        "outcome": "Fully Complete",
        "children": []
      },
      {
        "branch_id": "branch_2",
        "branch_point": 1,
        "instruction": "Read the test file first to understand expected behavior",
        "steps": [
          {"step": 2, "type": "file_read", "file": "tests/test_parser.py", "rating": "Good"},
          {"step": 3, "type": "edit", "file": "src/parser.py", "rating": "Good"},
          {"step": 4, "type": "terminal", "command": "pytest", "rating": "Good"}
        ],
        "outcome": "Fully Complete",
        "children": []
      }
    ]
  },
  "branch_preference": "Branch B",
  "observation_notes": "Both branches solved the problem, but branch B produced cleaner code by reading the tests first."
}

Exportez les trajectoires qui bifurquent pour l'apprentissage de préférences :

bash
# Export as DPO preference pairs from branch comparisons
python -m potato.export \
  -i output/ \
  -f branching_dpo \
  -o results/branch_preferences.jsonl
 
# Export full trajectory trees
python -m potato.export \
  -i output/ \
  -f trajectory_tree \
  -o results/trajectory_trees.jsonl

Sécurité

L'agent en direct s'exécute dans le répertoire de projet indiqué dans les données de la tâche. Il peut lire, écrire et exécuter des fichiers à l'intérieur de ce répertoire. Quelques pratiques à considérer :

  • Bac à sable : pour du code non fiable ou des modèles d'agent non fiables, faites tourner Potato dans un conteneur Docker ou une VM. L'agent peut exécuter des commandes shell arbitraires, l'isolation compte donc.
  • Mode lecture seule : désactivez les outils bash et write_file si vous voulez seulement que l'agent analyse le code sans le modifier.
  • Restrictions réseau : utilisez l'option --network none de Docker pour empêcher l'agent d'émettre des requêtes réseau.
  • Limites de ressources : réglez max_steps et step_timeout_seconds pour éviter les agents qui s'emballent.
yaml
# Restricted tool set for analysis-only tasks
live_agent:
  tools:
    - read_file
    - glob
    - grep
  # No edit_file, write_file, or bash

Dépannage

Ollama ne tourne pas

text
Error: Connection refused at http://localhost:11434

Démarrez le serveur Ollama :

bash
ollama serve

Vérifiez qu'il tourne :

bash
ollama list

Clé d'API manquante

text
Error: ANTHROPIC_API_KEY environment variable not set

Définissez la variable d'environnement :

bash
export ANTHROPIC_API_KEY="sk-ant-..."

Ou ajoutez-la au fichier .env de votre projet. Potato charge les fichiers .env automatiquement.

Git non initialisé

text
Error: Project directory is not a git repository

Le système de points de contrôle a besoin de git. Initialisez un dépôt dans le répertoire du projet :

bash
cd /path/to/project
git init
git add -A
git commit -m "Initial commit"

L'agent tourne en boucle

Si l'agent répète plusieurs fois la même action, il est peut-être bloqué. Potato détecte les boucles quand le même appel d'outil avec les mêmes arguments se répète 3 fois, et met alors l'agent en pause automatiquement. Ce seuil est configurable :

yaml
live_agent:
  loop_detection:
    enabled: true
    threshold: 3                     # pause after N identical consecutive steps
    action: pause                    # "pause" or "terminate"

Nettoyage des branches de session

Avec le temps, les branches de session s'accumulent. Nettoyez-les régulièrement :

bash
# Remove branches older than 7 days
python -m potato.cleanup_sessions --older-than 7d
 
# Remove all session branches
python -m potato.cleanup_sessions --all
 
# Dry run (show what would be deleted)
python -m potato.cleanup_sessions --older-than 7d --dry-run

Voir aussi

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