Observación de Agentes de Coding en Vivo

Observa a los agentes de coding trabajar en tiempo real con pausa, reversión y ramificación. Tres backends admitidos: Ollama para modelos locales, la API de Anthropic y el Claude Agent SDK.

Novedad en la v2.4.0

La anotación de trazas estáticas te dice lo que un agente hizo. La observación en vivo te dice lo que un agente hace en respuesta a la guía humana. El modo de agente de coding en vivo de Potato permite a los anotadores ver a un agente de coding trabajar en tiempo real -- leyendo archivos, editando código, ejecutando pruebas -- e intervenir en cualquier momento. Pausa el agente, envía nuevas instrucciones, revierte a un punto de control anterior o ramifica la trayectoria para explorar enfoques alternativos.

Esto genera datos de anotación más ricos que las trazas estáticas por sí solas. Obtienes la trayectoria completa con marcas de tiempo, las intervenciones del anotador, los puntos de decisión de ramificación y datos comparativos de los caminos alternativos. Estos datos sirven directamente para entrenar modelos de recompensa de proceso, modelos de preferencia y evaluadores de seguimiento de instrucciones.

Requisitos

Python 3.10+
Git (el sistema de puntos de control usa commits de git)
Uno de los siguientes backends de agente:
- Ollama para inferencia con modelos locales (no requiere clave de API)
- ANTHROPIC_API_KEY para acceder a la API de Anthropic
- Claude Agent SDK para la experiencia completa del agente Claude Code

Backends

Potato admite tres backends para ejecutar agentes de coding. Cada backend ejecuta el agente en un subproceso y transmite sus acciones a la interfaz de anotación en tiempo real.

1. Ollama (modelos locales)

Ejecuta agentes de coding en local sin necesidad de clave de API. Ollama ofrece inferencia rápida para modelos de pesos abiertos. Es la mejor opción para desarrollo, pruebas y situaciones en las que los datos no pueden salir de la máquina local.

Instalación:

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

Configuración:

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 de Anthropic

Usa modelos Claude a través de la API de Anthropic. Ofrece buen rendimiento en tareas de código con capacidad de uso de herramientas. Requiere una clave de API.

Instalación:

bash

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

Configuración:

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

El Claude Agent SDK ofrece la experiencia completa del agente Claude Code, incluida la orquestación automática de herramientas, la gestión de contexto y el razonamiento sobre varios archivos. Es el backend más capaz, pero requiere tener el SDK instalado.

Instalación:

bash

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

Configuración:

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

Controles

La interfaz de anotación ofrece cuatro acciones de control con las que los anotadores pueden guiar el comportamiento del agente.

Pausar / Reanudar

Pulsa Pause para detener al agente entre pasos. El agente termina el paso en curso y espera. El anotador puede revisar el estado actual, examinar archivos y decidir si deja continuar al agente o interviene. Pulsa Resume para que el agente siga.

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"

Enviar instrucciones

Con el agente en pausa, los anotadores pueden enviar nuevas instrucciones que lo redirijan. Resulta útil cuando el agente va por el camino equivocado o cuando el anotador quiere comprobar cómo responde el agente a una indicación.

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"

Las instrucciones se inyectan en el contexto de conversación del agente. La opción inject_as controla si aparecen como mensaje de sistema (instrucción con autoridad) o como mensaje de usuario (indicación conversacional).

Reversión

La reversión devuelve el proyecto a un punto de control de git anterior. Cada cambio de archivo que hace el agente se confirma automáticamente, así que el anotador puede pulsar cualquier paso anterior de la línea de tiempo y volver a ese estado exacto. El contexto de conversación del agente también se trunca en consecuencia.

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"

Ramificar y reproducir

Ramificar y reproducir combina la reversión con el envío de instrucciones. El anotador vuelve a un punto de control y envía instrucciones distintas, creando una trayectoria ramificada. Esto ayuda a la hora de recoger datos de preferencia: puedes explorar dos enfoques distintos desde el mismo punto de partida y comparar resultados.

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 vista de comparación de ramas muestra dos ramas lado a lado y resalta dónde divergen. Los anotadores pueden valorar qué rama produjo mejores resultados, lo que genera pares de preferencia para entrenar con DPO.

