View a markdown version of this page

Diagnostique problemas AgentCore de avaliação com um assistente de codificação de IA - Base da Amazônia AgentCore
O que a habilidade diagnosticaPré-requisitosCopie a habilidadeCarregue 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

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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, um 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 correçã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 habilitada.

  • LogEventMissingException— a avaliação relata que um intervalo não tem seu evento de registro 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 consegue analisar o corpo de um evento.

  • Gateway Timeout (504)— o tempo limite da avaliação é atingido.

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

  • Multi-agent problemas de escopo de avaliação — os avaliadores identificam o agente errado em um rastreamento de vários agentes.

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 por meio da AWS CLI.

  • Um assistente de codificação de IA compatível com o padrão Agent Skills ou que pode aceitar instruções de remarcaçã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 chamada agentcore-eval-diagnostic/ em sua máquina.

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

Carregue 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 chamada 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 de habilidades do agente, 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ção genéricosAGENTS.md, como, CLAUDE.md ou. GEMINI.md

CLI do Kiro

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 OpenAI Codex

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 do Cursor Rules.

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 do Gemini CLI.

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 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 o agente estiver implantado no AgentCore Runtime ou 3p-managed se o agente estiver hospedado no Amazon ECS, Amazon EKS, AWS Lambda ou em qualquer outro ambiente que não seja. AgentCore

  3. Seu tipo de avaliação — online (usa uma configuração de avaliação com amostragem) ou on-demand (chamada direta à 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 a AWS documentação relevante.

  • Próximas etapas recomendadas.

O assistente executa todas as consultas em sua própria AWS conta em 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 puder 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á destacado.

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

  • O agente foi invocado nas últimas 24 horas.

Tópicos