View a markdown version of this page

Diagnostique problemas de AgentCore evaluación con un asistente de codificación de IA - Amazon Bedrock AgentCore
¿Qué diagnostica la habilidadRequisitos previosCopia la habilidadAplica esta habilidad a tu asistente de programación de IAEjecute un diagnósticoEjemplo de interacciónSolución de problemas de la habilidad en síDocumentación relacionada

Diagnostique problemas de AgentCore evaluación con un asistente de codificación de IA

Si tu configuración de AgentCore evaluación no produce resultados (o si ves errores o puntuaciones de evaluación vacías) LogEventMissingExceptionAgentSpanMappingException, puedes utilizar la habilidad de diagnóstico de AgentCore evaluación para solucionar el problema tú mismo.

La habilidad consiste en un archivo de rebajas que funciona con cualquier asistente de programación de IA. Lo cargas en el asistente, indicas tu AWS región, el tipo de implementación y, si lo deseas, un identificador de sesión, y el asistente te guiará paso a paso para realizar un diagnóstico. La habilidad funciona con agentes implementados en AgentCore Runtime y agentes alojados en infraestructuras de terceros (Amazon ECS, Amazon EKS, AWS Lambda o cualquier otro entorno). El asistente consulta tus propios grupos de CloudWatch registros de Amazon para identificar la causa raíz y recomendar una solución.

¿Qué diagnostica la habilidad

La habilidad cubre los problemas de evaluación más comunes:

  • Los resultados de la evaluación están vacíos: no aparecen puntuaciones a pesar de que la configuración de evaluación esté habilitada.

  • LogEventMissingException— la evaluación indica que a un intervalo le falta el evento de registro correspondiente.

  • AgentSpanMappingExceptiono ToolSpanMappingException: la evaluación no puede extraer la consulta del usuario o el resultado de la herramienta de un intervalo.

  • SpanEventParsingException— la evaluación no puede analizar el cuerpo de un evento.

  • Gateway Timeout (504)— se agota el tiempo de espera de la evaluación.

  • ValidationExceptiononevaluatorId: el formato del identificador del evaluador es incorrecto.

  • Multi-agent problemas relacionados con el alcance de la evaluación: los evaluadores seleccionan al agente incorrecto en un rastreo de varios agentes.

Requisitos previos

  • AWS CLI configurada con las credenciales de la cuenta en la que se ejecuta el agente. Las credenciales necesitan los siguientes permisos:

    • logs:DescribeLogGroups,logs:DescribeLogStreams,logs:StartQuery, logs:GetQueryResults — para consultar CloudWatch los registros

    • bedrock-agentcore:GetOnlineEvaluationConfig, bedrock-agentcore:ListOnlineEvaluationConfigs — para leer las configuraciones de evaluación (solo para evaluación en línea)

  • Se recomienda Python 3.9 o posterior con la boto3 biblioteca, pero no es estrictamente obligatorio; las consultas de diagnóstico también se pueden ejecutar directamente a través de la AWS CLI.

  • Un asistente de programación de IA compatible con el estándar Agent Skills o que pueda aceptar instrucciones de rebajas.

  • Un agente que se ha invocado al menos una vez con la observabilidad habilitada.

Copia la habilidad

La fuente de habilidades está disponible en la fuente de habilidades de diagnóstico. Copia todo el bloque de código de ese tema y guárdalo SKILL.md dentro de una nueva carpeta con su nombre agentcore-eval-diagnostic/ en tu máquina.

La habilidad es un simple archivo de anotaciones. Contiene solo información pública y solo se utiliza en tu propia cuenta; no es necesario acceder al servicio.

Aplica esta habilidad a tu asistente de programación de IA

Guarda la fuente de habilidades de la fuente de habilidades de diagnóstico como SKILL.md si estuviera dentro de una carpeta con agentcore-eval-diagnostic/ el nombre de tu máquina y, a continuación, mueve o copia esa carpeta al directorio de habilidades de tu asistente de codificación de IA. La habilidad sigue el estándar abierto de habilidades de los agentes, por lo que cada herramienta la descubre en su propia carpeta de habilidades específica. No añadas el contenido de la habilidad a archivos de instrucciones genéricos comoAGENTS.md,CLAUDE.md, oGEMINI.md.

Kiro CLI

Coloca la carpeta de habilidades .kiro/skills/agentcore-eval-diagnostic/ en tu proyecto o en ~/.kiro/skills/agentcore-eval-diagnostic/ para que esté disponible en todos los espacios de trabajo. Para obtener detalles de configuración, consulte la documentación de habilidades de Kiro CLI.

