Skip to content
Guides10 min read

Evaluación de Agentes de IA: Una Guía Completa para la Anotación Humana de Trazas de Agentes

Aprende a configurar la evaluación humana de las salidas de agentes de IA usando las funciones de anotación agéntica de Potato, desde la importación de trazas hasta el diseño del esquema de anotación.

Potato Team·

Evaluación de Agentes de IA: Una Guía Completa para la Anotación Humana de Trazas de Agentes

Las métricas automatizadas te dicen con qué frecuencia un agente tiene éxito. La evaluación humana te dice por qué falla, dónde se equivoca y cómo solucionarlo. Esta guía explica cómo configurar un pipeline completo de evaluación humana para agentes de IA usando las funciones de anotación agéntica de Potato.

Evaluaremos un agente de estilo ReAct que responde preguntas buscando en la web. Al final de esta guía, habrás:

  • Importado trazas de agentes en Potato
  • Configurado la visualización de trazas de agentes
  • Establecido esquemas de anotación tanto generales como por paso
  • Ejecutado la tarea de anotación
  • Exportado resultados de evaluación estructurados

Requisitos Previos

Instala Potato 2.3.0 o posterior:

bash
pip install --upgrade potato-annotation

También necesitarás trazas de agentes para evaluar. Esta guía usa trazas ReAct, pero el mismo enfoque funciona para cualquiera de los 12 formatos soportados.

Paso 1: Prepara Tus Trazas de Agentes

Una traza ReAct es una secuencia de pasos de Pensamiento, Acción y Observación. Aquí tienes un ejemplo mínimo. Crea un archivo en data/traces.jsonl:

json
{
  "trace_id": "trace_001",
  "task": "What is the capital of Australia and what is its population?",
  "trace": [
    {"type": "thought", "content": "I need to find the capital of Australia and its population. Let me search for this."},
    {"type": "action", "content": "search", "action_input": "capital of Australia"},
    {"type": "observation", "content": "Canberra is the capital city of Australia. It was chosen as the capital in 1908 as a compromise between Sydney and Melbourne."},
    {"type": "thought", "content": "The capital is Canberra. Now I need to find its population."},
    {"type": "action", "content": "search", "action_input": "Canberra population 2025"},
    {"type": "observation", "content": "Canberra has a population of approximately 467,000 as of 2025, making it the eighth-largest city in Australia."},
    {"type": "thought", "content": "I now have both pieces of information. The capital of Australia is Canberra with a population of approximately 467,000."},
    {"type": "action", "content": "finish", "action_input": "The capital of Australia is Canberra, with a population of approximately 467,000 as of 2025."}
  ],
  "ground_truth": "Canberra, approximately 467,000"
}

Cada línea en el archivo JSONL es una traza completa de agente. El campo trace contiene el registro paso a paso. El campo task es lo que se le pidió al agente que hiciera.

Notas sobre el Formato de Trazas

Para trazas de llamada a funciones de OpenAI, el formato es diferente:

json
{
  "trace_id": "oai_001",
  "task": "Find cheap flights from NYC to London",
  "messages": [
    {"role": "user", "content": "Find cheap flights from NYC to London"},
    {"role": "assistant", "content": null, "tool_calls": [{"function": {"name": "search_flights", "arguments": "{\"from\": \"NYC\", \"to\": \"LHR\"}"}}]},
    {"role": "tool", "name": "search_flights", "content": "{\"flights\": [{\"airline\": \"BA\", \"price\": 450}, {\"airline\": \"AA\", \"price\": 520}]}"},
    {"role": "assistant", "content": "I found flights from NYC to London. The cheapest is British Airways at $450."}
  ]
}

El convertidor de Potato maneja estas diferencias. Solo necesitas especificar el nombre correcto del convertidor.

Paso 2: Crea la Configuración del Proyecto

Crea config.yaml:

yaml
task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task
 
# --- Agentic annotation settings ---
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: 400
    show_step_numbers: true
    show_timestamps: false
    render_json: true
    syntax_highlight: true

Esto le dice a Potato que:

  1. Cargue las trazas desde data/traces.jsonl
  2. Use el convertidor ReAct para analizar el campo trace
  3. Muestre las trazas usando la visualización de trazas de agente con tarjetas de pasos codificadas por color

Paso 3: Diseña Tus Esquemas de Anotación

La evaluación de agentes típicamente necesita tanto juicios a nivel de traza (¿tuvo éxito el agente?) como juicios a nivel de paso (¿fue correcto cada paso?). Agreguemos ambos.

Añade lo siguiente a config.yaml:

yaml
annotation_schemes:
  # --- Trace-level schemas ---
 
  # 1. Task success (the most important metric)
  - annotation_type: radio
    name: task_success
    description: "Did the agent successfully complete the task?"
    labels:
      - "Success"
      - "Partial Success"
      - "Failure"
    label_requirement:
      required: true
    sequential_key_binding: true
 
  # 2. Answer correctness (if the task has a ground truth)
  - annotation_type: radio
    name: answer_correctness
    description: "Is the agent's final answer factually correct?"
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Cannot Determine"
    label_requirement:
      required: true
 
  # 3. Efficiency rating
  - annotation_type: likert
    name: efficiency
    description: "Did the agent use an efficient path to the answer?"
    min: 1
    max: 5
    labels:
      1: "Very Inefficient (many unnecessary steps)"
      3: "Average"
      5: "Optimal (no wasted steps)"
 
  # 4. Free-text notes
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations"
    label_requirement:
      required: false
 
  # --- Step-level schemas ---
 
  # 5. Per-step correctness
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    description: "Was this step correct and useful?"
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Unnecessary"
 
  # 6. Per-step error type (only shown when step is not correct)
  - annotation_type: per_turn_rating
    name: error_type
    target: agentic_steps
    description: "What type of error occurred?"
    rating_type: multiselect
    labels:
      - "Wrong tool/action"
      - "Wrong arguments"
      - "Hallucinated information"
      - "Reasoning error"
      - "Redundant step"
      - "Premature termination"
      - "Other"
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]

Este diseño de esquema te da:

  • Una métrica binaria de éxito/fallo para análisis de alto nivel
  • Una calificación de corrección para evaluar la respuesta final
  • Una puntuación de eficiencia para comparar estrategias de agentes
  • Calificaciones por paso para identificar exactamente dónde fallan los agentes
  • Una taxonomía de errores condicional que solo aparece cuando un paso tiene un problema

Paso 4: Configura la Salida e Inicia el Servidor

Añade la configuración de salida a config.yaml:

yaml
output_annotation_dir: "output/"
output_annotation_format: "jsonl"
 
# Optional: also export to Parquet for analysis
parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd

config.yaml completo de referencia:

yaml
task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task
 
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: 400
    show_step_numbers: true
    render_json: true
    syntax_highlight: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    description: "Did the agent successfully complete the task?"
    labels: ["Success", "Partial Success", "Failure"]
    label_requirement:
      required: true
    sequential_key_binding: true
 
  - annotation_type: radio
    name: answer_correctness
    description: "Is the agent's final answer factually correct?"
    labels: ["Correct", "Partially Correct", "Incorrect", "Cannot Determine"]
    label_requirement:
      required: true
 
  - annotation_type: likert
    name: efficiency
    description: "Did the agent use an efficient path?"
    min: 1
    max: 5
    labels:
      1: "Very Inefficient"
      3: "Average"
      5: "Optimal"
 
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations"
    label_requirement:
      required: false
 
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    description: "Was this step correct?"
    rating_type: radio
    labels: ["Correct", "Partially Correct", "Incorrect", "Unnecessary"]
 
  - annotation_type: per_turn_rating
    name: error_type
    target: agentic_steps
    description: "Error type"
    rating_type: multiselect
    labels:
      - "Wrong tool/action"
      - "Wrong arguments"
      - "Hallucinated information"
      - "Reasoning error"
      - "Redundant step"
      - "Premature termination"
      - "Other"
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"
 
parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd

Inicia el servidor:

bash
potato start config.yaml -p 8000

Abre http://localhost:8000 en tu navegador.

Paso 5: El Flujo de Trabajo de Anotación

Cuando un anotador abre una traza, ve:

  1. Descripción de la tarea en la parte superior (la consulta original del usuario)
  2. Tarjetas de pasos mostrando la traza completa del agente, codificadas por color según el tipo:
    • Tarjetas moradas para pensamientos/razonamiento
    • Tarjetas azules para acciones/llamadas a herramientas
    • Tarjetas verdes para observaciones/resultados
    • Tarjetas rojas para errores
  3. Controles de calificación por paso junto a cada tarjeta de paso
  4. Esquemas a nivel de traza debajo de la visualización de la traza

El flujo de trabajo típico:

  1. Leer la descripción de la tarea para entender qué se suponía que debía hacer el agente
  2. Recorrer los pasos de la traza, calificando cada uno
  3. Para cualquier paso calificado como "Parcialmente Correcto" o "Incorrecto", seleccionar el tipo(s) de error
  4. Calificar la traza general (éxito, corrección, eficiencia)
  5. Agregar notas si es necesario
  6. Enviar y pasar a la siguiente traza

