Livello 2: triage errori dell'agente

Dopo aver interpretato i punteggi delle valutazioni e identificato le aree di attenzione, determina perché i singoli casi di test sono falliti e chi deve agire.

Questo articolo fornisce indicazioni strutturate per diagnosticare gli errori a livello di i guasti a livello di test case. Consente di classificare la causa radice, distinguere tra problemi di agente, valutazione e infrastruttura, e scegliere la prossima azione da intraprendere.

Prima di iniziare

Prima di iniziare il triage degli errori:

  1. Completa l'interpretazione del punteggio e la valutazione dell'idoneità e identifica i set di valutazione che richiedono attenzione.
  2. Concentrati sugli errori di massima priorità in base all'idoneità e al rischio.

Importante

Se ignori questo passaggio, puoi dedicare del tempo a problemi di basso impatto o non critici.

Verifica preliminare: certifica l'integrità dell'infrastruttura

Prima di diagnosticare i singoli errori, verifica che le dipendenze siano integre durante l'esecuzione della valutazione. I problemi di infrastruttura possono generare errori che sembrano problemi di agente o di valutazione, ma non sono riconducibili a nessuno dei due.

Verificare le condizioni seguenti:

  • Le fonti delle informazioni sono accessibili e completamente indicizzate.
  • I back-end o i connettori API non restituiscono errori, timeout o risposte di limite di frequenza.
  • I token di autenticazione sono validi per tutta la durata della valutazione.
  • L'ambiente di valutazione è conforme alla configurazione prevista per l'agente.

Se una dipendenza non è integra, risolvi il problema ed esegui nuovamente la valutazione prima di continuare. Il triage dei risultati di un'esecuzione non integra può guidare a conclusioni errate.

Passaggio 0: assegnare priorità agli errori

Prima di analizzare i singoli test case, decidi dove concentrarti.

Dai priorità agli errori in quest'ordine:

Priorità Prima il triage Spiegazione
1 Errori di sicurezza e conformità Massima conseguenza. Risolvi questi errori prima della distribuzione.
2 Errori degli scenari aziendali principali Impatto diretto sulla proposta di valore dell'agente.
3 Errori nel set di valutazione con il punteggio più basso Probabilmente sistemico. La risoluzione della causa radice potrebbe risolvere più errori.
4 Errori ricorrenti in più esecuzioni Gli errori costanti sono più facili da diagnosticare.
5 Errori negli scenari di capacità Importante, ma tipicamente a minore impatto.

Se hai molti errori (ad esempio, più di 15), non eseguire io triage di ogni errore singolarmente. Inizia con il set di valutazione con il punteggio più basso ed esamina manualmente alcuni errori. Se condividono una causa radice, correggerla può risolvere molti errori in una sola volta.

Individua il segnale di qualità per un test non riuscito

Se un risultato di valutazione mostra un test case fallito ma non identifica chiaramente il segnale di qualità, usa il set di valutazione e il metodo di valutazione per inferire il segnale.

Ad esempio:

  • Il set di valutazione indica l'area di competenza, come la sicurezza, la fondatezza o l'uso degli strumenti.
  • Il metodo di valutazione, come la corrispondenza delle parole chiave o il punteggio basato sulla rubrica, fornisce più contesto.

L'identificazione del segnale di qualità desiderato aiuta a selezionare le domande di diagnostica più rilevanti.

Passaggio 1: verifica la configurazione della valutazione

Importante

Inizia sempre da qui. Prima di indagare sull'agente, verifica che la configurazione della valutazione sia corretta.

Per ogni errore, esamina manualmente la risposta effettiva dell'agente insieme al valore atteso e al metodo di valutazione.

