Evalúe agentes de IA con eventos estructurados y SQL

Un agente puede terminar una ejecución sin cumplir la tarea. Registre la ejecución, las llamadas a modelos y herramientas que necesite analizar y el resultado de la evaluación como eventos separados. SQL permite comparar calidad, costo, latencia, reintentos y transferencias a personas por versión. Contraste las puntuaciones generadas por modelos con otras pruebas antes de darlas por correctas.

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.

Cada operation_id debe ser único entre versiones.

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,
  isFinal,
  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,
    is_final: isFinal,
    dataset_version: datasetVersion,
    prompt_version: promptVersion,
    release,
  });
}

Marca isFinal como true solo en la decisión definitiva para esa operación, métrica, versión del evaluador y versión del producto. Que el agente haya terminado no implica que la revisión sea definitiva.

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

Este ejemplo admite una sola revisión con is_final = true por operación, versión, métrica y versión del evaluador. Las revisiones preliminares llevan is_final = false. Si hay que corregir una decisión definitiva, usa otra versión del evaluador o un evento de finalización independiente. La consulta excluye las decisiones definitivas duplicadas y solo cuenta operaciones completadas; investiga los duplicados antes de interpretar la cobertura o la tasa de aprobación.

WITH completed AS (
  SELECT release, operation_id
  FROM agent_run_completed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
    AND status = 'success'
  GROUP BY release, operation_id
),
final_reviews AS (
  SELECT release, operation_id, MAX(score) AS score,
    MAX(CASE WHEN passed THEN 1 ELSE 0 END) AS passed
  FROM ai_output_reviewed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
    AND metric_name = 'task_quality'
    AND evaluator_version = 'quality-rubric-v3'
    AND is_final = true
  GROUP BY release, operation_id
  HAVING COUNT(*) = 1
)
SELECT
  c.release,
  COUNT(*) AS completed_operations,
  COUNT(f.operation_id) AS evaluated_operations,
  ROUND(
    100.0 * COUNT(f.operation_id)
    / NULLIF(COUNT(*), 0),
    1
  ) AS evaluation_coverage_pct,
  ROUND(
    100.0 * SUM(CASE WHEN f.passed = 1 THEN 1 ELSE 0 END)
    / NULLIF(COUNT(f.operation_id), 0),
    1
  ) AS evaluated_pass_rate_pct,
  ROUND(AVG(f.score), 3) AS average_final_score
FROM completed c
LEFT JOIN final_reviews f
  ON f.release = c.release AND f.operation_id = c.operation_id
GROUP BY c.release
ORDER BY c.release;

Antes de usar el resultado para decidir sobre una versión, comprueba las revisiones definitivas duplicadas que la consulta excluyó:

SELECT release, operation_id, COUNT(*) AS conflicting_final_reviews
FROM ai_output_reviewed
WHERE timestamp_utc >= now() - INTERVAL '30 days'
  AND metric_name = 'task_quality'
  AND evaluator_version = 'quality-rubric-v3'
  AND is_final = true
GROUP BY release, operation_id
HAVING COUNT(*) > 1
ORDER BY release, operation_id;

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

Suma primero el coste por operación y únelo a una sola decisión definitiva. Aquí operation_id es único entre versiones; si no lo es en tu sistema, incluye release en ambas claves. Las decisiones definitivas duplicadas se excluyen y deben investigarse.

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'
    AND metric_name = 'task_quality'
    AND evaluator_version = 'quality-rubric-v3'
    AND is_final = true
  GROUP BY operation_id
  HAVING COUNT(*) = 1
)
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.