Anotación Agéntica

Novedad en la v2.3.0

Cada vez se despliegan más agentes de IA para tareas complejas de varios pasos: navegar por la web, escribir código, llamar a APIs y orquestar subagentes. Pero evaluar si un agente realmente hizo lo correcto exige un juicio humano con una granularidad que las herramientas de anotación tradicionales no pueden ofrecer. Una sola traza de agente puede contener decenas de pasos, llamadas a herramientas, razonamiento intermedio, capturas de pantalla y decisiones de ramificación. Los anotadores necesitan ver todo ese contexto, recorrerlo de forma eficiente y aportar evaluaciones estructuradas tanto a nivel de traza como a nivel de cada paso individual.

El sistema de anotación agéntica de Potato resuelve esto con cuatro capacidades:

1. 13 conversores de formato de trazas que normalizan los registros de agentes de cualquier framework importante a un formato unificado
2. 5 tipos de visualización especializados optimizados para distintas modalidades de agente (tool-use, navegación web, coding, chat, observación en vivo)
3. 9 esquemas de anotación predefinidos que cubren las dimensiones de evaluación de agentes más comunes
4. 4 tipos de anotación hechos a medida para evaluación avanzada: evaluación de trayectoria, evaluación por rúbrica, comparación por pares y anotación de recompensa de proceso

Conversores de Formato de Trazas

Las trazas de agentes vienen en formatos muy distintos según el framework. Potato incluye 13 conversores que las normalizan en una representación interna unificada. Especificas el conversor en tu configuración, o dejas que Potato detecte el formato automáticamente.

Referencia de Conversores

Configuración

Especifica el conversor en la configuración de tu proyecto:

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

Cada línea del archivo de trazas debe ser un objeto JSON que contenga la traza bruta del agente. El conversor se encarga del resto.

Para trazas multiagente en las que distintos agentes usan distintos frameworks, puedes especificar conversores por agente:

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

Detección Automática

Si no estás seguro de qué conversor usar, define trace_converter: auto:

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

Potato inspecciona las 10 primeras trazas y selecciona el conversor que mejor coincide según las firmas de los campos. Se registra una advertencia si la confianza queda por debajo del 80%, en cuyo caso debes especificar el conversor de forma explícita.

Conversores Personalizados

Si tu framework de agente no está en la lista, puedes escribir un conversor 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}

Regístralo en la configuración:

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

Tipos de Visualización

Una vez convertidas las trazas, Potato las renderiza usando uno de cinco tipos de visualización especializados. Cada uno está optimizado para una modalidad de agente diferente.

1. Visualización de Traza de Agente

La visualización predeterminada para agentes que usan herramientas (OpenAI function calling, Anthropic tool_use, ReAct, LangChain, etc.). Renderiza cada paso como una tarjeta con codificación por colores según el tipo de paso.

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

Características:

• Tarjetas de paso con borde izquierdo de color que indica el tipo (pensamiento, acción, observación, error)
• Secciones plegables para observaciones largas o salidas de herramientas (umbral configurable)
• Formateo de JSON para los argumentos de las llamadas a herramientas y las respuestas estructuradas
• Resaltado de sintaxis para los bloques de código en las observaciones
• Línea de tiempo de pasos en la barra lateral que muestra la traza completa de un vistazo
• Navegación salto-a-paso para trazas largas

2. Visualización de Traza de Agente Web

Hecha a medida para agentes de navegación web (WebArena, VisualWebArena, grabaciones brutas de navegador). Renderiza capturas de pantalla con superposiciones SVG que muestran dónde hizo clic, escribió o se desplazó el agente.

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

Características:

• Galería de capturas de pantalla con visualización a tamaño completo y zoom
• Superposiciones SVG que muestran los objetivos de clic (círculos rojos), las regiones de entrada de texto (resaltados azules) y las direcciones de desplazamiento
• Vista en tira de película en la parte inferior que muestra todas las capturas como miniaturas para una navegación rápida
• Descripción de la acción debajo de cada captura (p. ej., "Hacer clic en el botón 'Add to Cart'")
• Barra de URL que muestra la URL de la página actual en cada paso
• Comparación antes/después para los pasos que modifican el contenido de la página

3. Visualización de Chat Interactivo

Para evaluar agentes conversacionales y chatbots. Admite dos submodos: chat en vivo, donde los anotadores interactúan con el agente en tiempo real, y revisión de traza, donde los anotadores evalúan una conversación grabada.

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"

El modo de revisión de traza renderiza una conversación grabada con conteos de tokens y latencia por mensaje opcionales. Los anotadores pueden valorar turnos individuales o la conversación completa.

El modo de chat en vivo conecta a los anotadores con un agente en ejecución a través del Sistema de Proxy de Agente (ver más abajo). Los anotadores conversan con el agente y luego anotan la conversación resultante.

4. Visualización de Traza de Coding

Hecha a medida para sesiones de agentes de coding (Claude Code, Aider, SWE-Agent). Renderiza diffs de código con resaltado de sintaxis, salida de terminal en bloques oscuros y lecturas de archivos con números de línea.

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

Características:

• Vista de diff unificada con resaltado rojo/verde para las operaciones de edición
• Bloques de terminal oscuros para la salida de comandos bash/shell
• Bloques de código con números de línea para las operaciones de lectura de archivos
• Barra lateral con árbol de archivos que muestra todos los archivos tocados durante la sesión
• Salidas largas plegables para contenido verboso de terminal o de archivo

Consulta Anotación de Agente de Coding para la referencia completa.

5. Visualización de Agente en Vivo

Observación en tiempo real de agentes de IA con controles para la intervención humana. Admite agentes de navegación web y agentes de coding.

agentic:
  enabled: true
  display_type: live_agent

Características:

• Streaming en tiempo real de las acciones del agente mediante Server-Sent Events
• Pausar/Reanudar el agente entre pasos
• Enviar instrucciones para redirigir al agente en mitad de la tarea
• Tomar el control manual
• Revertir a cualquier punto de control anterior (los agentes de coding usan puntos de control basados en git)
• Ramificar y reproducir desde cualquier punto de control con instrucciones distintas

Consulta Evaluación de Agente en Vivo y Agente de Coding en Vivo para los detalles de configuración.

Tipos de Anotación Avanzados

Más allá de las valoraciones por turno y los esquemas predefinidos, Potato incluye cuatro tipos de anotación hechos a medida para la evaluación estructurada de agentes.

Evaluación de Trayectoria (trajectory_eval)

Localización de errores por paso con taxonomías de errores jerárquicas y puntuación de severidad. Cada paso recibe una valoración de corrección, un tipo de error, un nivel de severidad y una justificación opcional. Un contador de puntuación corriente se decrementa según la severidad.

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

Consulta la entrada de blog sobre evaluación de trayectoria para una guía completa.

Evaluación por Rúbrica (rubric_eval)

Evaluación multicriterio en cuadrícula al estilo MT-Bench. Define criterios personalizados y una escala de valoración. Los anotadores valoran cada criterio de forma independiente.

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"

Consulta el tutorial de evaluación por rúbrica para las instrucciones de configuración.

Comparación por Pares

Compara dos trazas de agente lado a lado con tres modos:

• Binario: haz clic para seleccionar A o B (con empate opcional)
• Escala: control deslizante de "A mucho mejor" a "B mucho mejor"
• Multidimensión: A/B/empate independientes por dimensión, con justificación obligatoria

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

Consulta la guía de comparación por pares para los tres modos.

Anotación de Recompensa de Proceso

Anotación binaria de corrección por paso, optimizada para entrenar modelos de recompensa de proceso. Dos modos: primer-error (haz clic en el primer paso incorrecto y el resto se marca automáticamente) y por paso (valora cada uno de forma independiente).

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

Consulta Anotación de Recompensa de Proceso para la referencia completa.

Valoraciones por Turno

Para evaluaciones de diálogo y de varios pasos, a menudo necesitas valoraciones de turnos individuales en lugar de (o además de) la traza global. Potato admite anotación por turno para cualquier tipo de visualización.

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

Las valoraciones por turno aparecen en línea junto a cada tarjeta de paso. El bloque conditional permite mostrar preguntas de seguimiento solo cuando se seleccionan ciertas valoraciones, manteniendo la interfaz limpia.

Formato de Salida por Turno

Las anotaciones por turno se guardan con índices de paso:

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

Sistema de Proxy de Agente

Para tareas de evaluación en vivo en las que los anotadores interactúan con un agente en tiempo real, Potato proporciona una capa de proxy de agente. El proxy se sitúa entre la interfaz de anotación y el backend del agente, registrando la conversación completa para su revisión posterior.

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

Tipos de Proxy

El proxy OpenAI reenvía mensajes a una API compatible con OpenAI:

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

El proxy HTTP reenvía mensajes a cualquier endpoint HTTP (tu propio servidor de agente):

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

El proxy echo devuelve el mensaje del usuario (útil para pruebas y desarrollo de UI):

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

Esquemas de Anotación Predefinidos

Potato incluye 9 esquemas de anotación diseñados específicamente para la evaluación de agentes. Úsalos directamente o como punto de partida para tus propios esquemas.

Carga un esquema predefinido por su nombre:

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

O combina presets con esquemas personalizados:

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

Ejemplo Completo: Evaluando un Agente ReAct

Aquí tienes una configuración completa para evaluar trazas de agente al estilo ReAct con valoraciones por paso:

# 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"

Datos de entrada de ejemplo (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."}
  ]
}

Inicia el servidor:

potato start config.yaml -p 8000

Lectura Adicional

• Anotación de Agente de Coding — renderizado de diffs, salida de terminal, árbol de archivos para agentes de coding
• Anotación de Recompensa de Proceso — datos de entrenamiento de PRM con modos primer-error y por paso
• Anotación de Revisión de Código — comentarios en línea y veredictos al estilo de PR de GitHub
• Agente de Coding en Vivo — observación en tiempo real de agentes de coding con reversión y ramificación
• Evaluación de Agente en Vivo — observación en tiempo real de agentes web
• Anotación de Agente Web — revisión de trazas de agentes web pregrabadas
• Evaluando Agentes de IA: Una Guía Completa — recorrido por un proyecto completo de evaluación de agentes
• Formatos de Exportación — exportar datos de evaluación de agentes

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