Esamina le seguenti domande in ordine. Interrompi quando raggiungi un risultato.

  1. La risposta dell'agente è accettabile? Un utente reale sarebbe soddisfatto di questa risposta, anche se non ha superato la valutazione?

    • Se Sì, la configurazione di valutazione ha un problema: il valutatore o il valore atteso è sbagliato.
    • Se No, prosegui con la domanda successiva.

  2. La risposta attesa è aggiornata e accurata rispetto all'origine?

    • Se Sì, prosegui con la domanda successiva.
    • Se No, la configurazione della valutazione ha un problema: la risposta attesa è obsoleta o errata.

  3. Il test case riflette un input realistico degli utenti?

    • Se Sì, prosegui con la domanda successiva.
    • Se No, la configurazione della valutazione ha un problema: il test case è irrealistico.

  4. Potrebbe essere corretta anche una risposta alternativa ragionevole, ma il valutatore non la consente?

    • Se Sì, la configurazione della valutazione ha un problema: il valutatore è troppo rigido e non tiene conto delle variazioni valide.
    • Se No, prosegui con la domanda successiva.

  5. Il metodo di valutazione è appropriato per ciò che stai testando?

Determinare l'accettabilità della risposta

Utilizza i seguenti segnali per valutare se la risposta dell'agente è accettabile:

  • Stessi fatti chiave, espressione diversa → Spesso accettabile (il valutatore potrebbe essere troppo rigido).
  • Informazioni critiche presenti nell'origine ma mancanti nella risposta → Spesso non accettabile.
  • Soglia di accettabilità ambigua → i criteri di accettazione potrebbero essere poco chiari (da segnalare al passaggio 4).

Se hai dei dubbi, confronta il contenuto con l'origine originale, non solo con la risposta prevista.

Questi segnali guidano il tuo giudizio, ma non lo sostituiscono.

Tipi comuni di errori di configurazione della valutazione

Tipo di errore Descrizione Esempio
Risposta prevista obsoleta Il contenuto di origine è cambiato, ma il valore atteso non è stato aggiornato La policy è stata aggiornata a 15 giorni, ma la valutazione prevede ancora "finestra di reso di 30 giorni".
Valutatore troppo rigido La corrispondenza di parole chiave non riesce su un sinonimo valido o una riformulazione Era previsto "acqua fredda". La risposta dell'agente dice "acqua fresca, 30 gradi C", il che è semanticamente corretto.
Test case irrealistico Il Lo scenario di test non corrisponde al comportamento reale degli utenti Testare una query di 4 paragrafi quando utenti reali digitano 5-10 parole.
Metodo di valutazione errato Il metodo di valutazione non corrisponde a ciò che stai effettivamente testando L'uso di Corrispondenza parole chiave (Tutti) per una domanda di sintesi in cui Confronta significato è appropriato.
Errore di fatto del valutatore Il modello linguistico come giudice inventa un motivo di errore che non è reale (errore isolato) Il valutatore del modello linguistico afferma che "la risposta non menziona la politica di reso" mentre in realtà la menziona.
Distorsione sistematica del valutatore Il modello linguistico come giudice applica uno standard incoerente tra i test case (problema di calibrazione) Il valutatore accetta risposte brevi ma boccia quelle più lunghe per lo stesso segnale di qualità, indipendentemente dal contenuto.
Criteri di accettazione ambigui Il valore atteso può essere interpretato in più modi "Dovrebbe includere informazioni sui prezzi." Mensile? Annuale? Per utente?

Validazione del valutatore

L'affidabilità del valutatore è un prerequisito per un triage attendibile. Se il valutatore stesso non è affidabile, diagnostichi erroneamente ogni errore con cui entra in contatto.

Per convalidare l'affidabilità del valutatore:

  1. Seleziona 5-10 test case dove conosci il corretto esito di superamento/fallimento tramite revisione manuale.
  2. Esegui la valutazione e confronta l'output del valutatore con il verdetto manuale.
  3. Se il valutatore non è d'accordo su più del 20% di casi, calibrare nuovamente il valutatore prima di eseguire il debug dell'agente.

Segnali che un valutatore ha bisogno di attenzione:

  • Lo stesso caso di test produce verdetti diversi tra le diverse esecuzioni.
  • Gli errori si concentrano nei set di valutazione che utilizzano la valutazione basata su modello, mentre i metodi deterministici passano.
  • Il valutatore segnala problemi che non è possibile riprodurre analizzando la risposta dell'agente.

