# Come funziona
<a name="insights-how-it-works"></a>

AgentCore insights risponde a tre domande sul comportamento di produzione del tuo agente: **Perché fallisce**? **Cosa chiedono gli utenti?** e **come risolve i problemi?** 

## Cosa ottieni
<a name="insights-what-you-get"></a>

Quando esegui Insights, ricevi:
+  **Un elenco prioritario di modelli di errore**, non errori individuali, ma problemi ricorrenti raggruppati per causa principale. Ogni schema indica cosa sta andando storto e perché. Insights è integrato con funzionalità di [AgentCore raccomandazione](optimization-recommendations.md) per generare correzioni ai modelli di errore.
+  **Una mappa degli intenti degli utenti**: le cose più comuni che gli utenti cercano di realizzare, classificate in base alla frequenza.
+  **Un riepilogo dei modelli di comportamento degli agenti**: in che modo l'agente affronta tipicamente i problemi e quali risultati ottiene.

Questi corrispondono a tre tipi di informazioni che puoi configurare:
+  `Builtin.Insight.FailureAnalysis`— Rilevamento del modello di guasto e analisi della causa principale
+  `Builtin.Insight.UserIntent`— Estrazione e clustering delle intenzioni degli utenti
+  `Builtin.Insight.ExecutionSummary`— Riepilogo e raggruppamento del comportamento degli agenti

## Come funziona l'analisi
<a name="insights-how-analysis-works"></a>

Insights esamina le tracce delle sessioni dell'agente (il registro completo dei messaggi degli utenti, delle motivazioni degli agenti, delle chiamate agli strumenti e delle risposte) e produce risultati a due livelli:

### Session-level analisi
<a name="insights-session-level"></a>

Ogni sessione viene analizzata singolarmente per determinare:
+ Se l'agente ha riscontrato errori durante l'esecuzione, inclusi errori nascosti all'interno delle tracce che potrebbero non essere visibili all'utente finale anche quando la sessione sembra riuscita
+ Quale categoria di errore si è verificata (errore dell'utensile, allucinazioni, scelta errata dell'utensile, ecc.)
+ Quale fase specifica dell'esecuzione dell'agente ha causato l'errore
+ Qual era la causa principale
+ Cosa stava cercando di ottenere l'utente
+ Quale approccio ha adottato l'agente e il risultato finale

### Scoperta di schemi
<a name="insights-pattern-discovery"></a>

Dopo l'analisi delle singole sessioni, il servizio identifica gli schemi ricorrenti in tutte le sessioni raggruppando risultati simili. Per l'analisi degli errori, si ottiene una gerarchia a tre livelli:

1.  **Categorie di fallimento:** raggruppamenti ampi come «errori di esecuzione», «allucinazioni» o «azioni scorrette».

1.  **Sottocategorie:** tipi di errori più specifici, come «limitazione della velocità» o «errori dello schema degli strumenti».

1.  **Cluster di cause principali:** all'interno di ogni sottocategoria, le cause principali ricorrenti specifiche. Ogni cluster ti dice:
   + Qual è la causa principale
   + Quante sessioni sono interessate
   + Quali sessioni puoi controllare per maggiori dettagli

Per quanto riguarda le intenzioni degli utenti e i riepiloghi dell'esecuzione, il servizio produce flat cluster classificati in base alla frequenza.

## Quando viene eseguito
<a name="insights-when-it-runs"></a>

Sei tu a controllare quando viene eseguito Insights:
+  **One-time:** contatta `StartBatchEvaluation` Insights ogni volta che desideri un'analisi, ad esempio dopo un'implementazione, dopo un picco di reclami degli utenti o come parte di una revisione settimanale.
+  **Ricorrente:** configura una frequenza di clustering (`DAILY``WEEKLY`, o`MONTHLY`) e il servizio viene eseguito automaticamente, fornendoti report periodici senza interventi manuali.

## Categorie di guasti
<a name="insights-failure-categories"></a>

Insights riconosce un'ampia tassonomia dei tipi di guasto degli agenti:


| Categoria | Esempi | 
| --- | --- | 
| Errori di esecuzione | Errori di autenticazione, risorsa non trovata, errori di servizio, limitazione della velocità, timeout, violazioni dello schema degli strumenti | 
| Problemi relativi alle istruzioni sulle attività | Non-compliance con istruzioni, errori di identificazione dei problemi | 
| Azioni errate | Selezione errata degli strumenti, scarso recupero delle informazioni, richieste di chiarimenti inappropriate | 
| Gestione del contesto | Errori di gestione del contesto tra i turni | 
| allucinazione | Capacità inventate, incomprensioni, utilizzo scorretto, fabbricazione di dati storici, allucinazioni parametriche, risultati di utensili fabbricati | 
| Comportamento ripetitivo | Ripetizione della chiamata allo strumento, ripetizione della richiesta di informazioni, ripetizione dei passaggi | 
| Errori di orchestrazione | Mancata corrispondenza di ragionamento, deviazione dall'obiettivo, terminazione anticipata, cessazione inconsapevole | 
| Problemi di output LLM | Uscite prive di senso | 
| Mancata corrispondenza della configurazione | Mancate corrispondenze nella definizione degli utensili | 
| Coding-specific | Supervisioni dei casi limite, problemi di dipendenza |