Usare la modalità sviluppatore per testare ed eseguire il debug degli agenti in Microsoft 365 Agents Toolkit

Suggerimento

Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.

Il test è una parte importante del processo di sviluppo di agenti dichiarativi per Microsoft 365 Copilot Chat. È possibile usare la modalità sviluppatore durante il test dell'agente per verificare se e come l'agente di orchestrazione Copilot seleziona le origini di conoscenza da usare in risposta a determinati prompt.

Inoltre, è possibile usare la funzionalità Anteprima dell'app (F5) nel toolkit degli agenti di Microsoft 365 per testare gli agenti in un ambiente di sviluppo locale. Questa funzionalità offre un modo interattivo per convalidare il comportamento e risolvere i problemi direttamente dall'interfaccia di sviluppo.

Usare la modalità sviluppatore in Copilot Chat e nel toolkit agenti

Puoi testare il tuo agente da Agents Toolkit in Visual Studio Code selezionando Anteprima della tua app (F5) nel riquadro Agents Toolkit. Questa operazione avvia l'agente in un'esperienza di Copilot Chat basata su browser, consentendo di convalidare rapidamente il suo comportamento in risposta alle richieste.

Screenshot di Visual Studio Code che mostra la funzionalità

Dopo aver selezionato l'agente in Microsoft 365 Copilot Chat, abilita la modalità sviluppatore digitando -developer on. Per disabilitare la modalità sviluppatore, digitate -developer off.

Screenshot della sessione di Copilot Chat in cui l'utente ha digitato

Quando la modalità sviluppatore è abilitata, viene restituita una scheda con le informazioni di debug ogni volta che l'agente di orchestrazione esegue una ricerca all'interno delle conoscenze (dati), delle funzionalità o delle competenze (azioni o plug-in) dell'agente. In Agent Toolkit, queste informazioni di debug vengono visualizzate nel pannello Debug e includono i seguenti campi:

  • Metadati dell'agente: identificatori per l'agente e la conversazione
  • Funzionalità: un elenco di funzionalità configurate per l'agente, insieme allo stato di esecuzione e alle statistiche di risposta (se eseguite)
  • Azioni: un elenco di azioni configurate per l'agente
    • Funzioni corrispondenti: stato delle funzioni corrispondenti nella ricerca dell'indice dell'app di runtime
    • Funzioni selezionate per l'esecuzione: stato delle funzioni selezionate per la chiamata in base al ragionamento dell'agente di orchestrazione

Sezione metadati agente

I metadati dell'agente forniscono dettagli chiave sull'agente e sulla sessione di debug corrente, tra cui:

  • Riepilogo : una panoramica generale delle origini delle conoscenze configurate e delle relative statistiche di utilizzo
  • ID agente - Un identificatore univoco per l'agente, che include l'ID del titolo e l'ID del manifesto
  • Versione agente : il numero di versione dell'agente attualmente in uso
  • ID conversazione - Identificatore della sessione di chat o della conversazione attiva
  • ID richiesta - Identificatore per la richiesta specifica all'interno della conversazione

Screenshot della sessione di Agents Toolkit in cui Copilot ha restituito una scheda con informazioni di debug che mostra i metadati dell'agente

Funzionalità dell'agente

Nella sezione Funzionalità dell'agente vengono visualizzate le funzionalità configurate per l'agente, definendo l'ambito delle origini di conoscenza accessibili. I dettagli seguenti vengono forniti per ogni funzionalità usata dal prompt.

  • Stato di esecuzione : indica se la funzionalità è stata utilizzata durante l'orchestrazione
  • File di log di diagnostica : file di .txt scaricabile contenente risultati di esecuzione dettagliati, inclusi messaggi di esito positivo o negativo, che possono essere utili per la risoluzione dei problemi e la convalida

Screenshot della sessione di Agent Toolkit in cui Copilot ha restituito una scheda con informazioni di debug che mostra le funzionalità dell'agente configurate

Azioni degli agenti