Opzioni di ricalibrazione del valutatore:

  • Usa metodi deterministici quando possibile.
  • Aggiungi esempi espliciti di "accettabile" e "non accettabile" alla rubrica.
  • Amplia i set di parole chiave includendo sinonimi e riformulazioni valide.
  • Utilizza Confronta significato invece di Corrispondenza parole chiave (Tutti) per le verifiche di equivalenza semantica.

Passaggio 2: esegui la diagnostica dell'agente

A questo punto, la valutazione è valida e l'agente ha prodotto una risposta errata. Analizza cosa non ha funzionato nella configurazione dell’agente.

Suggerimento

Alcune domande di diagnostica richiedono visibilità su cosa l'agente ha fatto internamente (ad esempio, quale fonte delle informazioni è stata recuperata, quale strumento è stato chiamato o quale argomento è stato attivato). Usa log di analisi, trascrizioni delle conversazioni o analisi di test quando disponibili. Se la tua piattaforma non mostra questi dettagli, deducili dalla risposta (es., se un contenuto appare solo nell'origine A, probabilmente proviene dall'origine A).

Verifica l'accuratezza dei fatti e gli errori di grounding della conoscenza

Domanda Se sì → Causa radice
L'agente ha recuperato dalla fonte delle informazioni sbagliata? Configurazione della fonte delle informazioni. Origine non corretta indicizzata o con priorità.
L'agente ha recuperato l'origine corretta ma ha estratto le informazioni sbagliate? Prompt o mancanza di istruzioni. Il modello necessita di indicazioni per l'estrazione.
Il contenuto dell'origine è errato o obsoleto? Contenuto della fonte delle informazioni. Aggiorna il documento di origine.
L'agente ha generato una risposta senza consultare alcuna fonte delle informazioni (inventandola)? Accessibilità dell'origine. Origine non indicizzata o la formulazione della query non corrisponde al vocabolario dell'origine.
L'agente ha contraddetto le informazioni presenti nell'origine? Informazioni errate. Aggiungi un'istruzione esplicita per il grounding.

Verificare gli errori di invocazione dello strumento

Domanda Se sì → Causa radice
È stato attivato lo strumento sbagliato? Ambiguità della descrizione dello strumento. Le descrizioni si sovrappongono tra gli strumenti.
Lo strumento corretto è stato attivato con parametri errati? Definizione parametro. Schema o descrizione non chiari.
Lo strumento non è stato attivato affatto? Condizione di trigger. L'input non soddisfa i criteri dell'invocazione.
Si è attivato lo strumento quando non avrebbe dovuto? Guardrail negativo mancante. Nessuna istruzione su quando non chiamare lo strumento.
Lo strumento è stato attivato correttamente, ma la risposta ha usato in modo improprio l'output? Istruzioni per la risposta. L'agente ha bisogno di indicazioni su come formattare gli output degli strumenti.
Lo strumento si è attivato correttamente, ma lo strumento stesso ha fallito (errore, timeout, dati errati)? Problema di strumento o integrazione; l'errore è nel sistema back-end, non nell'agente. Correggi lo strumento, non l'agente.

Controlla eventuali errori di distribuzione dei trigger

Domanda Se sì → Causa radice
È stato attivato l'argomento sbagliato? Sovrapposizione dei trigger di un argomento. I trigger sono ambigui tra gli argomenti.
Nessun argomento è stato innescato (fallback attivato)? Lacuna nella copertura dell’argomento. Nessun argomento gestisce questo tipo di input.
Più argomenti sono stati associati a una disambiguazione errata? Logica di disambiguazione. Flusso di priorità o chiarimento configurato in modo errato.

Verifica eventuali problemi di tono e qualità della risposta

Domanda Se sì → Causa radice
Il tono dell'agente è incoerente con le indicazioni del prompt di sistema? Lacuna nelle istruzioni sul tono. Risolvi le istruzioni mancanti o contraddittorie.
La risposta è troppo lunga o troppo corta rispetto alla domanda? Istruzioni sul formato. Aggiungi istruzioni sulla lunghezza o sulla struttura.
L'agente manca di empatia in contesti sensibili? Lacuna nelle istruzioni sull'empatia. Aggiungi indicazioni esplicite per gli input emotivi.
La risposta presenta una struttura inadeguata (muro di testo, nessuna suddivisione in passaggi)? Istruzioni sul formato. Aggiungi requisiti di formattazione.

