Eseguire il debug degli agenti con Agent Inspector in Microsoft Foundry Toolkit

Agent Inspector in Microsoft Foundry Toolkit for Visual Studio Code consente di inviare richieste a un agente locale, esaminare l'attività del modello e degli strumenti ed eseguire il debug del codice. Usalo per analizzare le risposte impreviste prima di distribuire una modifica.

Questo flusso di lavoro è utile per gli agenti ospitati, che eseguono il codice personalizzato in Foundry Agent Service. L'ispezione locale consente di eseguire il debug del codice. Prima dell'uso in produzione, testare anche l'agente distribuito con l'identità di runtime, la configurazione e l'accesso alla rete.

In questo articolo ci si connette a un agente locale, si esamina una richiesta e si salvano gli eventi di diagnostica. Il percorso principale usa il protocollo Responses. Le visualizzazioni disponibili dipendono dal protocollo e dalla diagnostica forniti dal server agent.

Prerequisites

  • Visual Studio Code con l'attuale estensione pubblica Foundry Toolkit. Vedere Install Foundry Toolkit.
  • Progetto agente locale con le relative dipendenze, configurazione del modello e credenziali configurate. Per iniziare da un esempio, seguire la guida introduttiva dell'agente ospitato tramite test locali.
  • Debugger richiesto dal tuo progetto. L'esempio di Python usa l'estensione Python e debugpy. Altri linguaggi ed esempi hanno requisiti diversi.

Per un progetto esistente, gli strumenti Foundry Toolkit Copilot consentono di preparare la configurazione. Esaminare i file generati e seguire il README.mdprogetto. Non sostituire i file di avvio con una configurazione generica.

Importante

Un agente locale può chiamare modelli cloud e strumenti live. Usare input di test non sensibili, controllare le autorizzazioni degli strumenti e tenere conto degli addebiti dei servizi configurati. Inspector non sostituisce gli strumenti con mock.

Connetti ed esegui il debug

Avviare il server agente prima di connettere Inspector. Usare la configurazione di avvio generata dal progetto per allineare il server, la directory di lavoro, l'interprete e il debugger.

  1. Avviare l'agente con la configurazione di debug documentata. Per l'esempio Python dell'agente ospitato, selezionare Debug Local Agent HTTP Server e premere F5.
  2. Se Inspector non è aperto, selezionare Foundry Toolkit nella barra delle attività, quindi Strumenti di sviluppo>Build>.
  3. Controllare l'endpoint nell'intestazione dell'Inspector. Lo scaffolding corrente Python usa http://localhost:8088. Per una porta server diversa, selezionare il pulsante a forma di matita accanto all'endpoint, immettere la porta e selezionare Connetti.
  4. Verificare che l'intestazione mostri Connesso. Inspector rileva automaticamente il protocollo Risposte o Invocazioni quando l'endpoint è raggiungibile.
  5. Impostare un punto di interruzione nel codice dell'agente e inviare un messaggio nel playground. Esaminare le variabili quando l'esecuzione viene sospesa, quindi continuare ed esaminare la risposta.

Screenshot della configurazione di debug dell'agente locale e di Agent Inspector connesso a localhost sulla porta 8088 con una risposta corretta.

L'apertura di Inspector da sola non avvia un server o collega un debugger. La configurazione di Python generata usa la porta 5679 per il debugger e la porta 8088 per le richieste HTTP dell'agente. Queste porte sono separate dalle porte di traccia OTLP.

Connettersi a un endpoint di Responses generico

Inspector può connettersi a un endpoint delle risposte generico locale senza l'interfaccia di diagnostica di sviluppo completa. È possibile esaminare gli eventi di risposte inviati dal server, ma il grafico del flusso di lavoro e la relativa visualizzazione di input e output non sono disponibili.

Una connessione con esito positivo non significa che il server fornisca percorsi di origine, utilizzo dei token o ragionamento.

Inviare una chiamata HTTP

