View a markdown version of this page

Diagnostique problemas AgentCore de avaliação com um assistente de codificação de IA - Amazon Bedrock AgentCore
O que a habilidade diagnosticaPré-requisitosCopie a habilidadeColoque a habilidade em seu assistente de codificação de IAExecute um diagnósticoExemplo de interaçãoSolução de problemas da habilidade em siDocumentação relacionada

Diagnostique problemas AgentCore de avaliação com um assistente de codificação de IA

Se sua configuração de AgentCore avaliação não estiver produzindo resultados — ou se você estiver vendo erros como LogEventMissingExceptionAgentSpanMappingException, ou pontuações de avaliação vazias — você pode usar a habilidade de diagnóstico de AgentCore avaliação para solucionar o problema sozinho.

A habilidade é um arquivo markdown que funciona com qualquer assistente de codificação de IA. Você o carrega em seu assistente, fornece sua AWS região, tipo de implantação e, opcionalmente, uma ID de sessão, e o assistente orienta você em um diagnóstico passo a passo. A habilidade funciona com agentes implantados no AgentCore Runtime e agentes hospedados em infraestrutura de terceiros (Amazon ECS, Amazon EKS, AWS Lambda ou qualquer outro ambiente). O assistente consulta seus próprios grupos de CloudWatch registros da Amazon para identificar a causa raiz e recomendar uma solução.

O que a habilidade diagnostica

A habilidade abrange os problemas de avaliação mais comuns:

  • Resultados de avaliação vazios — nenhuma pontuação aparece apesar da configuração de avaliação estar ativada.

  • LogEventMissingException— a avaliação relata que um intervalo está perdendo seu evento de log correspondente.

  • AgentSpanMappingExceptionou ToolSpanMappingException— a avaliação não pode extrair a consulta do usuário ou a saída da ferramenta de um intervalo.

  • SpanEventParsingException— a avaliação não pode analisar o corpo de um evento.

  • Gateway Timeout (504)— a avaliação atinge o tempo limite.

  • ValidationExceptionativado evaluatorId — o formato do ID do avaliador está incorreto.

  • Multi-agent problemas de escopo de avaliação — os avaliadores têm como alvo o agente errado em um rastreamento multiagente.

Pré-requisitos

  • AWS CLI configurada com credenciais para a conta em que o agente é executado. As credenciais precisam das seguintes permissões:

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

    • bedrock-agentcore:GetOnlineEvaluationConfig, bedrock-agentcore:ListOnlineEvaluationConfigs — para ler as configurações de avaliação (somente avaliação on-line)

  • O Python 3.9 ou posterior com a boto3 biblioteca é recomendado, mas não estritamente obrigatório — as consultas de diagnóstico também podem ser executadas diretamente pela CLI. AWS

  • Um assistente de codificação de IA que suporta o padrão Agent Skills ou que pode aceitar instruções de marcação.

  • Um agente que foi invocado pelo menos uma vez com a observabilidade ativada.

Copie a habilidade

A fonte de habilidades está disponível em Fonte de habilidades de diagnóstico. Copie todo o bloco de código desse tópico e salve-o como SKILL.md dentro de uma nova pasta nomeada agentcore-eval-diagnostic/ em sua máquina.

A habilidade é um arquivo markdown simples. Ele contém apenas informações públicas e funciona somente em sua própria conta — nenhum acesso do lado do serviço é necessário.

Coloque a habilidade em seu assistente de codificação de IA

Salve a fonte de habilidades da fonte de habilidades de diagnóstico como SKILL.md dentro de uma pasta nomeada agentcore-eval-diagnostic/ em sua máquina e, em seguida, mova ou copie essa pasta para o diretório de habilidades do seu assistente de codificação de IA. A habilidade segue o padrão aberto Agent Skills, então cada ferramenta a descobre em sua própria pasta de habilidades dedicada — não anexe o conteúdo da habilidade a arquivos de instruções genéricasAGENTS.md, como, CLAUDE.md ou. GEMINI.md

Kiro CLI

