View a markdown version of this page

Diagnostica i problemi di AgentCore valutazione con un assistente di codifica AI - Amazon Bedrock AgentCore
Cosa diagnostica l'abilitàPrerequisitiCopia l'abilitàCarica l'abilità nel tuo assistente di programmazione AIEsegui una diagnosiEsempio di interazioneRisoluzione dei problemi relativi all'abilità stessaDocumentazione correlata

Diagnostica i problemi di AgentCore valutazione con un assistente di codifica AI

Se la tua configurazione di AgentCore valutazione non produce risultati, o se visualizzi errori come punteggi di valutazione vuoti LogEventMissingExceptionAgentSpanMappingException, puoi utilizzare l'Evaluation Diagnostic Skill per risolvere il problema da solo. AgentCore

L'abilità è un file di markdown che funziona con qualsiasi assistente di codifica AI. Lo carichi nell'assistente, fornisci la tua AWS regione, il tipo di implementazione e, facoltativamente, un ID di sessione, e l'assistente ti guida attraverso una diagnosi dettagliata. La skill funziona con agenti distribuiti su AgentCore Runtime e agenti ospitati su infrastrutture di terze parti (Amazon ECS, Amazon EKS, AWS Lambda o qualsiasi altro ambiente). L'assistente interroga i tuoi gruppi di CloudWatch log Amazon per identificare la causa principale e consigliare una correzione.

Cosa diagnostica l'abilità

La competenza copre i problemi di valutazione più comuni:

  • Risultati di valutazione vuoti: non viene visualizzato alcun punteggio nonostante la configurazione di valutazione sia abilitata.

  • LogEventMissingException— la valutazione segnala che a uno span manca l'evento di registro corrispondente.

  • AgentSpanMappingExceptionoppure ToolSpanMappingException: la valutazione non può estrarre la query dell'utente o l'output dello strumento da uno span.

  • SpanEventParsingException— la valutazione non può analizzare il corpo di un evento.

  • Gateway Timeout (504)— il timeout della valutazione.

  • ValidationExceptionon evaluatorId — il formato dell'ID del valutatore non è corretto.

  • Multi-agent problemi relativi all'ambito della valutazione: i valutatori prendono di mira l'agente sbagliato in una traccia multiagente.

Prerequisiti

  • AWS CLI configurata con credenziali per l'account su cui viene eseguito l'agente. Le credenziali richiedono le seguenti autorizzazioni:

    • logs:DescribeLogGroups,, logs:DescribeLogStreamslogs:StartQuery, logs:GetQueryResults — per interrogare i registri CloudWatch

    • bedrock-agentcore:GetOnlineEvaluationConfig, bedrock-agentcore:ListOnlineEvaluationConfigs — per leggere le configurazioni di valutazione (solo valutazione online)

  • Python 3.9 o successivo con la boto3 libreria è consigliato ma non strettamente necessario: le query di diagnostica possono essere eseguite anche direttamente tramite la CLI. AWS

  • Un assistente di codifica AI che supporta lo standard Agent Skills o che può accettare istruzioni di markdown.

  • Un agente che è stato invocato almeno una volta con l'osservabilità abilitata.

Copia l'abilità

La fonte delle competenze è disponibile in Diagnostic skill source. Copia l'intero blocco di codice da quell'argomento e salvalo SKILL.md all'interno di una nuova cartella denominata agentcore-eval-diagnostic/ sul tuo computer.

L'abilità è un semplice file markdown. Contiene solo informazioni pubbliche e funziona solo con l'account dell'utente: non è richiesto l'accesso dal lato dei servizi.

Carica l'abilità nel tuo assistente di programmazione AI

Salva la fonte dell'abilità da Diagnostic skill source SKILL.md all'interno di una cartella denominata agentcore-eval-diagnostic/ sul tuo computer, quindi sposta o copia quella cartella nella directory delle competenze del tuo assistente di codifica AI. La skill segue lo standard aperto di Agent Skills, quindi ogni strumento la rileva dalla propria cartella dedicata alle competenze. Non aggiungete il contenuto della skill a file di istruzioni generici comeAGENTS.md, CLAUDE.md o. GEMINI.md

CLI Kiro