Controllare la sicurezza e le violazioni dei confini

Domanda Se sì → Causa radice
L'agente ha rivelato informazioni di sistema? Protezione del prompt di sistema. Aggiungi istruzioni "non rivelare".
L'agente è uscito dall'ambito? Lacune nella definizione degli ambiti. Definisci i confini in modo più chiaro.
L'agente ha rispettato la prompt injection? Istruzioni per la sicurezza. Aggiungi indicazioni per la resistenza agli attacchi avversari.
L'agente ha gestito i dati personali in modo scorretto? Regole per la gestione delle informazioni personali. Aggiungi istruzioni per la protezione dei dati personali.

Verificare escalation e fallimento controllato

Domanda Se sì → Causa radice
L'agente non è riuscito a fare l'escalation quando avrebbe dovuto? Trigger di escalation. Criteri non definiti o troppo ristretti.
L'agente ha inoltrato prematuramente la segnalazione? Soglia di escalation. Criteri troppo sensibili.
L'escalation perde il contesto della conversazione? Configurazione passaggio. Conservazione del contesto non configurata.
L'agente ha continuato a ripetere invece di ammettere l'errore? Logica di fallback. Limite di tentativi o comportamento di fallback non configurato.

Dopo la diagnosi, esegui il mapping dei modelli di errore alle strategie di risoluzione in base alla causa radice.

Passaggio 3: identifica i limiti della piattaforma

Se la valutazione è corretta e modifiche ragionevoli nella configurazione non migliorano i risultati, il problema potrebbe essere una limitazione della piattaforma.

Indicatori di limitazione della piattaforma

Indicatore Cosa suggerisce
Lo stesso errore persiste tra più variazioni di prompt e configurazione Non è un problema di configurazione
Il recupero restituisce costantemente documenti sbagliati nonostante la configurazione corretta dell'origine Limitazione nell'ordinamento dei risultati di recupero
L'agente non riesce a eseguire il ragionamento richiesto nonostante istruzioni chiare Limite delle capacità del modello
Modello di orchestrazione obbligatorio non supportato da nessuna opzione di configurazione Vincolo logico di orchestrazione
Il valutatore basato su modello classifica in modo non corretto nonostante l'ottimizzazione della rubrica Limitazione del modello del valutatore

Percorso d'azione per limitazioni della piattaforma

  1. Documenta chiaramente la limitazione (cosa fallisce, cosa è stato provato ed elementi che dimostrano che non è un problema di configurazione).
  2. Applica una soluzione alternativa quando possibile (es., ristrutturare il documento di origine per migliorare il recupero).
  3. Contrassegna il test case come limitazione nota o modifica le soglie in modo da non bloccare i progressi non correlati.
  4. Segnala con prove al team della piattaforma.
  5. Registra l'elemento nel registro degli errori per una rivalutazione quando le capacità della piattaforma vengono aggiornate.

Dopo la classificazione, esamina le linee guida per la soluzione alternativa e l'escalation per rispondere alle limitazioni della piattaforma.

Quando un errore non rientra nel framework

Alcuni errori non si riconducono chiaramente a un singolo tipo di causa radice. Tra gli esempi più comuni figurano:

  • Problemi di qualità dei dati back-end: il contenuto della fonte delle informazioni è tecnicamente corretto ma scritto in modo ambiguo, quindi né l'agente né la valutazione risultano errate.
  • Problemi di infrastruttura intermittenti: timeout di rete, limite di flusso in entrata delle API e problemi di connettori che non si verificano in modo consistente.
  • Modifiche nella versione del modello: il comportamento dell'agente è cambiato dopo un aggiornamento del modello della piattaforma che non è stato avviato dall'utente.
  • Test case ambigui: lo scenario è ambiguo e persone ragionevoli non sono d'accordo sulla risposta corretta.