Claude Code

Coloque la carpeta de habilidades .claude/skills/agentcore-eval-diagnostic/ en su proyecto o en ~/.claude/skills/agentcore-eval-diagnostic/ para que esté disponible en todos los proyectos. Para obtener detalles sobre la configuración, consulta la documentación de habilidades de Claude Code.

OpenAI Codex CLI

Coloca la carpeta de habilidades .agents/skills/agentcore-eval-diagnostic/ en tu repositorio o en ~/.agents/skills/agentcore-eval-diagnostic/ para que esté disponible en todos los repositorios. Para obtener detalles sobre la configuración, consulte la documentación de habilidades de CLI del Codex.

Cursor

Cursor usa reglas en lugar de habilidades. Guarde el contenido de las habilidades como regla de proyecto en.cursor/rules/agentcore-eval-diagnostic.md. Para obtener detalles sobre la configuración, consulte la documentación sobre las reglas del cursor.

CLI de Gemini

Coloque la carpeta de habilidades ~/.gemini/skills/agentcore-eval-diagnostic/ para que esté disponible en todos los espacios de trabajo, o en el directorio de habilidades de su proyecto para usarla dentro del ámbito del proyecto. Para obtener detalles de configuración, consulte la documentación de habilidades de CLI de Gemini.

¿Algún otro asistente de IA

Si tu asistente es compatible con el estándar de habilidades de agente, coloca la carpeta de habilidades en el directorio que usa para descubrir habilidades. Si su asistente no es compatible con Agent Skills, cargue la habilidad pegando el contenido de SKILL.md en un indicador del sistema, un mensaje de usuario o un archivo contextual. La habilidad es autónoma y no depende de ninguna característica específica de la herramienta.

Ejecute un diagnóstico

Tras cargar la habilidad, inicia una nueva conversación con tu asistente de IA y proporciona:

  1. Tu AWS región (por ejemplo,us-west-2).

  2. Su tipo de implementación: agentcore-runtime si su agente está implementado en AgentCore Runtime o 3p-managed si su agente está alojado en Amazon ECS, Amazon EKS, AWS Lambda o cualquier otro entorno que no sea. AgentCore

  3. Su tipo de evaluación: online (utiliza una configuración de evaluación con muestreo) o on-demand (llamada directa a la API Evaluate).

  4. Opcionalmente, se rastrea un identificador de sesión de su agente (el session.id atributo). Si no tiene uno, el asistente puede descubrir automáticamente las sesiones recientes de sus grupos de registro.

El asistente consulta los grupos de CloudWatch registros, identifica la causa raíz del error y elabora un informe de diagnóstico estructurado. El informe incluye:

  • Un resumen de la causa raíz.

  • Una tabla de resultados que muestra qué controles de diagnóstico se aprobaron o no.

  • Una lista de los tramos y eventos afectados.

  • Enlaces a la AWS documentación relevante.

  • Próximos pasos recomendados.

El asistente ejecuta todas las consultas de su propia AWS cuenta en sus propios grupos de CloudWatch registros. No accede a ningún registro del AWS lado del servicio ni a ningún dato interno.

Ejemplo de interacción

Tú: Mi región esus-west-2, uso AgentCore Runtime con evaluación en línea y mi ID de sesión esmy-session-abc123. Mi evaluación no produce resultados. ¿Puedes diagnosticarlo?

Asistente de IA: 

## AgentCore Evaluation Diagnostic Report

Session: my-session-abc123
Region: us-west-2

Summary: Service name mismatch — spans are emitted under
'my_agent.DEFAULT' but the evaluation configuration expects
'wrong_name.DEFAULT'.

Findings:
| Check                | Status | Details |
| -------------------- | ------ | ------- |
| Eval config status   | OK     | ENABLED, 100% sampling |
| Spans found          | OK     | 15 spans for this session |
| Scope support        | OK     | strands.telemetry.tracer found |
| Service name match   | FAIL   | Config expects wrong_name.DEFAULT |

Recommended fix: Update the evaluation configuration's serviceNames to
match 'my_agent.DEFAULT'.

Solución de problemas de la habilidad en sí

Si el asistente no puede consultar tus grupos de registros, comprueba que:

  • Sus AWS credenciales tienen los permisos necesarios.

  • La región que proporcionó coincide con el lugar en el que está desplegado su agente.

  • El identificador de sesión es correcto (cópielo del registro de sus agentes).

  • Se ha invocado al agente en las últimas 24 horas.

Temas