Posiziona la cartella delle competenze .kiro/skills/agentcore-eval-diagnostic/ nel tuo progetto o in ~/.kiro/skills/agentcore-eval-diagnostic/ per renderla disponibile in tutte le aree di lavoro. Per i dettagli di configurazione, consulta la documentazione sulle competenze della CLI di Kiro.

Codice Claude

Inserisci la cartella delle competenze .claude/skills/agentcore-eval-diagnostic/ nel tuo progetto o in ~/.claude/skills/agentcore-eval-diagnostic/ per renderla disponibile in tutti i progetti. Per i dettagli sulla configurazione, consulta la documentazione sulle competenze di Claude Code.

CLI OpenAI Codex

Posiziona la cartella delle competenze .agents/skills/agentcore-eval-diagnostic/ nel tuo repository o in ~/.agents/skills/agentcore-eval-diagnostic/ per renderla disponibile in tutti i repository. Per i dettagli sulla configurazione, consulta la documentazione sulle competenze della CLI di Codex.

Cursore

Il cursore utilizza le regole anziché le abilità. Salva il contenuto delle abilità come regola del progetto in.cursor/rules/agentcore-eval-diagnostic.md. Per i dettagli sulla configurazione, consulta la documentazione sulle regole del cursore.

CLI Gemini

Posiziona la cartella delle competenze su ~/.gemini/skills/agentcore-eval-diagnostic/ per renderla disponibile in tutte le aree di lavoro o nella directory delle competenze del progetto per utilizzarla nell'ambito del progetto. Per i dettagli sulla configurazione, consulta la documentazione sulle competenze della CLI di Gemini.

Qualsiasi altro assistente AI

Se il tuo assistente supporta lo standard Agent Skills, posiziona la cartella delle abilità nella directory utilizzata dall'assistente per scoprire le competenze. Se il tuo assistente non supporta Agent Skills, carica la skill incollandone il contenuto in un prompt di sistema, SKILL.md in un messaggio utente o in un file contestuale. L'abilità è autonoma e non dipende da alcuna funzionalità specifica dello strumento.

Esegui una diagnosi

Dopo aver caricato l'abilità, avvia una nuova chat con il tuo assistente AI e fornisci:

  1. La tua AWS regione (ad esempio,us-west-2).

  2. Il tipo di distribuzione, agentcore-runtime se l'agente è distribuito su AgentCore Runtime o 3p-managed se è ospitato su Amazon ECS, Amazon EKS, AWS Lambda o qualsiasi altro ambiente diverso dall'ambiente. AgentCore

  3. Il tipo di valutazione: online (utilizza una configurazione di valutazione con campionamento) o on-demand (chiamata API Evaluate diretta).

  4. Facoltativamente, un ID di sessione ottenuto dal tuo agente trace (l'session.idattributo). Se non ne hai uno, l'assistente può scoprire automaticamente le sessioni recenti dai tuoi gruppi di log.

L'assistente interroga i gruppi di CloudWatch log, identifica la causa principale dell'errore e produce un rapporto diagnostico strutturato. Il rapporto include:

  • Un riepilogo della causa principale.

  • Una tabella dei risultati che mostra quali controlli diagnostici hanno avuto esito positivo o negativo.

  • Un elenco degli intervalli e degli eventi interessati.

  • Collegamenti alla AWS documentazione pertinente.

  • Passaggi successivi consigliati.

L'assistente esegue tutte le interrogazioni del tuo AWS account sui tuoi gruppi di CloudWatch log. Non accede ai registri AWS sul lato dei servizi o ai dati interni.

Esempio di interazione

Tu: La mia regione èus-west-2, sto usando AgentCore Runtime con valutazione online e il mio ID di sessione èmy-session-abc123. La mia valutazione non produce risultati. Puoi diagnosticarlo?

Assistente AI: 

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

Risoluzione dei problemi relativi all'abilità stessa

Se l'assistente non riesce a interrogare i tuoi gruppi di log, verifica che:

  • AWS Le tue credenziali dispongono delle autorizzazioni richieste.

  • La regione che hai fornito corrisponde a quella in cui è distribuito il tuo agente.

  • L'ID di sessione è corretto (copialo dalle tracce del tuo agente).

  • L'agente è stato richiamato nelle ultime 24 ore.

Argomenti