Anotación de Agentes

Evalúa agentes de IA con visualizaciones de trazas especializadas, 12 convertidores de formato y esquemas de anotación diseñados específicamente.

Anotación de Agentes

Nuevo en v2.3.0

Los agentes de IA se despliegan cada vez más para tareas complejas de múltiples pasos: navegar por la web, escribir código, llamar APIs y orquestar sub-agentes. Pero evaluar si un agente realmente hizo lo correcto requiere juicio humano a una granularidad que las herramientas de anotación tradicionales no pueden soportar. Una sola traza de agente puede contener docenas de pasos, llamadas a herramientas, razonamiento intermedio, capturas de pantalla y decisiones de ramificación. Los anotadores necesitan ver todo este contexto, navegarlo eficientemente y proporcionar evaluaciones estructuradas tanto a nivel de traza como a nivel de paso individual.

El sistema de anotación de agentes de Potato aborda esto con tres capacidades:

12 convertidores de formato de trazas que normalizan registros de agentes de cualquier framework principal a un formato unificado
3 tipos de visualización especializados optimizados para diferentes modalidades de agentes (uso de herramientas, navegación web, chat)
9 esquemas de anotación preconstruidos que cubren las dimensiones de evaluación de agentes más comunes

Convertidores de Formato de Trazas

Las trazas de agentes vienen en formatos muy diferentes dependiendo del framework. Potato incluye 12 convertidores que las normalizan en una representación interna unificada. Especificas el convertidor en tu configuración, o dejas que Potato detecte automáticamente el formato.

Referencia de Convertidores

Convertidor	Formato de Origen	Campos Clave Extraídos
`openai`	OpenAI Assistants API / function calling logs	messages, tool_calls, function results
`anthropic`	Anthropic Claude tool_use / Messages API	content blocks, tool_use, tool_result
`swebench`	SWE-bench task traces	patch, test results, trajectory
`opentelemetry`	OpenTelemetry span exports (JSON)	spans, attributes, events, parent-child
`mcp`	Model Context Protocol sessions	tool definitions, call/response pairs
`multi_agent`	CrewAI / AutoGen / LangGraph multi-agent logs	agent roles, delegation, message passing
`langchain`	LangChain callback traces	chain runs, LLM calls, tool invocations
`langfuse`	LangFuse observation exports	generations, spans, scores
`react`	ReAct-style Thought/Action/Observation logs	thought, action, action_input, observation
`webarena`	WebArena / VisualWebArena trace JSON	actions, screenshots, DOM snapshots, URLs
`atif`	Agent Trace Interchange Format (ATIF)	steps, observations, metadata
`raw_web`	Raw browser recordings (HAR + screenshots)	requests, responses, screenshots, timings

Configuración

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

yaml

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

Cada línea en el archivo de trazas debe ser un objeto JSON que contenga la traza cruda del agente. El convertidor se encarga del resto.

Para trazas multi-agente donde diferentes agentes usan diferentes frameworks, puedes especificar convertidores por agente:

yaml

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é convertidor usar, establece trace_converter: auto:

yaml

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

Potato inspecciona las primeras 10 trazas y selecciona el convertidor que mejor coincida basándose en las firmas de campos. Se registra una advertencia si la confianza está por debajo del 80%, en cuyo caso debes especificar el convertidor explícitamente.

Convertidores Personalizados

Si tu framework de agentes no está en la lista, puedes escribir un convertidor en Python:

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:

yaml

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

Tipos de Visualización

Una vez que las trazas son convertidas, Potato las renderiza usando uno de tres 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 de colores por tipo de paso.

yaml

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 coloreado indicando el tipo (pensamiento, acción, observación, error)
Secciones colapsables para observaciones largas o salidas de herramientas (umbral configurable)
Formato JSON para argumentos de llamadas a herramientas y respuestas estructuradas
Resaltado de sintaxis para bloques de código en observaciones
Línea de tiempo de pasos en la barra lateral mostrando la traza completa de un vistazo
Navegación saltar-a-paso para trazas largas