Approccio suggerito: documenta ciò che hai osservato (l'errore, la risposta dell'agente, cosa hai controllato). Registra la voce come "non classificata" nel registro degli errori. Se l'errore si ripresenta, spesso diventa classificabile con ulteriori prove.

Gestione delle cause multiple

Un singolo errore può avere più cause radice concorrenti. Ad esempio:

  • Un errore di accuratezza fattuale in cui la risposta attesa è leggermente obsoleta (configurazione della valutazione) e la fonte delle informazioni è anche incompleta (configurazione dell'agente).
  • Un errore nell'invocazione di uno strumento in cui la descrizione dello strumento è ambigua (configurazione dell'agente) e l'orchestrazione non supporta invocazioni condizionali degli strumenti (limitazione della piattaforma).

Approccio suggerito: completa il triage per ogni errore. Se si applicano più tipi di cause radice, affrontale secondo l'ordine di priorità:

  1. Correggere prima di tutto la valutazione per isolare un segnale pulito che permetta di capire se la modifica dell'agente apporta davvero benefici.
  2. Correggi la configurazione dell'agente per determinare se l'errore residuo è effettivamente un problema della piattaforma.
  3. Documenta la limitazione della piattaforma solo dopo aver affrontato i punti 1 e 2.

Esegui nuovamente i test case interessati dopo ogni modifica prima di procedere.

Gestione degli errori di conversazione a più turni

Negli scenari multi-turno, gli errori si manifestano solo tra i turni.

Quando sospettare un problema su più turni

  • L'agente risponde correttamente nei primi turni ma si contraddice in seguito.
  • L'agente perde il contesto di una precedente chiamata di uno strumento o di un recupero di conoscenza in un turno successivo.
  • La tempistica dell'escalation ha senso solo quando si considera la cronologia completa della conversazione.
  • Il tono dell'agente si deteriora progressivamente man mano che la conversazione si allunga.
  • L'agente chiede informazioni già fornite dall'utente.

Suggerimento

Un errore potrebbe manifestarsi in un turno successivo, mentre la causa radice si verifica in una fase precedente. Torna indietro per identificare il primo punto in cui la conversazione è divergente.

Domande diagnostiche aggiuntive

Domanda Se sì → Causa radice
L'errore dipende da informazioni di un turno precedente che sono andate perse? Problema di gestione del contesto; stato della conversazione non mantenuto tra i turni.
L'agente ha contraddetto qualcosa che aveva detto in un turno precedente? Assenza di linee guida sulla coerenza; nessuna indicazione per garantire la coerenza tra i turni.
L'agente ha richiesto nuovamente informazioni che l'utente aveva già fornito? Problema di recupero del contesto; l'agente non fa riferimento ai turni precedenti.
L'errore è apparso solo dopo molti turni (5+)? La lunghezza effettiva del contesto è stata superata.

Indicazioni di risoluzione dei problemi multi-turno

  • Perdita di contesto: verifica la configurazione dello stato della conversazione. Assicurati che gli output degli strumenti e i fatti chiave vengano mantenuti tra turni.
  • Contraddizioni: aggiungi istruzioni di coerenza, ad esempio: "Mantieni la coerenza con le tue risposte precedenti in questa conversazione."
  • Ripetizione delle domande: verifica la configurazione della memoria conversazionale della piattaforma.
  • Deterioramento delle conversazioni lunghe: considera strategie di riepilogo conversazioni o di riduzione del contesto.

Convalida dei test case superati (verifica dei falsi positivi)

Questo framework si concentra sui test case non riusciti. Tuttavia, un test case che viene superato erroneamente può creare lacune nascoste nella qualità.

Procedura consigliata: rivedi manualmente il 5-10% dei test case superati per ogni esecuzione di valutazione, specialmente per:

  • Valutazione basata su modelli (rischio maggiore di falsi positivi)
  • Segnali soggettivi (tono, utilità)
  • Test precedentemente falliti che ora vengono superati dopo una modifica

Se trovi falsi positivi, ricalibra il valutatore.

Passaggi successivi

Dopo aver completato il triage degli errori:

  • Last updated on