Evalúe agentes de IA con eventos estructurados y SQL

La evaluación del agente de IA es útil cuando distingue una ejecución técnicamente completada de un resultado que realmente cumplió con la tarea. Un diseño confiable registra eventos compactos para la ejecución, cualquier modelo o actividad de herramienta que valga la pena analizar y el resultado de la evaluación posterior. Luego, SQL puede comparar la calidad, el costo, la latencia, los reintentos y las transferencias humanas mediante la liberación sin tratar un rastro o una puntuación generada por el modelo como verdad sobre el terreno.

Telemetry es la capa de análisis en este flujo de trabajo. No ejecuta anotadores, no administra versiones de avisos, no selecciona conjuntos de datos de evaluación ni proporciona repetición de avisos y finalización. Mantenga esos flujos de trabajo en su aplicación o en un sistema de evaluación dedicado, luego envíe los campos de resultados aprobados necesarios para el análisis agregado.

Definir primero la unidad de evaluación

Elija la fila que responde "¿qué recibió una puntuación?" antes de elegir métricas. Las unidades comunes incluyen:

• una respuesta final mostrada a un usuario;
• una ejecución de agente completa;
• un caso de soporte resuelto;
• una decisión de selección de herramienta;
• una respuesta recuperada frente a un ejemplo congelado;
• una operación comercial que puede incluir varios intentos de agentes.

Asigne a esa unidad un identificador estable como operation_id. Utilice identificadores separados para run_id, response_id y evaluation_id. Un reintento puede crear varias ejecuciones para una operación y una salida puede recibir varias evaluaciones. Reutilizar un único identificador para cada grano produce uniones incorrectas y costos contabilizados dos veces.

Eventos de ejecución, solicitud y evaluación separados

Un contrato inicial práctico utiliza tres o cuatro tablas de eventos:

No fuerces los cuatro granos en una fila ancha. De lo contrario, una ejecución con cinco intentos de herramientas y dos evaluaciones multiplicaría los costos o el recuento de éxitos cuando se uniera.

Utilice varios tipos de evidencia.

Ningún evaluador es suficiente para cada flujo de trabajo de los agentes. Combina sólo las señales que corresponden a una decisión real:

1. Comprobaciones deterministas verifican esquemas, citas requeridas, opciones de herramientas permitidas, cálculos exactos, reglas de políticas o estado terminal conocido.
2. Revisión humana captura una rúbrica limitada como correcta, parcialmente correcta, insegura o necesita escalamiento. Registre la rúbrica y el proceso del revisor, no las notas privadas del revisor.
3. La puntuación basada en modelos puede aplicar una rúbrica repetible en mayor volumen. Versione el modelo de juez, las instrucciones y los umbrales, y compare periódicamente la puntuación con la revisión humana.
4. Resultados del producto registra si el usuario aceptó, guardó, corrigió, regeneró, elevó o abandonó el resultado.

Un juez de LLM es un instrumento de medición, no una etiqueta objetiva. Realice un seguimiento de los desacuerdos, las evaluaciones faltantes y los cambios en la configuración de los jueces. Conceptos de evaluación de Langfuse y Documentación de evaluación de Arize Phoenix describen flujos de trabajo de evaluación adicionales que pueden permanecer aguas arriba de Telemetry.

Emitir un evento de resultado revisado

Este ejemplo de JavaScript envía un resultado de evaluador compacto una vez finalizado el flujo de trabajo del evaluador o de la revisión humana:

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

export async function recordAgentEvaluation({
  operationId,
  evaluationId,
  evaluatorType,
  evaluatorVersion,
  metricName,
  score,
  threshold,
  reviewOutcome,
  datasetVersion,
  promptVersion,
  release,
}) {
  await telemetry.log("ai_output_reviewed", {
    operation_id: operationId,
    evaluation_id: evaluationId,
    evaluator_type: evaluatorType,
    evaluator_version: evaluatorVersion,
    metric_name: metricName,
    score,
    threshold,
    passed: score >= threshold,
    review_outcome: reviewOutcome,
    dataset_version: datasetVersion,
    prompt_version: promptVersion,
    release,
  });
}

Mantenga las indicaciones sin procesar, las completaciones, los documentos recuperados, los argumentos de las herramientas, los secretos y las notas del revisor de formato libre fuera del evento de forma predeterminada. Prefiere categorías estables e identificadores de versión. Si se aprueba la retención de contenido, guárdelo en el sistema diseñado para esa política de acceso y eliminación y correlacionelo con un identificador restringido.

Comparar calidad por lanzamiento