Usare le chiamate HTTP quando l'agente accetta un corpo di richiesta personalizzato anziché un messaggio di conversazione. Il formato della richiesta e il protocollo di risposta del server determinano come Inspector invia e visualizza il risultato.

  1. Connettersi al server delle invocazioni HTTP in esecuzione. Inspector rileva automaticamente il protocollo.
  2. Immettere il corpo della richiesta richiesto dall'agente. Se il server espone una specifica OpenAPI compatibile, Inspector può compilare un esempio. Esaminarlo prima dell'invio o seguire il formato di richiesta del modello, se non è disponibile alcun esempio.
  3. Selezionare l'ingranaggio Impostazioni richiesta accanto all'input per impostare Content-Type e Accept come richiesto dal server. Ad esempio, usare application/json per un corpo JSON e text/event-stream quando il server supporta una risposta di streaming.
  4. Selezionare Invia ed esaminare lo stato e il corpo della risposta.
  5. Passa da Anteprima per l'output formattato a Raw per la risposta sottostante. Il riquadro dei dettagli include anche I/O e chiamate LLM. I dettagli del modello, dello strumento e del token dipendono dagli eventi del server riconosciuti, quindi non tutte le risposte riempiono ogni scheda.

Inspector gestisce una risposta HTTP normale, un flusso di eventi inviati dal server o una risposta asincrona. Per una risposta asincrona 202 Accepted , esegue il polling della chiamata fino al completamento o all'errore. La selezione di un formato di risposta non aggiunge il supporto di streaming o asincrono al server.

Per una risposta di streaming, Stop disconnette il flusso client. Per una chiamata di polling, Annulla invia una richiesta di annullamento al server. Nessuna delle due azioni garantisce che il processo dell'agente o un'operazione esterna dello strumento sia stato arrestato.

Questa visualizzazione non è un client WebSocket. Gli esempi di Activity Protocol usano un playground diverso. Vedere Scegliere un altro protocollo o un altro esempio per il percorso di test locale appropriato.

Usare l’Inspector

Iniziare con una richiesta che esercita il comportamento che si vuole comprendere. Per uno strumento meteo, ad esempio, chiedere informazioni che richiedono tale strumento, anziché una risposta generale che il modello può produrre senza di esso.

  1. Inviare la richiesta nel playground ed esaminare la risposta di streaming.
  2. Usare le schede dei dettagli per trovare l'operazione lenta o non riuscita.
  3. Esaminare l'evento o la chiamata dello strumento pertinente, modificare il codice o la configurazione e ripetere la richiesta.

Premere INVIO per inviare o MAIUSC+INVIO per aggiungere una nuova riga. Per richiamare una richiesta precedente, posizionare il cursore all'inizio dell'input e premere Freccia SU. Premere Freccia giù alla fine per spostarsi verso le richieste più recenti e tornare alla bozza non inviata.

È possibile modificare una richiesta ritirata prima di inviarla. La cronologia di input è una comodità all'interno di Inspector, non un archivio permanente di richieste salvate.

Visualizzazione Usalo per
Overview Seguire il waterfall della latenza e la timeline ordinata dell'esecuzione. Selezionare tutte le esecuzioni o una singola esecuzione per distinguere l'attività del modello e dello strumento dal tempo trascorso tra le esecuzioni.
Token Esamina l'utilizzo di token di input e output riportato. I dati di utilizzo mancanti non sono un risultato con token zero.
Events Esaminare gli eventi Responses analizzati, inclusi errori, chiamate di funzione e risultati. Cercare in base al tipo di evento o al contenuto JSON e filtrare per categoria.
Strumenti Esaminare le chiamate dello strumento raggruppate in base all'esecuzione della risposta, inclusi lo stato, l'ID chiamata, gli argomenti e i risultati.

Il piè di pagina della risposta mostra informazioni sul modello, sulla durata, sull'utilizzo dei token e sul timestamp quando specificato. Il testo di ragionamento e i riepiloghi di ragionamento vengono visualizzati in sezioni comprimibili separate quando l'agente li genera. Inspector non genera ragionamenti mancanti né espone informazioni che il provider di modelli non restituisce.

Esaminare gli strumenti e le autorizzazioni

Usare Strumenti per verificare se l'agente ha chiamato lo strumento previsto con gli argomenti previsti e ha ricevuto un risultato. Una risposta del modello con esito positivo non dimostra che uno strumento è stato eseguito. Se il codice usa un mock, il risultato visualizzato è comunque un risultato mock.