Coloque a pasta de habilidades .kiro/skills/agentcore-eval-diagnostic/ em seu projeto ou em ~/.kiro/skills/agentcore-eval-diagnostic/ para disponibilizá-la em todos os espaços de trabalho. Para obter detalhes de configuração, consulte a documentação de habilidades do Kiro CLI.

Claude Code

Coloque a pasta de habilidades .claude/skills/agentcore-eval-diagnostic/ em seu projeto ou em ~/.claude/skills/agentcore-eval-diagnostic/ para disponibilizá-la em todos os projetos. Para obter detalhes de configuração, consulte a documentação de habilidades do Claude Code.

CLI do Codex OpenAI

Coloque a pasta de habilidades .agents/skills/agentcore-eval-diagnostic/ em seu repositório ou em ~/.agents/skills/agentcore-eval-diagnostic/ para disponibilizá-la em todos os repositórios. Para obter detalhes de configuração, consulte a documentação de habilidades do Codex CLI.

Cursor

O cursor usa regras em vez de habilidades. Salve o conteúdo da habilidade como uma regra do projeto em.cursor/rules/agentcore-eval-diagnostic.md. Para obter detalhes de configuração, consulte a documentação das Regras do Cursor.

CLI do Gemini

Coloque a pasta de habilidades em ~/.gemini/skills/agentcore-eval-diagnostic/ para disponibilizá-la em todos os espaços de trabalho ou no diretório de habilidades do seu projeto para uso no escopo do projeto. Para obter detalhes de configuração, consulte a documentação de habilidades da CLI do Gemini.

Qualquer outro assistente de IA

Se seu assistente suportar o padrão Agent Skills, coloque a pasta de habilidades no diretório que seu assistente usa para descobrir habilidades. Se o seu assistente não oferecer suporte às habilidades do agente, carregue a habilidade colando o conteúdo SKILL.md em um prompt do sistema, mensagem do usuário ou arquivo de contexto. A habilidade é independente e não depende de nenhum recurso específico da ferramenta.

Execute um diagnóstico

Depois de carregar a habilidade, inicie um novo bate-papo com seu assistente de IA e forneça:

  1. Sua AWS região (por exemplo,us-west-2).

  2. Seu tipo de implantação — agentcore-runtime se seu agente estiver implantado no AgentCore Runtime ou 3p-managed se seu agente estiver hospedado no Amazon ECS, Amazon EKS, AWS Lambda ou em qualquer outro ambiente não pertencente. AgentCore

  3. Seu tipo de avaliação — online (usa uma configuração de avaliação com amostragem) ou on-demand (chamada direta da API Evaluate).

  4. Opcionalmente, um ID de sessão do seu agente rastreia (o session.id atributo). Se você não tiver uma, o assistente poderá descobrir automaticamente as sessões recentes dos seus grupos de registros.

O assistente consulta seus grupos de CloudWatch registros, identifica a causa raiz da falha e produz um relatório de diagnóstico estruturado. O relatório inclui:

  • Um resumo da causa raiz.

  • Uma tabela de resultados mostrando quais verificações de diagnóstico foram aprovadas ou reprovadas.

  • Uma lista dos períodos e eventos afetados.

  • Links para AWS documentação relevante.

  • Próximas etapas recomendadas.

O assistente executa todas as consultas em sua própria AWS conta em relação aos seus próprios grupos de CloudWatch registros. Ele não acessa nenhum registro do AWS lado do serviço ou dados internos.

Exemplo de interação

Você: Minha região éus-west-2, estou usando o AgentCore Runtime com avaliação on-line e meu ID de sessão émy-session-abc123. Minha avaliação não está produzindo resultados. Você pode diagnosticar isso?

Assistente 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'.

Solução de problemas da habilidade em si

Se o assistente não conseguir consultar seus grupos de registros, verifique se:

  • Suas AWS credenciais têm as permissões necessárias.

  • A região que você forneceu corresponde ao local em que seu agente está implantado.

  • O ID da sessão está correto (copie-o dos rastreamentos do seu agente).

  • O agente foi chamado nas últimas 24 horas.

Tópicos