Esta consulta calcula la cobertura y la tasa de aprobación para una única métrica. El recuento de evaluación explícito evita que una publicación no evaluada parezca artificialmente exitosa.

WITH run_counts AS (
  SELECT
    release,
    COUNT(DISTINCT operation_id) AS completed_operations
  FROM agent_run_completed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
    AND status = 'success'
  GROUP BY release
),
evaluation_counts AS (
  SELECT
    release,
    COUNT(DISTINCT operation_id) AS evaluated_operations,
    COUNT(DISTINCT CASE WHEN passed THEN operation_id END) AS passed_operations,
    AVG(score) AS average_score
  FROM ai_output_reviewed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
    AND metric_name = 'task_quality'
    AND evaluator_version = 'quality-rubric-v3'
  GROUP BY release
)
SELECT
  r.release,
  r.completed_operations,
  COALESCE(e.evaluated_operations, 0) AS evaluated_operations,
  ROUND(
    100.0 * COALESCE(e.evaluated_operations, 0)
    / NULLIF(r.completed_operations, 0),
    1
  ) AS evaluation_coverage_pct,
  ROUND(
    100.0 * COALESCE(e.passed_operations, 0)
    / NULLIF(e.evaluated_operations, 0),
    1
  ) AS evaluated_pass_rate_pct,
  ROUND(e.average_score, 3) AS average_score
FROM run_counts r
LEFT JOIN evaluation_counts e ON e.release = r.release
ORDER BY r.release;

No compare publicaciones que utilizaron diferentes rúbricas, modelos de evaluación, umbrales, versiones de conjuntos de datos o reglas de muestreo sin separar esas dimensiones. Un cambio de puntuación después de un cambio de evaluador no es evidencia de una regresión del producto.

Calcular el costo por resultado aceptado

Costo agregado del proveedor al grano de operación antes de incorporarlo a un resultado terminal:

WITH operation_cost AS (
  SELECT
    operation_id,
    SUM(estimated_cost_usd) AS total_cost_usd
  FROM llm_request_completed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
  GROUP BY operation_id
),
terminal_outcome AS (
  SELECT
    operation_id,
    MAX(CASE WHEN review_outcome = 'accepted' THEN 1 ELSE 0 END) AS accepted
  FROM ai_output_reviewed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
  GROUP BY operation_id
)
SELECT
  COUNT(*) AS evaluated_operations,
  SUM(accepted) AS accepted_operations,
  ROUND(SUM(total_cost_usd), 4) AS evaluated_cost_usd,
  ROUND(
    SUM(total_cost_usd) / NULLIF(SUM(accepted), 0),
    4
  ) AS cost_per_accepted_operation_usd
FROM operation_cost c
JOIN terminal_outcome o ON o.operation_id = c.operation_id;

Esta métrica sólo es significativa cuando "aceptado" tiene una definición estable. Una respuesta copiada, una respuesta visible para el usuario, un caso resuelto sin reabrirse y un pase de rúbrica humana son resultados diferentes.

Construir una puerta de regresión

Para cada versión propuesta:

1. Ejecute el mismo conjunto de datos congelado con la misma configuración del evaluador.
2. Registre los candidatos release, prompt_version, dataset_version y evaluator_version.
3. Compare la tasa de aprobación, la tasa de fallas graves, la tasa de transferencia, la duración de p95 y el costo por operación aceptada con la línea base aprobada.
4. Inspeccionar ejemplos fallidos en el sistema de evaluación de fuentes.
5. Apruebe o rechace la versión utilizando umbrales elegidos antes de la ejecución.
6. Supervise los resultados de producción por separado porque un conjunto de datos congelado no puede representar todos los insumos en vivo.

Incluir tamaños mínimos de muestra e intervalos de confianza cuando la decisión lo amerite. Evite una alerta sobre un porcentaje con un denominador pequeño. También realice un seguimiento de la cobertura de la evaluación: una puntuación aprobatoria de más de 20 ejecuciones revisadas no describe 10,000 ejecuciones no revisadas.

Cuándo conservar una plataforma de evaluación dedicada

Utilice una plataforma especializada cuando el equipo necesite una inspección rápida y completa, curación de conjuntos de datos, colas de anotaciones, gestión de notificaciones, ejecución de experimentos, reproducción de seguimiento o evaluadores integrados. Telemetry puede recibir las puntuaciones versionadas resultantes y los resultados para el análisis SQL; no es un reemplazo característica por característica.

A continuación, utilice Receta de regresión de calidad de IA, éxito de la tarea del agente y receta de transferencia y receta de producción aceptada por dólar. Para conocer los límites de implementación más amplios, consulte Monitoreo de agentes de IA.