Schermata della scheda Strumenti con chiamate raggruppate per esecuzione e una chiamata di strumento espansa che mostra gli argomenti e il risultato.

Quando una risposta viene sospesa per l'approvazione mcp (Model Context Protocol) o il consenso OAuth, le richieste in sospeso vengono visualizzate sopra l'input del messaggio. Concedere solo l'accesso che si intende consentire.

Per una chiamata allo strumento MCP, selezionare Mostra parametri, esaminare gli input e quindi selezionare Approva o Rifiuta. Approva tutto e Nega tutto si applica alle richieste in sospeso, non ai criteri di approvazione permanente degli strumenti.

Per il consenso OAuth, completare sia l'autorizzazione del browser che la conferma Inspector:

  1. Selezionare Apri il consenso per la richiesta in sospeso.
  2. Completa l'autorizzazione nel browser, torna a Inspector e seleziona Consent done. Per rifiutare l'autorizzazione, selezionare Annulla .
  3. Risolvere le richieste di consenso rimanenti. Usare Tutto fatto, se disponibile, solo dopo aver completato l'autorizzazione per tutte le richieste aperte.

L'apertura di una pagina di consenso da sola non fa riprendere la richiesta. Inspector attende una decisione su ogni consenso in sospeso prima di controllare di nuovo il server. Le richieste possono riapparire se il server necessita ancora dell'autorizzazione.

Controllare il risultato successivo dello strumento, non solo l'approvazione, per confermare il completamento. Per la configurazione della connessione e dell'autenticazione, vedere Catalogo degli strumenti. Non modificare le credenziali o le autorizzazioni dello strumento esclusivamente per far scomparire un errore di diagnostica.

Esaminare i flussi di lavoro e il codice sorgente

Per i flussi di lavoro supportati di Microsoft Agent Framework, il server di sviluppo può fornire la diagnostica del flusso di lavoro e i riferimenti al sorgente. Inspector usa queste informazioni per visualizzare il grafico di esecuzione e passare al codice.

  1. Selezionare un nodo del flusso di lavoro per esaminare gli input e gli output disponibili.
  2. Fare doppio clic sul nodo per aprire la relativa posizione di origine.
  3. Impostare un punto di interruzione e ripetere la richiesta per controllare l'operazione nel debugger.

È possibile testare i flussi di lavoro LangGraph nel playground, ma la visualizzazione del flusso di lavoro non è supportata per tali flussi di lavoro. Un server senza metadati del flusso di lavoro può comunque restituire eventi di risposta utili.

Indagare sugli errori con Copilot

Usare le azioni di errore in Eventi per preparare una richiesta incentrata per GitHub Copilot invece di copiare l'intera conversazione.

  1. Trova l'evento non riuscito ed esaminane i dettagli per il contenuto sensibile prima di condividerli.
  2. Selezionare Fix accanto all'evento non riuscito per preparare un prompt per tale errore. Per diversi problemi, restringere l'elenco con i filtri di ricerca e categoria, quindi selezionare Risolvi con Copilot. Questa azione include gli errori visibili.
  3. Esaminare il prompt preparato in GitHub Copilot Chat prima di inviarlo. Esaminare le modifiche proposte, quindi eseguire nuovamente la richiesta dell'agente originale per confermare il risultato.

Queste azioni non richiedono il collector OTLP. La preparazione di un prompt di diagnostica non corregge l'agente né riesegue l'operazione non riuscita.

Screenshot della scheda Eventi con risposte non riuscite, controlli di ricerca e filtro, azioni di esportazione e dettagli di diagnostica preparati in Copilot Chat.

Salva gli eventi diagnostici

Salva uno snapshot dell'evento per confrontare un errore con un'esecuzione successiva o condividere una riproduzione incentrata.

  1. In Eventi restringere l'elenco con il campo di ricerca e il filtro categoria.
  2. Selezionare Copia eventi visibili per copiare gli eventi filtrati come JSONL. In alternativa, selezionare Scarica eventi visibili per aprire l'esportazione in VS Code.
  3. Per il file esportato aperto, utilizzare File> per salvare una copia in un percorso controllato prima di chiudere il documento. Il file esportato aperto è un file temporaneo, non un download permanente.