2. Visualización de Traza de Agente Web

Diseñada específicamente para agentes de navegación web (WebArena, VisualWebArena, grabaciones de navegador crudas). Renderiza capturas de pantalla con superposiciones SVG mostrando dónde el agente hizo clic, escribió o se desplazó.

yaml

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 vista a tamaño completo y zoom
Superposiciones SVG mostrando objetivos de clic (círculos rojos), regiones de entrada de texto (resaltados azules) y direcciones de desplazamiento
Vista de tira de película en la parte inferior mostrando todas las capturas como miniaturas para navegación rápida
Descripción de acción texto debajo de cada captura (ej., "Clic en el botón 'Agregar al Carrito'")
Barra de URL mostrando la URL de la página actual en cada paso
Comparación antes/después para pasos que modifican el contenido de la página

3. Visualización de Chat Interactivo

Para evaluar agentes conversacionales y chatbots. Soporta dos sub-modos: 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.

yaml

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 opcionales y latencia por mensaje. Los anotadores pueden calificar 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 abajo). Los anotadores conversan con el agente y luego anotan la conversación resultante.

Calificaciones por Turno

Para evaluaciones de diálogo y de múltiples pasos, frecuentemente necesitas calificaciones en turnos individuales además de (o en lugar de) la traza general. Potato soporta anotación por turno para cualquier tipo de visualización.

yaml

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 calificaciones por turno aparecen en línea junto a cada tarjeta de paso. El bloque conditional te permite mostrar preguntas de seguimiento solo cuando se seleccionan ciertas calificaciones, manteniendo la interfaz limpia.

Formato de Salida por Turno

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

json

{
  "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 donde 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 revisión posterior.

yaml

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

Proxy de OpenAI reenvía mensajes a una API compatible con OpenAI:

yaml

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

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

yaml

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

Proxy de eco devuelve el mensaje del usuario (útil para pruebas y desarrollo de UI):

yaml

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

Esquemas de Anotación Preconstruidos

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

Esquema	Tipo	Descripción
`agent_task_success`	radio	Éxito/fracaso binario con opción de crédito parcial
`agent_step_correctness`	per_turn_rating (radio)	Calificaciones por paso: correcto/incorrecto/innecesario
`agent_error_taxonomy`	per_turn_rating (multiselect)	Taxonomía de errores de 12 categorías (herramienta incorrecta, alucinación, bucle, etc.)
`agent_safety`	radio + text	Detección de violaciones de seguridad con escala de gravedad
`agent_efficiency`	likert	Calificar si el agente usó una ruta eficiente
`agent_instruction_following`	likert	Calificar adherencia a la instrucción original del usuario
`agent_explanation_quality`	likert	Calificar calidad del razonamiento/explicaciones del agente
`agent_web_action_correctness`	per_turn_rating (radio)	Evaluación por paso de acciones web (objetivo correcto, tipo de acción correcto)
`agent_conversation_quality`	multirate	Calidad de chat multidimensional (utilidad, precisión, tono, seguridad)

Carga un esquema preconstruido por nombre:

yaml

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

O combina presets con esquemas personalizados:

yaml

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í hay una configuración completa para evaluar trazas de agentes estilo ReAct con calificaciones por paso:

yaml

# 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):

json

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

bash

potato start config.yaml -p 8000

Lectura Adicional

Evaluando Agentes de IA: Una Guía Completa -- tutorial completo de un proyecto de evaluación de agentes
Anotando Agentes de Navegación Web -- guía para evaluación de agentes web con capturas de pantalla y superposiciones
Modo Solo -- combina anotación de agentes con etiquetado colaborativo humano-LLM
Calificaciones por Turno para Diálogo -- opciones adicionales de calificación por turno
Formatos de Exportación -- exportar datos de evaluación de agentes

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