Sistema de Puntos de Control con Git

El modo de agente en vivo usa git para registrar cada cambio de archivo. Así se consigue una reversión fiable, ramificación y el historial completo de cambios.

Cómo Funciona

Antes de que arranque el agente, Potato crea una rama de git nueva llamada potato-session-{session_id}
Tras cada cambio de archivo (edición, escritura, creación, borrado), Potato hace un commit automático con un mensaje descriptivo
Cada commit se marca como un punto de control que aparece en la línea de tiempo
La reversión usa git checkout para restaurar el directorio de trabajo a cualquier punto de control
La ramificación crea una rama de git nueva a partir del commit del punto de control

Configuración

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

Gestión Manual de Puntos de Control

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

Formato de Datos

Los datos de entrada para las tareas de agente de coding en vivo especifican la descripción de la tarea y, opcionalmente, un archivo o directorio de partida:

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

Campo	Requerido	Descripción
`id`	Sí	Identificador único de la tarea
`task_description`	Sí	Lo que debe hacer el agente
`project_dir`	Sí	Ruta al directorio del proyecto
`start_file`	No	Archivo que se muestra al agente al principio
`test_command`	No	Comando para verificar el arreglo
`context_files`	No	Archivos que se precargan en el contexto del agente

Referencia de Configuración

Configuración completa para una tarea de observación de agente de coding en vivo:

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: per_turn_rating
    name: step_quality
    description: "Rate each agent step as you observe it"
    target: agentic_steps
    rating_type: radio
    labels:
      - "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"

Exportación de Trayectorias Ramificadas

Cuando los anotadores usan ramificar y reproducir, la salida incluye el árbol de ramificación completo. Este formato está pensado para entrenar modelos de preferencia y modelos de recompensa de proceso a partir de trayectorias comparativas.

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

Exporta trayectorias ramificadas para aprendizaje de preferencias:

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

Seguridad

El agente en vivo se ejecuta en el directorio de proyecto indicado en los datos de la tarea. Tiene permiso para leer, escribir y ejecutar archivos dentro de ese directorio. Ten en cuenta estas prácticas de seguridad:

Aislamiento: para código o modelos de agente no confiables, ejecuta Potato dentro de un contenedor Docker o una máquina virtual. El agente puede ejecutar comandos de shell arbitrarios, así que el aislamiento importa.
Modo de solo lectura: desactiva las herramientas bash y write_file si solo quieres que el agente analice el código sin modificarlo.
Restricciones de red: usa la opción --network none de Docker para impedir que el agente haga peticiones de red.
Límites de recursos: ajusta max_steps y step_timeout_seconds para que un agente descontrolado no se dispare.

yaml

# Restricted tool set for analysis-only tasks
live_agent:
  tools:
    - read_file
    - glob
    - grep
  # No edit_file, write_file, or bash

Resolución de Problemas

Ollama no está en ejecución

text

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

Arranca el servidor de Ollama:

bash

ollama serve

Comprueba que está funcionando:

bash

ollama list

Falta la clave de API

text

Error: ANTHROPIC_API_KEY environment variable not set

Define la variable de entorno:

bash

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

O añádela al archivo .env de tu proyecto. Potato carga los archivos .env automáticamente.

Git no está inicializado

text

Error: Project directory is not a git repository

El sistema de puntos de control necesita git. Inicializa un repositorio en el directorio del proyecto:

bash

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

El agente se queda en un bucle

Si el agente repite la misma acción varias veces, puede haberse quedado atascado. Potato detecta los bucles cuando la misma llamada a herramienta con los mismos argumentos se repite 3 veces y pausa el agente automáticamente. Puedes ajustar ese umbral:

yaml

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

Limpieza de ramas de sesión

Con el tiempo se acumulan ramas de sesión. Conviene limpiarlas de vez en cuando:

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

Véase También

Anotación de Agente de Coding -- anotar trazas estáticas de agentes de coding
Anotación de Recompensa de Proceso -- recoger señales de recompensa por paso para entrenar PRM
Anotación de Revisión de Código -- revisión en línea al estilo de PR de GitHub para cambios de código
Anotación Agéntica -- anotación de trazas de agente de propósito general

Para detalles de implementación, consulta la documentación fuente.