Consejos para Anotadores

  • Expande las observaciones colapsadas para verificar que el agente procesó la información correctamente
  • Compara la respuesta final con la verdad de referencia (si está disponible) antes de calificar el éxito de la tarea
  • Califica los pasos "Innecesarios" por separado de los "Incorrectos" -- un paso innecesario desperdicia esfuerzo pero no introduce errores
  • Usa la línea temporal de pasos en la barra lateral para saltar a pasos específicos en trazas largas

Paso 6: Análisis de Resultados

Después de la anotación, analiza los resultados programáticamente.

Análisis Básico con pandas

python
import pandas as pd
import json
 
# Load annotations
annotations = []
with open("output/annotations.jsonl") as f:
    for line in f:
        annotations.append(json.loads(line))
 
df = pd.DataFrame(annotations)
 
# Task success rate
success_counts = df.groupby("annotations").apply(
    lambda x: x.iloc[0]["annotations"]["task_success"]
).value_counts()
print("Task Success Distribution:")
print(success_counts)
 
# Average efficiency rating
efficiency_scores = [
    a["annotations"]["efficiency"]
    for a in annotations
    if "efficiency" in a["annotations"]
]
print(f"\nAverage Efficiency: {sum(efficiency_scores) / len(efficiency_scores):.2f}")

Análisis de Errores a Nivel de Paso

python
# Collect all step-level errors
error_counts = {}
for ann in annotations:
    step_errors = ann["annotations"].get("error_type", {})
    for step_idx, errors in step_errors.items():
        for error in errors:
            error_counts[error] = error_counts.get(error, 0) + 1
 
print("Error Type Distribution:")
for error, count in sorted(error_counts.items(), key=lambda x: -x[1]):
    print(f"  {error}: {count}")

Análisis con DuckDB (vía Parquet)

python
import duckdb
 
# Overall success rate
result = duckdb.sql("""
    SELECT value, COUNT(*) as count
    FROM 'output/parquet/annotations.parquet'
    WHERE schema_name = 'task_success'
    GROUP BY value
    ORDER BY count DESC
""")
print(result)

Paso 7: Escalamiento

Para proyectos de evaluación más grandes (cientos o miles de trazas), considera estas configuraciones:

Múltiples Anotadores

Asigna múltiples anotadores por traza para el acuerdo entre anotadores:

yaml
annotation_task_config:
  total_annotations_per_instance: 3
  assignment_strategy: random

Uso de Esquemas Pre-construidos

Para una configuración rápida, usa los esquemas de evaluación de agentes pre-construidos de Potato:

yaml
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy
  - preset: agent_efficiency

Control de Calidad

Habilita instancias de referencia para monitoreo de calidad:

yaml
phases:
  training:
    enabled: true
    data_file: "data/training_traces.jsonl"
    passing_criteria:
      min_correct: 4
      total_questions: 5

Adaptación para Otros Tipos de Agentes

OpenAI Function Calling

yaml
agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace

Anthropic Tool Use

yaml
agentic:
  enabled: true
  trace_converter: anthropic
  display_type: agent_trace

Sistemas Multi-Agente (CrewAI/AutoGen)

yaml
agentic:
  enabled: true
  trace_converter: multi_agent
  display_type: agent_trace
  multi_agent:
    agent_converters:
      researcher: react
      writer: anthropic
      reviewer: openai

Agentes de Navegación Web

Para agentes web, cambia a la visualización de agente web:

yaml
agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
  web_agent_display:
    screenshot_max_width: 900
    overlay:
      enabled: true
    filmstrip:
      enabled: true

Consulta Anotación de Agentes de Navegación Web para una guía dedicada.

Resumen

La evaluación humana de agentes de IA requiere herramientas especializadas. El sistema de anotación agéntica de Potato proporciona:

  • 12 convertidores para normalizar trazas de cualquier framework
  • 3 tipos de visualización optimizados para agentes de uso de herramientas, navegación web y conversacionales
  • Calificaciones por turno para evaluación a nivel de paso
  • 9 esquemas pre-construidos que cubren dimensiones de evaluación comunes
  • Exportación Parquet para análisis eficiente downstream

La idea clave es que la evaluación de agentes no es solo "¿obtuvo el agente la respuesta correcta?" -- es "¿razonó el agente correctamente en cada paso?" La anotación por pasos revela patrones de error que las métricas agregadas no detectan.

Lectura Adicional