Lo snapshot contiene gli eventi visibili quando si seleziona l'azione, non gli eventi futuri dell'agente in esecuzione. Non salva una versione dell'agente, non distribuisce il codice né crea la cronologia di traccia cloud.

Attenzione

Gli eventi possono includere prompt, risposte, argomenti degli strumenti, risultati e dettagli degli errori. Prima di salvare o condividere un'esportazione, rivedere e oscurare il contenuto sensibile.

Avviare una nuova conversazione

Selezionare Cancella chat per avviare una nuova conversazione e cancellare lo stato di chat, Eventi e Dettagli. Esportare prima gli eventi di diagnostica necessari. L'aggiornamento dello stesso agente connesso mantiene lo stato di ispezione, mentre il cambio di agente cancella lo stato non aggiornato.

Per le risposte, Clear Chat è disabilitato mentre una risposta scorre attivamente. Rimane disponibile quando l'interazione viene sospesa per l'approvazione o il consenso. Non è un comando generale per arrestare il tuo agente.

Non fare affidamento sullo stato locale di Inspector come archivio permanente delle conversazioni. Il server gestisce la persistenza della conversazione, che può differire tra lo sviluppo locale e un agente ospitato distribuito. Cancellare Inspector non elimina le tracce già raccolte in locale o archiviate in Application Insights.

Differenze tra Inspector e tracing

Inspector comunica con il server locale tramite HTTP e trasmette in streaming gli eventi di risposta. Un server di sviluppo compatibile fornisce anche un flusso di diagnostica separato per i dettagli del flusso di lavoro e la navigazione del codice sorgente. Il debugger si collega al processo in esecuzione in modo indipendente.

Questi dati di diagnostica in tempo reale non richiedono l'agente di raccolta OTLP locale. La scheda Tracce di Inspector apre il visualizzatore di traccia separato. Non trasforma gli eventi del protocollo in span OpenTelemetry archiviati.

Per raccogliere span per un'analisi successiva, configurare il tracciamento locale. Per gli agenti distribuiti nell'ambiente, usare le tracce degli agenti ospitati.

Dopo il test locale, distribuisci l'agente ospitato. Testarla separatamente perché l'identità, l'ambiente e l'accesso alla rete differiscono dal tuo processo locale.

Troubleshooting

Issue Controlli da eseguire
Inspector non è in grado di connettersi. Controllare la presenza di errori di avvio nel terminale dell'agente. Confermare l'interprete, le dipendenze e la porta HTTP, quindi riconnettersi alla porta segnalata dal server. Aprire Inspector non avvia il processo.
Una richiesta ha esito positivo, ma i punti di interruzione non vengono attivati. Verificare che il debugger sia collegato al processo che gestisce la richiesta e usi la directory di origine corretta. Per Python, vedi risoluzione dei problemi di debug.
Il grafico o la navigazione all'origine non è presente. Verificare che il server e il flusso di lavoro forniscano la diagnostica di sviluppo e i percorsi di origine. L'ispezione delle risposte generiche non offre queste funzionalità. I flussi di lavoro LangGraph funzionano nel playground senza la visualizzazione del flusso di lavoro.
Mancano i risultati dello strumento. Controllare Eventi per errori e approvazioni in sospeso. Verificare che la richiesta richieda uno strumento e che lo strumento sia configurato e raggiungibile.
Mancano i dettagli relativi al token o al ragionamento. Controllare cosa emettono il modello e il server. Inspector può visualizzare solo le informazioni che forniscono.
Le immagini remote sono bloccate. Selezionare Carica immagini remote solo se si vuole che Inspector le recuperi dagli host remoti. Questo permesso di esposizione non è un'approvazione dello strumento. Gli URL o il contenuto non supportati possono comunque non essere caricati. Un'immagine mancante non indica necessariamente che la richiesta dell'agente non è riuscita.
Il flusso di risposta viene interrotto. Esaminare i dettagli della risposta parziale e dell'operazione non riuscita. Riconnettersi se necessario ed esaminare le approvazioni in sospeso prima di riprovare. Un tentativo può ripetere le azioni live dello strumento.
Inspector ha eventi, ma il visualizzatore di traccia è vuoto. Gli eventi del protocollo e gli span OTLP sono diversi. Configurare la strumentazione e avviare il collector.

Contenuti correlati

  • Ultimo aggiornamento: