View a markdown version of this page

Diagnostique problemas de AgentCore evaluación con un asistente de codificación de IA - Base amazónica AgentCore
Qué diagnostica la habilidadRequisitos previosCopia la habilidadCarga la habilidad en tu asistente de codificación de IAEjecute un diagnósticoEjemplo de interacciónSolución de problemas de la habilidad en síDocumentación relacionada

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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

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

La habilidad es un archivo de marcado que funciona con cualquier asistente de codificación de IA. Lo cargas en tu asistente, le indicas tu AWS región, el tipo de implementación y, opcionalmente, un identificador de sesión, y el asistente te guiará paso a paso para realizar un diagnóstico. Esta habilidad funciona con agentes implementados en AgentCore Runtime y con agentes alojados en infraestructuras de terceros (Amazon ECS, Amazon EKS, AWS Lambda o cualquier otro entorno). El asistente consulta sus propios grupos de CloudWatch registros de Amazon para identificar la causa principal 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 informa de que a un intervalo le falta el evento de registro correspondiente.

  • AgentSpanMappingExceptiono bien 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.

  • ValidationExceptionactivadoevaluatorId: el formato de identificación del evaluador es incorrecto.

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

Requisitos previos

  • AWS La CLI está 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 evaluación en línea)

  • Se recomienda usar Python 3.9 o una versión 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 codificación basado en IA que sea compatible con el estándar Agent Skills o que acepte instrucciones de marcado.

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

Copia la habilidad

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

La habilidad es un simple archivo de markdown. Contiene solo información pública y solo se ejecuta en tu propia cuenta; no se requiere acceso desde el lado del servicio.

Carga la habilidad en tu asistente de codificación de IA

Guarda la fuente de habilidades de la fuente de habilidades de diagnóstico SKILL.md 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 agente, por lo que cada herramienta la descubre en su propia carpeta de habilidades dedicada; no añada el contenido de la habilidad a archivos de instrucciones genéricosAGENTS.md, comoCLAUDE.md, oGEMINI.md.

CLI de Kiro

Coloque la carpeta de habilidades .kiro/skills/agentcore-eval-diagnostic/ en su proyecto o en ~/.kiro/skills/agentcore-eval-diagnostic/ para que esté disponible en todos los espacios de trabajo. Para obtener más información sobre la configuración, consulta la documentación sobre las habilidades de la CLI de Kiro.

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 más información sobre la configuración, consulta la documentación de habilidades de Claude Code.

CLI de OpenAI Codex

Coloque la carpeta de habilidades .agents/skills/agentcore-eval-diagnostic/ en su repositorio, o en ~/.agents/skills/agentcore-eval-diagnostic/ para que esté disponible en todos los repositorios. Para obtener más información sobre la configuración, consulte la documentación sobre las habilidades de la CLI del Codex.

Cursor

El cursor usa reglas en lugar de habilidades. Guarde el contenido de la habilidad como una regla de proyecto en.cursor/rules/agentcore-eval-diagnostic.md. Para obtener más información sobre la configuración, consulte la documentación de Cursor Rules.

CLI de Gemini

Coloque la carpeta de habilidades en ~/.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 en el ámbito del proyecto. Para obtener más información sobre la configuración, consulte la documentación sobre las habilidades de la 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 tu asistente para descubrir habilidades. Si su asistente no admite las habilidades de agente, cargue la habilidad pegando su contenido SKILL.md en una línea de comandos del sistema, un mensaje de usuario o un archivo de contexto. La habilidad es autónoma y no depende de ninguna función específica de la herramienta.

Ejecute un diagnóstico

Tras cargar la habilidad, inicia un nuevo chat 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á hospedado en Amazon ECS, Amazon EKS, AWS Lambda o cualquier otro AgentCore entorno que no sea.

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

  4. Si lo desea, puede utilizar un identificador de sesión de los rastreos de su agente (el session.id atributo). Si no tiene uno, el asistente puede detectar automáticamente las sesiones recientes de sus grupos de registro.

El asistente consulta tus grupos de CloudWatch registros, identifica la causa principal del error y produce un informe de diagnóstico estructurado. El informe incluye:

  • Un resumen de la causa principal.

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

  • Una lista de los intervalos y eventos afectados.

  • Enlaces a la AWS documentación relevante.

  • Próximos pasos recomendados.

El asistente ejecuta todas las consultas de tu propia AWS cuenta comparándolas con tus propios grupos de CloudWatch registro. 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, estoy usando AgentCore Runtime con la 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 registro, comprueba lo siguiente:

  • Tus AWS credenciales tienen los permisos necesarios.

  • La región que proporcionaste coincide con la región en la que está desplegado tu agente.

  • El identificador de sesión es correcto (cópielo de los rastros de su agente).

  • El agente ha sido invocado en las últimas 24 horas.

Temas