Capa 2: Triaje de errores del agente

Después de interpretar las puntuaciones de la evaluación e identificar las áreas de enfoque, determine por qué fallaron los casos de prueba individuales y quién debe actuar.

Este artículo proporciona una guía estructurada para diagnosticar errores en el nivel de caso de prueba. Ayuda a clasificar la causa raíz, distinguir entre problemas de agente, evaluación e infraestructura, y elegir la acción siguiente adecuada.

Antes de comenzar

Antes de comenzar el triaje de errores:

1. Complete la interpretación de puntuación y la evaluación de preparación, e identifique qué conjuntos de evaluación requieren atención.
2. Céntrese en los errores de mayor prioridad según la preparación y el riesgo.

Comprobación previa al triaje: verificar el estado de la infraestructura

Antes de diagnosticar errores individuales, confirme que las dependencias estaban en buen estado durante la ejecución de la evaluación. Los problemas de infraestructura pueden producir errores que parecen problemas del agente o de la evaluación, pero no están relacionados con ellos.

Compruebe las condiciones siguientes:

• Las fuentes de conocimientos son accesibles y están completamente indexadas.
• Los conectores o back-ends de API no devuelven errores, tiempos de espera ni respuestas de límite de tasa.
• Los tokens de autenticación son válidos durante toda la ejecución.
• El entorno de evaluación coincide con la configuración prevista del agente.

Si una dependencia es incorrecta, corrija el problema y vuelva a ejecutar la evaluación antes de continuar. Evaluar los resultados de una ejecución incorrecta puede generar conclusiones incorrectas.

Paso 0: Priorizar errores

Antes de priorizar casos de prueba individuales, decida dónde centrarse primero.

Priorice los errores en este orden:

Si tiene muchos errores (por ejemplo, más de 15), no realice triaje de cada error individualmente. Comience con el conjunto de evaluación de menor puntuación y revise manualmente algunos errores. Si comparten una causa raíz, resolverla puede solucionar muchos errores a la vez.

Identifique la señal de calidad de una prueba fallida

Si un resultado de evaluación muestra un caso de prueba fallido pero no identifica claramente la señal de calidad, use el conjunto de evaluación y el método de calificación para inferir la señal.

Por ejemplo:

• El conjunto de evaluación indica el área de capacidad, como la seguridad, la fundamentación o el uso de herramientas.
• El método de calificación, como la coincidencia de palabras clave o la puntuación basada en rúbricas, proporciona más contexto.

Identificar la señal de calidad prevista ayuda a elegir las preguntas diagnósticas más relevantes.

Paso 1: Verificar la configuración de evaluación

Para cada error, revise manualmente la respuesta real del agente junto con el valor esperado y el método de calificación.

Siga estas preguntas en orden. Deténgase cuando llegue a un resultado.

1. ¿Es aceptable la respuesta del agente? ¿Estaría un usuario real satisfecho con esta respuesta, aunque no haya superado la evaluación?

   • Si la respuesta es Sí, la configuración de evaluación tiene un problema: el evaluador o el valor esperado son incorrectos.
   • Si la respuesta es No, continúe con la siguiente pregunta.

2. ¿La respuesta esperada es actual y precisa respecto al origen?

   • Si la respuesta es Sí, continúe con la siguiente pregunta.
   • Si es No, la configuración de evaluación tiene un problema: la respuesta esperada está desactualizada o es incorrecta.

3. ¿El caso de prueba refleja una entrada realista del usuario?

   • Si la respuesta es Sí, continúe con la siguiente pregunta.
   • Si la respuesta No, la configuración de evaluación tiene un problema: el caso de prueba es poco realista.

4. ¿Podría ser correcta una respuesta alternativa razonable, pero el evaluador no lo permite?

   • Si la respuesta es Sí, la configuración de la evaluación tiene un problema: el evaluador es demasiado rígido y no tiene en cuenta las variaciones válidas.
   • Si la respuesta es No, continúe con la siguiente pregunta.

5. ¿Es apropiado el método de evaluación para la prueba que está realizando?

   • Si la respuesta es Sí, la evaluación es válida. Continúe con el Paso 2: Diagnosticar el agente.
   • Si es No, la configuración de evaluación tiene un problema: el método de evaluación no es adecuado para esta señal de calidad.

Determinar la aceptabilidad de la respuesta

Utilice las siguientes señales para ayudar a determinar si la respuesta del agente es aceptable:

• Los mismos datos clave, diferente redacción → A menudo es aceptable (el calificador podría ser demasiado rígido).
• Ausencia de información crítica en el origen → A menudo no es aceptable.
• El umbral de "suficientemente bueno" ambiguo → los criterios de aceptación podrían ser poco claros (marca para el paso 4).

En caso de duda, compare el contenido con la fuente original, no únicamente con la respuesta esperada.

Estas señales guían su criterio, pero no lo sustituyen.

Tipos comunes de errores en la configuración de evaluación

Validación del calificador

La fiabilidad del evaluador es un requisito previo para un triaje fiable. Si el propio calificador no es confiable, se diagnostica incorrectamente cada fallo que toca.

Para validar la fiabilidad del evaluador:

1. Seleccione de 5 a 10 casos de prueba donde conozca el resultado correcto de aprobado/suspenso por revisión manual.
2. Realice la evaluación y compare el resultado del evaluador con el veredicto manual.
3. Si el calificador no está de acuerdo con más del 20 % de los casos, vuelva a calibrar el calificador antes de depurar el agente.

Señales de que un calificador necesita atención

• El mismo caso de prueba produce diferentes veredictos a lo largo de las ejecuciones.
• Los fallos se agrupan en conjuntos de evaluación que utilizan calificación basada en modelos, mientras que los métodos deterministas aprueban.
• El calificador marca los problemas que no puede reproducir revisando la respuesta del agente.

Opciones de recalibración del evaluador:

• Utilice métodos deterministas siempre que sea posible.
• Agregue ejemplos explícitos de "aceptable" y "no aceptable" a la rúbrica.
• Amplíe los conjuntos de palabras clave para incluir sinónimos y reformulaciones válidas.
• Use Comparar significado en lugar de Coincidencia de palabras clave (Todas) para comprobaciones de equivalencia semántica.

Paso 2: Diagnosticar el agente

En este punto, la evaluación es válida y el agente dio una respuesta incorrecta. Diagnostique qué falló en la configuración del agente.

Revise la exactitud factual y los errores de fundamentación del conocimiento

Compruebe si hay errores de invocación de herramientas

Comprobar errores de enrutamiento de desencadenador

Comprobar errores de calidad de tono y respuesta

Comprobar si hay errores de seguridad y límites

Comprobar la escalación y el fallo controlado

Después del diagnóstico, asigne patrones de error a estrategias de corrección por causa raíz.

Paso 3: Identificar las limitaciones de la plataforma

Si la evaluación es correcta y los cambios de configuración razonables no mejoran los resultados, el problema podría ser una limitación de la plataforma.

Indicadores de limitación de plataforma

Ruta de acción para limitaciones de plataforma

1. Documente claramente la limitación (lo que falla, lo que se intentó y evidencia de que no está relacionado con la configuración).
2. Aplique una solución alternativa cuando sea posible (por ejemplo, reestructure el documento fuente para mejorar la recuperación).
3. Marque el caso de prueba como una limitación conocida o ajuste umbrales para que no bloquee el progreso no relacionado.
4. Escale con evidencia al equipo de la plataforma.
5. Realice un seguimiento del elemento en el registro de errores para su reevaluación cuando se actualicen las capacidades de la plataforma.

Después de clasificar, revise las orientaciones alternativas y de escalación para responder a las limitaciones de la plataforma.

Cuando un error no encaja en el marco

Algunos errores no se ajustan claramente a un solo tipo de causa raíz. Algunos ejemplos habituales:

• Problemas de calidad de datos de back-end: el contenido del origen de conocimiento es técnicamente correcto, pero está escrito de manera ambigua, de modo que ni el agente ni la evaluación son incorrectos.
• Problemas intermitentes de infraestructura: tiempos de espera de red, limitación de velocidad de la API y problemas de conectores que no se reproducen de manera consistente.
• Cambios en la versión del modelo: el comportamiento del agente cambió después de una actualización del modelo de la plataforma que no inició usted.
• Casos de prueba ambiguos: el escenario es ambiguo y las personas razonables difieren sobre la respuesta correcta.

Enfoque sugerido: documente lo que ha observado (el error, la respuesta del agente, lo que ha comprobado). Registre el elemento como "sin clasificar" en el registro de errores. Si el error se repite, a menudo se vuelve clasificable con evidencia adicional.

Control de causas compuestas

Un solo error puede tener múltiples causas raíz que contribuyen. Por ejemplo:

• Un error de precisión factual donde la respuesta esperada está ligeramente desactualizada (configuración de evaluación) y la fuente de conocimientos también está incompleta (configuración del agente).
• Un error en la invocación de herramientas donde la descripción de la herramienta es ambigua (configuración del agente) y la orquestación no admite llamadas condicionales a herramientas (limitación de plataforma).

Enfoque sugerido: realice el triaje completo para cada error. Si se aplican varios tipos de causas raíz, abórdelas en orden de prioridad:

1. Corrija la evaluación primero para obtener una señal clara sobre si el cambio del agente realmente ayuda.
2. Corrija la configuración del agente para determinar si el error restante es realmente un problema de plataforma.
3. Documente la limitación de la plataforma solo después de que se hayan abordado los pasos 1 y 2.

Vuelva a ejecutar los casos de prueba afectados después de cada cambio antes de continuar.

Control de errores de conversación multiturno

En escenarios de varios turnos, los errores solo surgen entre turnos.

Cuándo sospechar un problema de varios turnos

• El agente responde correctamente en los primeros turnos, pero se contradice en turnos posteriores.
• El agente pierde el contexto de una llamada de herramienta anterior o la recuperación de conocimiento en un turno posterior.
• El momento de escalación solo tiene sentido si se tiene en cuenta el historial completo de la conversación.
• El tono del agente se degrada progresivamente a medida que la conversación se alarga.
• El agente pide información que el usuario ya proporcionó.

Preguntas diagnósticas adicionales

Guía de remediación para problemas de varios turnos

• Pérdida de contexto: verifique la configuración del estado de la conversación. Asegúrese de que los resultados de las herramientas y los datos clave persistan a lo largo de los turnos.
• Contradicciones: agregue una instrucción de coherencia, como: "Mantenga la coherencia con sus respuestas anteriores en esta conversación."
• Volver a preguntar: verifique la configuración de la memoria de conversación de la plataforma.
• Degradación de conversaciones largas: considere estrategias de resumen de conversación o de reducción de contexto.

Validación de casos de prueba aprobados (comprobación de falso positivo)

Este marco se centra en casos de prueba que fallan. Sin embargo, un caso de prueba que se supere incorrectamente puede crear brechas de calidad ocultas.

Práctica recomendada: revise manualmente el 5-10 % de los casos de test por cada ejecución de evaluación, especialmente para:

• Calificación basada en modelos (mayor riesgo de falsos positivos)
• Señales subjetivas (tono, utilidad)
• Pruebas que anteriormente fallaban y ahora pasan tras un cambio

Si encuentra falsos positivos, recalibre el evaluador.

Pasos siguientes

Tras completar el triaje de errores:

• Use Capa 3: Asignar patrones de error a estrategias de corrección.
• Use Capa 4: Analizar patrones para identificar problemas sistémicos.
• Revise ejemplos prácticos que demuestran cómo las capas del marco funcionan juntas en escenarios del mundo real.