Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Il debugger degli agenti è uno strumento diagnostico che ti aiuta a caricare una conversazione registrata e a ispezionare ogni decisione presa da un agente. Per ogni turno di conversazione, puoi rivedere il percorso di esecuzione, il tempismo dei passaggi, l'uso dei token, le fonti delle informazioni, gli argomenti dei passaggi e il ragionamento dell'orchestratore.
Il debugger degli agenti supporta due origini dati:
- Trascrizione della Conversazione (Dataverse): quando una conversazione viene eseguita in Copilot Studio, la piattaforma registra un log attività come trascrizione della conversazione in Dataverse. Il debugger degli agenti interroga direttamente quei record, quindi qualsiasi agente pubblicato con dati di trascrizione è immediatamente disponibile.
- Snapshot di Copilot Studio (ZIP): il pannello di test di Copilot Studio include un'opzione Scarica snapshot che esporta la conversazione di test corrente come file ZIP. Caricando quel file sul debugger degli agenti hai la visualizzazione completa dell'analisi senza una connessione Dataverse. Questo metodo è utile per il debug delle conversazioni in pre-produzione, riprodurre problemi offline o condividere una sessione fallita con un collega.
Entrambe le origini dati alimentano la stessa interfaccia di analisi. I pannelli, i dettagli dei passaggi e le visualizzazioni sono gli stessi indipendentemente da come vengono caricati i dati.
Prerequisiti
Per utilizzare il debugger degli agenti, assicurati che i seguenti prerequisiti siano soddisfatti:
- L'agente è presente nell'inventario degli agenti e ha almeno una trascrizione di conversazione registrata su di esso. Puoi verificare questa condizione aprendo la vista elenco Inventario degli agenti, selezionando l'agente e selezionando Mostra altro per espandere i campi aggiuntivi. Il campo Trascrizione disponibile deve essere impostato su Sì. La sincronizzazione dell'inventario degli agenti imposta automaticamente questo campo quando esiste almeno una trascrizione di conversazione per l'agente in Dataverse.
- L'utente connesso ha il ruolo di sicurezza CSK - Amministratore o Amministratore di sistema nell'ambiente del kit.
- L'utente connesso ha accesso in lettura alle tabelle
conversationtranscripts,botebotcomponentsnell'ambiente di destinazione.
Nota
Se l'agente di cui stati eseguendo il debug si trova in un ambiente diverso da quello in cui è installato il kit, devi autenticare la connessione Dataverse nell'ambiente remoto con le stesse autorizzazioni di lettura.
Selezionare una conversazione
Quando apri il debugger degli agenti, la barra dei filtri fornisce i controlli necessari per localizzare una conversazione da analizzare.
| Filtro | Descrizione |
|---|---|
| Environment | Popolati dai nomi di ambiente distinti presenti nell'inventario degli agenti. La selezione di un ambiente restringe il menu a discesa Agente agli agenti registrati in quell'ambiente. |
| Agente | Mostra gli agenti nell'ambiente selezionato il cui campo Trascrizione disponibile è impostato su Sì. Selezionando un agente, le 50 conversazioni più recenti entro l'intervallo di tempo selezionato si caricano nel menu a discesa ID conversazione. |
| ID conversazione | Mostra le 50 conversazioni uniche più recenti per l'agente selezionato all'interno dell'intervallo temporale configurato. Digitando nella casella, si avvia una ricerca completa su tutte le trascrizioni di quell'agente (fino a 100.000 record), così puoi trovare conversazioni più vecchie o specifiche indipendentemente dall'intervallo temporale. |
| Intervallo di ore | Restringe l'elenco ID conversazione a un intervallo specifico. Scegli tra Ultimi 30 minuti, Ultima ora, Ultime 4 ore, Ultime 24 ore, Ultimi 7 giorni o Intervallo personalizzato. Quando selezioni Intervallo personalizzato, i selezionatori di data e ora sembrano impostare un timestamp di inizio e fine. |
| Solo conversazioni con errori | Filtra il menu a discesa ID conversazione per le conversazioni che contengono almeno un passaggio fallito o un errore di sistema. Usa questa opzione per valutare gli incidenti o per valutare agenti con problemi di affidabilità noti. |
Dopo aver selezionato un ID conversazione, Analisi diventa disponibile. Selezionalo per aprire la vista di analisi.
Nota
Digitando direttamente un ID di conversazione si cerca sempre tutte le trascrizioni indipendentemente dall'intervallo di tempo attivo. Il filtro Solo conversazioni con errori esegue la scansione del contenuto delle trascrizioni lato client e richiede più tempo rispetto alla query standard. Lascialo disattivato a meno che tu non abbia bisogno di filtrare specificamente per errori.
Caricare una snapshot da Copilot Studio
La scheda Carica snapshot offre un punto di ingresso alternativo che non richiede l'accesso a Dataverse. Invece di selezionare una conversazione live dai menu a discesa, carichi un file ZIP con la snapshot scaricato dal riquadro di test di Copilot Studio.
Per scaricare una snapshot da Copilot Studio:
- Apri l'agente principale in Copilot Studio e vai al pannello Test dell'agente.
- Esegui o rivedi una conversazione.
- Seleziona Scarica snapshot nella barra degli strumenti del pannello di test.
Copilot Studio scarica un file .zip che contiene:
-
dialog.json: tutte le attività di Bot Framework per la conversazione (obbligatorie). -
botContent.yml: le definizioni complete dei componenti e del flusso dell'agente, utilizzate per risolvere i nomi dei passaggi (facoltative; se assenti, vengono mostrati i nomi grezzi degli schemi).
Per caricare una snapshot sul debugger degli agenti:
- Passa alla scheda Carica snapshot nell'intestazione del debugger degli agenti.
- Trascina e rilascia il file
.zipnella zona di rilascio oppure seleziona per cercarlo.
Il debugger degli agenti convalida lo ZIP, estrae i file e apre la visualizzazione di analisi. Non è richiesta la selezione di ambiente, agente o conversazione. Tutte le metriche informative generali sono derivate dal file caricato.
Usa la modalità Carica snapshot quando hai bisogno di:
- Eseguire il debug di una conversazione avvenuta nel riquadro di test prima che l'agente venisse pubblicato.
- Analizzare una conversazione da un ambiente in cui non puoi eseguire l'autenticazione.
- Riprodurre i problemi offline o condividere una sessione di errore con un collega senza concedere l'accesso a Dataverse.
- Convalidare il comportamento degli agenti in un ambiente per sviluppatori locale.
Analizzare una conversazione
La visualizzazione di analisi si apre dopo che selezioni Analizza o carichi una snapshot. Contiene una riga di riepilogo Informazioni generali in alto, una sezione di analisi comprimibile con quattro pannelli (Percorso di esecuzione, Sequenza temporale delle prestazioni, Dettagli dell'agente e Raccomandazioni) e un layout a due pannelli che mostra l'anteprima della conversazione insieme al pannello Informazioni di debug.
Informazioni generali
La riga delle informazioni generali mostra i riquadri delle metriche di riepilogo per la conversazione.
| Campo | Descrizione |
|---|---|
| Sessioni | Numero di sessioni di conversazione. Più sessioni avvengono quando un utente torna alla stessa conversazione dopo l'inattività. |
| Turni | Numero di messaggi utente nella conversazione. |
| Risultato | Esito della sessione riportato dalla piattaforma, come Risolto, Riassegnato, Abbandonato o SystemError. |
| Durata | Durata totale della conversazione dalla prima all'ultima attività. |
| Start Time | Quando è iniziata la conversazione (ora locale). |
| Canale | Canale di comunicazione utilizzato, come webchat o msteams. Mostrato quando disponibile. |
| Modello | Il modello di intelligenza artificiale usato dall'orchestratore dell'agente per questa conversazione. |
Quando un agente live viene caricato, un collegamento Apri agente appare nell'intestazione delle informazioni generali. Il collegamento apre la pagina di configurazione dell'agente in Copilot Studio.
Percorso di esecuzione
Il percorso di esecuzione visualizza l'ordine completo di esecuzione su tutti i turni di conversazione come un diagramma a flusso diretto. I passaggi scorrono da sinistra a destra in ordine di esecuzione. Linee verticali tratteggiate segnano i confini dei turni e ogni messaggio utente avvia una nuova sezione. Le etichette dei turni appaiono in cima a ogni sezione. Selezionando un'etichetta di turno si fa scorrere l'anteprima della conversazione fino a quel messaggio.
Ogni tipo di passaggio utilizza un colore distinto e una legenda in fondo al diagramma mappa i colori alle categorie di passaggi come Argomento, Conoscenza, Strumento, Connettore, Flusso, Codice, MCP e Agente connesso. Ogni nodo mostra il nome del passaggio e la durata dell'esecuzione. I passaggi con errore sono evidenziati in rosso. Gli agenti connessi appaiono come caselle contenitore che raggruppano i passaggi figlio che hanno eseguito.
Sequenza temporale delle prestazioni
La sequenza temporale delle prestazioni mostra un grafico a cascata dei tempi di esecuzione dei passaggi raggruppati per turno di conversazione. Le barre dei passaggi sono ridimensionate in base alla durata totale del turno per rendere visibili i tempi relativi. La codifica a colori corrisponde alla legenda del percorso di esecuzione e i passaggi con errore appaiono in rosso.
Il pannello include le seguenti funzionalità:
- I pulsanti Espandi/Comprimi tutto attivano tutte le sezioni di turno contemporaneamente. Ogni sezione di turni è anche comprimibile singolarmente.
- Le statistiche per turno mostrano il numero di passaggi, il nome e la durata dei passaggi più lenti e il numero di errori.
- Un riepilogo globale in alto mostra il totale dei passaggi, il tempo totale trascorso, il passaggio più lento nell'intera conversazione e il numero totale di errori.
- I passaggi più lenti di 10 secondi sono segnalati con un indicatore di avviso.
Dettagli agente
Il pannello dettagli dell'agente mostra la configurazione completa dell'agente così com'era al momento dell'analisi della conversazione. Le informazioni sono organizzate in sei schede.
| Tab | Descrizione |
|---|---|
| Panoramica | Riquadri KPI per Argomenti, Strumenti, Conoscenza, Agenti figlio, Modalità orchestrazione, Lingua, Modalità autenticazione, Conoscenza del modello, Ricerca semantica e Ultimi modelli. Ogni riquadro include una descrizione comando che spiega l'ambientazione. |
| Istruzioni | Il prompt completo del sistema dell'agente configurato in Copilot Studio. |
| Argomenti | Tutti gli argomenti con nome, descrizione, variabili di input/output e stato Abilitato/Disabilitato. |
| Strumenti | Tutti gli strumenti con nome, descrizione, badge di tipo (MCP, Flusso, Connettore, Prompt) e stato Abilitato/Disabilitato. |
| Conoscenza | Tutte le fonti delle informazioni con nome, badge di tipo (SharePoint, Web, Dataverse, File), URL e stato Abilitato/Disabilitato. |
| Agenti | Tutti gli agenti figli connessi con nome, tipo di relazione e stato Abilitato/Disabilitato. |
Suggerimenti
Il pannello delle raccomandazioni rileva automaticamente i problemi nella conversazione e li mostra come schede utilizzabili con valutazioni di gravità.
| Gravità | Descrizione |
|---|---|
| Alto | Probabilmente ha causato una risposta incorretta o errata. Indaga immediatamente. |
| Media | Esperienza degradata o rischio di affidabilità. Rivedi subito. |
| Basso | Inefficienza minore o nota informativa. |
Vengono rilevati i seguenti tipi di problemi:
| Emissione | Gravità | Descrizione |
|---|---|---|
| Passaggio non riuscito o con errore | Massimo | Un passaggio ha restituito un errore o un'eccezione. |
| Blocco di intelligenza artificiale responsabile | Massimo | Il contenuto è stato filtrato dal sistema dell'intelligenza artificiale responsabile. |
| Riassegnazione delle conversazioni | Massimo | La conversazione è stata trasferita a un agente umano. |
| Abbandono della conversazione | Massimo | L'utente ha abbandonato senza una soluzione. |
| Argomento di fallback attivato | Massimo | L'agente non è riuscito a instradare il messaggio dell'utente verso un argomento. |
| Passaggio lento (>10s) | Medio | Un passaggio ha impiegato più di 10 secondi per essere eseguito. |
| Errore della ricerca nella Knowledge Base | Medio | Una fonte delle informazioni è stata interrogata ma non ha restituito risultati. |
| Limite di token quasi raggiunto | Medio | L'utilizzo dei token si è avvicinato al limite della finestra di contesto del modello. |
| Errore di passaggio del codice | Massimo | Un passaggio di codice Python ha sollevato un'eccezione. |
| Errore di Inizializzazione MCP | Massimo | L'inizializzazione di un server MCP non è riuscita durante la conversazione. |
Ogni scheda di raccomandazione mostra l'icona di gravità e il colore, un badge di categoria, il titolo e la descrizione del problema rilevato, un suggerimento su come indagarlo o risolverlo, e un pulsante Vai al turno che scorre l'anteprima della conversazione fino al messaggio utente pertinente. Quando non vengono rilevati problemi, il pannello mostra un messaggio di stato vuoto.
Anteprima della conversazione
Il pannello di anteprima della conversazione mostra l'intero scambio della conversazione così come appariva all'utente, incluse le bolle di messaggi utente e bot, schede adattiva con rendering in linea, chip d'azione suggeriti e prompt di feedback.
Selezionando una bolla di messaggi utente, i passaggi di questo turno si caricano nel pannello Informazioni di debug. Il messaggio selezionato è evidenziato così puoi tracciare quale turno è attivo. Il pannello può essere fatto scorrere in modo indipendente. Selezionando Visualizza JSON nell'intestazione di anteprima della conversazione si apre la finestra di dialogo JSON della trascrizione completa.
Informazioni di debug
Il pannello di informazioni di debug mostra dettagli a livello di passaggio per il turno del messaggio utente selezionato. Il pannello include un elenco di passaggi a sinistra e una vista dettagliata dei passaggi che si apre quando selezioni un passaggio.
L'elenco dei passaggi passi mostra ogni passaggio dell'orchestratore eseguito per il turno selezionato, con un'icona e un colore che indicano il tipo di passaggio, il nome del passaggio (risolto in un nome visualizzato intuitivo quando possibile), la durata dell'esecuzione e un indicatore di successo o errore. I passaggi appartenenti a un agente connesso sono raggruppati all'interno di una scheda contenitore comprimibile che mostra il nome dell'agente e il tempo totale di esecuzione. Un pulsante Carica dettagli dell'agente connesso sul container carica la trascrizione completa dell'agente figlio su richiesta.
Sono supportati i seguenti tipi di passaggi:
| Tipo | Descrizione |
|---|---|
| Topic | Un argomento con nome nell'elenco di argomenti dell'agente. |
| Argomento di sistema | Un argomento integrato nella piattaforma, come Formula di saluto, Fallback o Riassegna. |
| Conoscenza | Un passaggio di ricerca della fonte delle informazioni. |
| Strumento/Azione | Un flusso o azione di connettore Power Automate. |
| Codice | Un passaggio di esecuzione del codice Python. |
| Prompt personalizzato | Un passaggio con prompt di IA generativa personalizzato. |
| Ragionatore | Un passaggio di ragionamento interno usato dall'orchestratore. |
| Server MCP | Una chiamata dello strumento Model Context Protocol. |
| Agente connesso | Delega a un agente figlio connesso. |
Selezionando un passaggio, si apre un pannello dettagliato con le seguenti sezioni, mostrate quando i dati sono presenti nella trascrizione:
- Processo di riflessione: il testo di ragionamento dell'orchestratore registrato prima che il passaggio venisse invocato. Mostra come il modello ha deciso di chiamare questo passaggio e cosa si aspettava da esso.
- Tipo di passaggio: etichetta classificata per il passaggio.
- Argomenti: una vista ad albero JSON comprimibile dei parametri di input passati al passaggio. Include un'opzione di copia per acquisire il JSON per i ticket di supporto.
- Osservazione: il valore di output o restituzione del passaggio. Visualizzato anche come un albero JSON comprimibile con supporto per la copia.
- Anteprima del codice: per i passaggi con codice Python, il codice sorgente viene mostrato con evidenziazioni della sintassi.
- Utilizzo dei token: numero di token del prompt, numero dei token di completamento e totale per il passaggio, insieme al nome del modello utilizzato.
- Fonti delle informazioni: fonti ricercate, risultati restituiti (output) e fonti effettivamente citate nella risposta finale. Ogni voce mostra il nome della fonte, il tipo, l'URL dove disponibile e un collegamento per aprire la fonte.
- Informazioni sul server MCP: per i passaggi MCP, mostra la versione del protocollo del server, le capacità dichiarate e l'elenco degli strumenti forniti dal server durante l'inizializzazione.
- Informazioni sull'errore: quando un passaggio fallisce, mostra il codice di errore, il messaggio di errore e (per i blocchi di intelligenza artificiale responsabile) la categoria di sicurezza dei contenuti che ha attivato il filtro.
- Schede adattive: quando il passaggio produce una risposta con scheda adattiva, il rendering della scheda viene eseguito in linea nel pannello dei dettagli esattamente come l'utente l'avrebbe vista.
JSON trascrizione
Quando selezioni Visualizza JSON nell'intestazione di anteprima della conversazione, si apre una finestra che mostra le attività complete non elaborate della trascrizione con evidenziazione della sintassi, ricerca in testo completo all'interno dell'albero JSON e un'opzione copia nella cartella per l'intero payload.
Utilizza questa visualizzazione quando:
- Devi ispezionare un tipo di evento che non appare nel pannello Informazioni di debug.
- Vuoi copiare campi specifici per un ticket di supporto.
- Stai indagando su comportamenti inaspettati nelle viste analizzate.
Risoluzione dei problemi
Le sezioni seguenti descrivono i problemi comuni e come risolverli.
L'agente non appare né nell'ambiente né nel menu a discesa dell'agente
L'agente non è sincronizzato con l'inventario dell'agente oppure non ha trascrizioni delle conversazioni.
Per risolvere il problema:
- Esegui una sincronizzazione manuale dell'inventario degli agenti per l'ambiente.
- Verifica che il record dell'agente esista nella tabella Dettagli dell'agente in Dataverse.
- Controlla che la colonna Trascrizione disponibile sia impostata su Sì nel record. La sincronizzazione imposta questo campo quando esiste almeno una trascrizione.
Per maggiori informazioni, consulta Monitorare gli agenti usando l'inventario degli agenti nel kit per gli agenti Copilot.
L'ID conversazione non si trova nel menu a discesa
Per quanto riguarda le prestazioni, il menu a discesa precarica solo le 50 conversazioni più recenti all'interno dell'intervallo di tempo attivo. Le trascrizioni più vecchie esistono ancora in Dataverse ma non appaiono di default. In alternativa, la trascrizione potrebbe non essere ancora scritta se la conversazione è appena finita.
Per risolvere il problema:
- Digita l'ID della conversazione direttamente nel campo ID conversazione. Digitando si avvia una ricerca completa su tutte le trascrizioni per quell'agente, ignorando l'intervallo temporale.
- Se l'intervallo di tempo è ristretto (ad esempio, Ultimi 30 minuti), amplialo o passa a un intervallo personalizzato che copra la data della conversazione.
- Se la conversazione è appena finita, aspetta 35-40 minuti che la trascrizione venga scritta su Dataverse, poi aggiorna.
Analizza viene caricato, ma nel riquadro Informazioni di debug non viene visualizzato alcun passaggio
La trascrizione esiste ma contiene solo attività di tipo messaggio senza eventi di traccia diagnostica. Questo problema si verifica tipicamente quando la conversazione proviene da un canale che non emette dati di traccia, come alcuni canali personalizzati o versioni più vecchie dello schema.
Per risolvere il problema:
- Seleziona Visualizza JSON nell'intestazione di anteprima della conversazione per confermare la presenza di attività.
- Cerca le voci
type: "trace"otype: "event". Se sono assenti, il canale potrebbe non emettere dati di traccia.
Accesso negato o pagina vuota al caricamento
Ruoli o autorizzazioni sono mancanti in uno o in entrambi gli ambienti.
Per risolvere il problema:
- Nell'ambiente del kit, assicurati che l'utente abbia il ruolo CSK - Amministratore o Amministratore di sistema.
- Nell'ambiente di destinazione, assicurati che l'utente connesso abbia accesso in lettura alle tabelle
conversationtranscripts,botebotcomponents.
Le trascrizioni appaiono incomplete (messaggi iniziali mancanti)
Le conversazioni lunghe sono suddivise su più record Dataverse (limite di 1 MB per record). Se i criteri di conservazione eliminano alcuni record, la trascrizione unita presenta delle lacune.
Per risolvere il problema:
- Dataverse elimina di default le trascrizioni delle conversazioni più vecchie di 30 giorni. Se il problema è la conservazione, aggiorna il programma di eliminazione in blocco dei processi in Power Apps>Impostazioni>Impostazioni avanzate>Gestione dati>Eliminazione in blocco record.
- Se la causa non è la conservazione, verifica che tutti i record delle trascrizioni per la conversazione siano presenti nella tabella
conversationtranscriptsdi Dataverse.
I passaggi mostrano i nomi non elaborati degli schemi invece dei nomi leggibili degli argomenti
La ricerca della tabella botcomponents non è riuscita oppure il record del componente è stato eliminato.
Per risolvere il problema:
- Verifica che l'utente connesso abbia accesso in lettura alla tabella
botcomponentsnell'ambiente di destinazione. - Se il componente è stato eliminato da Copilot Studio, non esiste alcun record corrispondente e il debugger degli agenti torna al nome non elaborato dello schema, come
cr123_mytopic. Questo comportamento è previsto per argomenti o azioni eliminate.
Il pannello dei dettagli dell'agente non mostra dati
Il recupero della configurazione dell'agente non è riuscito oppure la connessione dell'utente connesso non ha accesso in lettura alle tabelle bot e botcomponents nell'ambiente di destinazione.
Per risolvere il problema:
- Verifica l'accesso in lettura alle tabelle
botebotcomponentsper il riferimento a una connessione usato dall'app. - Se l'agente è stato eliminato o non pubblicato dopo la registrazione della conversazione, i suoi record di configurazione potrebbero non esistere più. In questo caso, il pannello Dettagli dell'agente rimane vuoto, ma i pannelli di trascrizione e debug sono ancora pienamente funzionanti.
Il pannello delle raccomandazioni non mostra problemi, ma la conversazione è fallita
Le raccomandazioni derivano da modelli presenti negli eventi di traccia della trascrizione. Se nella trascrizione mancano dati di traccia o se l'errore avviene al di fuori della conversazione (ad esempio, un timeout di rete automatico che la trascrizione non registra), il sistema non genera raccomandazioni.
Per risolvere il problema:
- Apri il JSON della trascrizione per cercare payload di errore non elaborati che non sono presentati come raccomandazione.
- Controlla il percorso di esecuzione per eventuali passaggi mostrati in rosso. Questi passaggi indicano errori che non corrispondono a un modello di raccomandazione noto.