La sezione Azioni agente fornisce informazioni dettagliate sul modo in cui le azioni dell'agente (funzioni o plug-in) vengono elaborate durante l'orchestrazione. Queste informazioni sono suddivise in tre aree chiave: metadati dell'azione, corrispondenza e selezione delle funzioni e dettagli di esecuzione.

Screenshot della sessione di Agent Toolkit in cui Copilot ha restituito una scheda con informazioni di debug che mostrano le azioni dell'agente configurate

Metadati delle azioni

In questa sezione vengono visualizzate le informazioni generali sulle azioni registrate per l'agente. Queste informazioni includono l'ID azione (l'identificatore univoco per l'azione) e il numero di versione (la versione della definizione di azione in uso).

Corrispondenza e selezione delle funzioni

Questa parte illustra il modo in cui l'agente di orchestrazione ha interpretato il prompt dell'utente e se alcune funzioni sono state considerate rilevanti per l'esecuzione:

  • Funzioni corrispondenti : funzioni che corrispondono semanticamente al prompt dell'utente durante la ricerca dell'indice dell'app di runtime. Se per il prompt specificato non sono state restituite funzioni corrispondenti, è probabile che il prompt non abbia menzionato in modo esplicito il nome dell'azione.

  • Funzioni selezionate per l'esecuzione : funzioni scelte per la chiamata in base al ragionamento dell'agente di orchestrazione e alla pertinenza al prompt. Se non sono state abilitate azioni, la sezione delle azioni indica che non sono abilitate azioni.

Dettagli di esecuzione

I dettagli di esecuzione dell'azione includono la funzione e il relativo stato, insieme alla latenza, alle informazioni sulla richiesta (endpoint della richiesta, metodo HTTP, intestazioni della richiesta) e alla risposta.

Risolvere gli errori

Di seguito sono riportati gli errori comuni che potrebbero verificarsi durante il debug dell'agente e le possibili cause.

Nessuna informazione di debug

Dopo aver avviato l'agente, verifica che la connessione al browser sia contrassegnata come riuscita nel pannello di debug. In caso contrario, prova a eseguire di nuovo F5 in Visual Studio Code per avviare una nuova sessione.

Screenshot della sessione di Agent Toolkit in cui la connessione al Web browser è riuscita

Se la connessione è riuscita ma non vengono visualizzate le informazioni di debug, è possibile che l'agente di orchestrazione non richieda i dati o le competenze di Microsoft 365 per rispondere. In questo caso non viene restituita alcuna scheda informazioni di debug.

Le informazioni di debug non vengono restituite nemmeno nei casi di limitazione della capacità, dove in genere viene visualizzato un messaggio di errore che richiede di riprovare in un secondo momento.

Informazioni di debug senza alcuna funzione selezionata per l'esecuzione

Se nessuna funzione di azione corrisponde all'intento di ricerca del prompt, la scheda informazioni di debug segnala Nessuna funzione selezionata per l'esecuzione. La causa è probabilmente che la descrizione del comando nel manifesto non è semanticamente correlata all'intento di ricerca del prompt specificato.

Se Copilot in precedenza corrispondesse e eseguisse correttamente le funzioni, le richieste potrebbero essere limitate.

Informazioni di debug con vuoto o non riuscito Nessun dettaglio di esecuzione della funzione

Per i plug-in API, se sono presenti dettagli di esecuzione della funzione non riusciti o assenti, indica un errore durante il tentativo dell'agente di assegnare parametri alla funzione selezionata del plug-in. Se l'errore è coerente, è molto probabile che sia dovuto a descrizioni poco chiare di azioni o parametri, URL host non validi o altri problemi con la definizione di Open API.

Per i plug-in di estensione messaggio, la procedura consigliata consiste nell'ottimizzare le risposte sotto i nove secondi. Per altre informazioni, esaminare i requisiti tecnici per i plug-in di estensione messaggio.

Attualmente, il limite di timeout per l'esecuzione di un'API plug-in da parte di Copilot è impostato su 10 secondi.

Segnalazione di un problema

Segnala qualsiasi feedback o problema con il tuo agente usando il pulsante pollice su o pollice giù. Includere il #extensibility tag nel report.

Screenshot di Copilot Chat opzioni di feedback pollice su o pollice giù