Cuando su agente de IA falla en producción, saber que falló es solo el comienzo. La pregunta más difícil es por qué falló y qué solucionar. La evaluación tradicional le dice "este agente obtuvo un 60 por ciento de cumplimiento de objetivos", pero le deja revisar manualmente los seguimientos de ejecución para comprender qué salió mal. Para los equipos que operan agentes a escala, este diagnóstico manual se convierte en el cuello de botella entre la detección de un problema y el envío de una solución. Los detectores del SDK de Strands Evals eliminan este cuello de botella al identificar automáticamente fallas en los seguimientos de ejecución del agente y realizar análisis de causa raíz, para que pueda reducir el tiempo de diagnóstico de horas a minutos.
En esta publicación, lo guiaremos a través de cómo llamar a las funciones del detector para diagnosticar fallas reales del agente. Aprenderá a interpretar su resultado estructurado: fallos categorizados con puntuaciones de confianza, cadenas causales que vinculan las causas fundamentales con los síntomas posteriores y recomendaciones de corrección que especifican si un cambio pertenece al mensaje del sistema o a las definiciones de herramientas. También aprenderá cómo integrar la detección en su proceso de evaluación para realizar un diagnóstico automatizado en cada ejecución de prueba.
Los detectores complementan el marco de evaluación presentado en una publicación anterior respondiendo no solo "¿qué tan bien le fue al agente?" pero también "¿por qué falló y cómo lo soluciono?"
Requisitos previos
Debe tener los siguientes requisitos previos para seguir esta publicación.
Python 3.10 o posterior. SDK de Strands Evals instalado con pip install strands-agents-evals. Acceso al modelo de Amazon Bedrock habilitado (los detectores utilizan análisis basado en modelos de lenguaje grande (LLM)). Para ejemplos de Amazon CloudWatch, credenciales de AWS configuradas con permisos logs:StartQuery y logs:GetQueryResults.
Por qué las puntuaciones por sí solas no son suficientes
El marco Strands Evals proporciona señales de calidad confiables a través de casos, experimentos y evaluadores: tasas de éxito de objetivos, precisión de selección de herramientas y puntuaciones de utilidad. Estos son importantes para captar regresiones y comprender el desempeño a nivel estadístico. Pero considere lo que sucede después de detectar una regresión. La tasa de éxito de los objetivos de su agente cae del 85 por ciento al 70 por ciento después de una implementación o después de cambios en los mensajes o herramientas en las pruebas de tiempo de compilación. Los evaluadores confirman la caída. ¿Y ahora qué?
Debe identificar qué comportamientos específicos causaron fallas, distinguir las causas raíz de los síntomas posteriores, determinar si la solución pertenece al indicador del sistema o a las definiciones de herramientas y priorizar por impacto. Este flujo de trabajo de diagnóstico tradicionalmente ha requerido que los ingenieros superiores inspeccionen manualmente los rastros tramo por tramo y correlacionen fallas en cientos de pasos, y este proceso no se escala.
Los detectores automatizan este flujo de trabajo. Los evaluadores responden "¿qué tan bien le fue al agente?" produciendo puntuaciones a nivel de cada caso. Los detectores responden "¿por qué falló?" produciendo diagnósticos a nivel por tramo con fallas categorizadas, cadenas causales y recomendaciones de reparación.
Cómo funcionan los detectores
La canalización del detector opera en dos fases, cada una impulsada por un análisis del seguimiento de ejecución basado en LLM. Consulte Comprender la observabilidad de los recursos de agentes en Amazon Bedrock AgentCore para obtener más información sobre sesiones, seguimientos y períodos de agentes.
Fase 1: la detección de fallas analiza cada intervalo de una sesión con una taxonomía de fallas integral organizada en nueve categorías principales: alucinaciones, acciones incorrectas, errores de orquestación, incumplimiento de las instrucciones de la tarea, errores de ejecución, errores de manejo del contexto, comportamiento repetitivo, problemas de salida de LLM y falta de coincidencia de configuración. Para cada falla identificada, devuelve la ubicación del tramo, una o más categorías, una puntuación de confianza y evidencia extraída del seguimiento.
Fase 2: El análisis de la causa raíz toma las fallas detectadas y rastrea las cadenas causales entre ellas. Un solo error ascendente a menudo deriva en múltiples fallas posteriores. El análisis de la causa raíz separa las causas de los síntomas. Clasifica la causalidad de cada falla (PRIMARIA, SECUNDARIA o TERCIARIA), determina el impacto de la propagación y genera recomendaciones de reparación categorizadas según el lugar al que pertenece la solución (indicador del sistema, descripción de la herramienta u otro).
Ambas fases manejan sesiones de diferentes tamaños a través de una estrategia escalonada: análisis directo para sesiones que se ajustan a la ventana de contexto del modelo de Detector seleccionado, poda de ruta de falla que retiene solo los tramos ancestros y descendientes para sesiones moderadamente grandes, y análisis fragmentado con fusión para sesiones muy grandes que divide el seguimiento en ventanas superpuestas y concilia los resultados.
El siguiente diagrama muestra el proceso de un extremo a otro con dos puntos de entrada que convergen en el mismo flujo de detección y análisis.
Figura: Tubería de detectores con puntos de entrada integrados e independientes que desembocan en la detección de fallas y el análisis de la causa raíz.
Comenzando con la detección de fallas
Los siguientes ejemplos utilizan un seguimiento de sesión del asistente de investigación de descubrimiento de fármacos que aparece en Evaluación de agentes de IA para la producción: una guía práctica para Strands Evals. El agente se basa en Strands Agents y Amazon Bedrock. Para seguir adelante, ejecute su agente con el seguimiento de OpenTelemetry habilitado y exporte la sesión como JSON, o use CloudWatchProvider que se muestra más adelante en esta publicación para obtener un seguimiento existente. Consulte Simulación de usuario en la documentación del SDK de Strands Agents para saber cómo configurar sesiones de seguimiento y exportación.
La función detect_failures toma un objeto Session (el formato de seguimiento estándar en Strands Evals) y devuelve fallas estructuradas. Cada falla incluye el lapso en el que ocurrió, una o más categorías de la taxonomía de fallas predefinida, una puntuación de confianza y evidencia extraída del seguimiento.
Lo siguiente es el resultado de un agente de investigación al que se le pidió "Investigar el impacto de los requisitos de energía para impulsar la IA en el mundo real". El agente encontró problemas de configuración de herramientas y se degradó progresivamente:
En una sola pasada, el detector identifica fallas en múltiples niveles: errores de ejecución (validación de parámetros de herramienta), problemas semánticos (alucinaciones por “conocimiento general”) y problemas de orquestación (desviación total del objetivo). Un solo tramo puede exhibir múltiples categorías de fallas, cada una con confianza y evidencia independientes.
Agregar análisis de causa raíz
Identificar fallas es útil, pero comprender por qué ocurrieron es lo que impulsa las correcciones. La función analyse_root_cause toma las fallas detectadas y rastrea las cadenas causales entre ellas, separando las causas raíz de los síntomas posteriores y recomendando dónde pertenece cada solución. Si no se proporcionan fallas para analizar_raíz_causa, ejecuta la detección de fallas automáticamente.
Continuando con la misma sesión del agente de investigación, el análisis de causa raíz revela la estructura causal:
La distinción entre tipos de soluciones es lo que hace que el análisis de la causa raíz sea viable. El error del esquema de la herramienta es TOOL_DESCRIPTION_FIX porque el KnowledgeBaseId de la herramienta de recuperación no está documentado claramente. La alucinación posterior es un SYSTEM_PROMPT_FIX debido a que faltan instrucciones sobre cómo manejar fallas persistentes de las herramientas. Arreglar sólo una categoría deja la otra sin abordar.
Diagnóstico integrado con diagnostic_session
Para mayor comodidad, diagnostic_session ejecuta ambas fases como una sola canalización (detecta fallas y luego analiza las causas raíz) y devuelve un DiagnosisResult unificado con recomendaciones deduplicadas:
Esto produce los mismos errores y causas raíz que se muestran en los ejemplos anteriores, empaquetados en un único resultado con recomendaciones deduplicadas en todas las causas raíz. A partir de una llamada a función, obtiene una lista priorizada de cambios concretos categorizados según su lugar.
Integración con canales de evaluación
Los detectores proporcionan un valor adicional cuando los integra en su flujo de trabajo de evaluación existente. DiagnosisConfig adjunta un diagnóstico automatizado a cualquier experimento, de modo que cada caso de prueba fallido produzca automáticamente un diagnóstico:
Hay dos modos de disparo disponibles. ON_FAILURE (predeterminado) ejecuta el diagnóstico solo cuando al menos un evaluador devuelve test_pass=False, lo que lo hace rentable para la detección de regresión de integración continua y entrega continua (CI/CD). SIEMPRE ejecuta el diagnóstico en cada caso independientemente del resultado, lo cual es útil para identificar rutas subóptimas en casos nominalmente pasajeros.
Con esta integración, su canal de CI/CD le indica "3 pruebas fallaron" y le indica por qué fallaron y qué cambiar. Esto cierra el ciclo de retroalimentación: defina casos, ejecute el experimento, obtenga puntuaciones y diagnósticos juntos, aplique las correcciones recomendadas y vuelva a ejecutarlo para confirmar.
Nota: La ejecución de detectores utiliza la inferencia de Amazon Bedrock para el análisis basado en LLM, lo que genera cargos. Consulte los precios de Amazon Bedrock para obtener más detalles. El almacenamiento de Amazon CloudWatch Logs también genera cargos. Consulte los precios de Amazon CloudWatch para obtener más detalles. Supervise su uso en AWS Cost Explorer, especialmente cuando integre detectores en canalizaciones de CI/CD que se ejecutan con frecuencia.
Diagnóstico de sesiones de producción desde CloudWatch
Los ejemplos anteriores utilizan archivos de sesión locales, pero en producción los seguimientos de su agente se encuentran en Amazon CloudWatch Logs, exportados con OpenTelemetry. CloudWatchProvider obtiene seguimientos directamente de Amazon CloudWatch y los convierte en objetos de sesión que puede analizar con detectores:
En el fondo, el proveedor consulta Amazon CloudWatch Logs Insights en busca de registros OTEL que coincidan con el ID de sesión, detecta automáticamente el marco del agente (Strands, LangChain u otros) a partir de metadatos de intervalos y asigna los intervalos a una sesión estandarizada. Los detectores funcionan con cualquier marco que exporte seguimientos de OpenTelemetry a Amazon CloudWatch, no solo con Strands Agents.
También puede combinar esto con la canalización de experimentos para la evaluación fuera de línea: use CloudWatchProvider para evaluar y diagnosticar sesiones de producción históricas sin volver a ejecutar el agente. También puede recuperar rastros de Langfuse u OpenSearch utilizando LangfuseProvider u OpenSearchProvider.
Mejores prácticas
Comience con confianza MEDIA. El umbral BAJO detecta más problemas potenciales pero incluye más ruido, lo que resulta útil para una investigación profunda de un caso de falla específico. MEDIUM proporciona una buena relación señal-ruido para uso rutinario. Reserve ALTO para el seguimiento de la producción cuando solo desee resultados de alta certeza.
Utilice ON_FAILURE en CI/CD, SIEMPRE para auditorías periódicas. ON_FAILURE mantiene los costos de LLM proporcionales a las tasas de falla, lo que lo hace práctico para cada ejecución de prueba. Programe ejecuciones del modo SIEMPRE semanalmente o por lanzamiento para detectar comportamientos subóptimos que se esconden en casos que pasan.
Primero solucione los fallos PRINCIPALES. Las fallas secundarias y terciarias a menudo se resuelven cuando se aborda su causa raíz. Antes de implementar múltiples recomendaciones, verifique si al corregir la falla principal se eliminan las posteriores. Esto reduce los ciclos de iteración.
Recomendaciones de grupo por tipo de solución. Lote de cambios TOOL_DESCRIPTION_FIX juntos y cambios SYSTEM_PROMPT_FIX juntos. Esto hace que el impacto de cada categoría de cambio se pueda medir de forma independiente cuando se vuelve a ejecutar la evaluación.
Pase los fallos predetectados a analyse_root_cause. Si ya ejecutó detect_failures y desea inspeccionar los resultados antes de ejecutar el análisis de causa raíz, páselos directamente para evitar detecciones redundantes:
Utilice la sesión de prueba para experimentar. El default_session.json utilizado en esta publicación está disponible en el conjunto de pruebas Strands Evals para que pueda probar los detectores localmente.
Limpiar recursos
Las funciones del detector en sí no proporcionan ningún recurso persistente de AWS. Sin embargo, si configuró la exportación de Amazon CloudWatch Logs para los seguimientos de su agente, es posible que desee revisar lo siguiente:
Grupos de registros de Amazon CloudWatch: la eliminación de un grupo de registros elimina permanentemente todos los datos de registro y no se puede deshacer. Confirme que ha exportado todos los registros que necesita conservar antes de continuar. Si creó grupos de registros específicamente para pruebas, elimínelos a través de la consola de Amazon CloudWatch o ejecutando aws logs delete-log-group –log-group-name . Acceso al modelo de Amazon Bedrock: el análisis LLM utiliza Amazon Bedrock. Si habilitó el acceso al modelo únicamente para este tutorial, revocarlo a través de la consola de Amazon Bedrock en Acceso al modelo.
Conclusión
Los detectores cierran el círculo entre medir la calidad del agente y mejorarla. Al automatizar la detección de fallas y el análisis de la causa raíz que antes requerían una inspección manual del seguimiento, puede pasar de "prueba fallida" a "esto es lo que hay que solucionar" en minutos en lugar de horas.
Para comenzar, consulte la documentación de los detectores SDK de Strands Evals y el repositorio de GitHub de Strands Evals. Pruebe el archivo de seguimiento de muestra incluido y luego agregue DiagnosisConfig a un caso de prueba existente en su canal de evaluación para ver el diagnóstico automatizado en acción.
Sobre los autores
Po-Shin Chen
Po-Shin Chen es un desarrollador de software que se centra en el desarrollo y las evaluaciones de IA agente en Amazon Web Services. Con experiencia en ingeniería y ciencia, su trabajo se centra en la creación de capacidades centrales para el marco agente (Strands SDK), liderando y desarrollando el marco de evaluación de agentes (Strands Evals).
Aaron Farntrog
Aaron Farntrog es ingeniero de software en Amazon y se centra en la creación de soluciones agentes. Su trabajo incluye el desarrollo de marcos de agentes como Strands SDK y Strands Evals, y la incorporación de capacidades de agentes a los sistemas de producción en la capa de aplicación utilizando Strands.
Muhyun Kim
Muhyun Kim es un científico de datos principal en AWS AI Fundamental Research que investiga y desarrolla primitivas clave para sistemas agentes, como evaluación, observabilidad, optimización y seguridad.
JJ Cho
Jaejin Cho es un científico aplicado en AWS y trabaja en sistemas de agentes con un enfoque en la observabilidad y la evaluación. Antes de AWS, se centró en la capacitación y evaluación de modelos principalmente en modalidades de voz, texto e imagen.
Ninad Kulkarni
Ninad Kulkarni es científico aplicado senior en AWS AI Fundamental Research y desarrolla primitivas para aplicaciones agentes que incluyen observabilidad, registro y seguridad.
Abhishek Kumar
Abhishek es científico aplicado en AWS y trabaja en la intersección de la inteligencia artificial y el aprendizaje automático, centrándose en la observabilidad, simulación y evaluación de agentes. Sus principales intereses de investigación se centran en los sistemas conversacionales agentes. Antes de ocupar su puesto actual, Abhishek pasó dos años en Alexa, Amazon, donde contribuyó a crear y entrenar modelos que impulsaron las capacidades principales de Alexa.