Test degli agenti utilizzando tunnel dev

Utilizzando tunnel dev, puoi testare il tuo agente Agent 365 con applicazioni Microsoft 365 (come Teams, Outlook o Word) mentre il tuo agente viene eseguito localmente sulla tua macchina di sviluppo. Questo approccio collega lo sviluppo locale e i test nel mondo reale, così puoi validare il comportamento dell'agente negli effettivi ambienti Microsoft 365 prima di distribuirlo nel cloud.

Prerequisiti

Prima di utilizzare tunnel dev, assicurati di installare lo strumento da riga di comando tunnel dev.

• Windows: winget install Microsoft.devtunnel
• macOS/Linux: scarica da aka.ms/devtunnels/download

Configura tunnel dev

Configura un tunnel dev per esporre il tuo endpoint agente locale ai servizi Microsoft 365.

Crea e avvia un tunnel

1. Accedi al tunnel dev:

   devtunnel user login
   

2. Crea un tunnel persistente:

   devtunnel create --allow-anonymous
   

   Questo comando restituisce un ID del tunnel. Salva questo identificatore per usi futuri.

3. Configura la porta del tunnel:

   Assegna la porta che usa il tuo server agente (di solito 3978):

   devtunnel port create <tunnel-id> -p <port-number>
   

4. Avvia il tunnel:

   devtunnel host <tunnel-id>
   

   Il comando mostra l'URL del tunnel (ad esempio, https://abc123xyz.devtunnels.ms:3978). Copia questo URL per il passaggio successivo.

Configurare gli endpoint di messaggistica degli agenti

Registra l'URL del tuo tunnel dev (ad esempio, https://abc123xyz.devtunnels.ms:3978/api/messages) come endpoint di messaggistica dell'agente, in modo che Microsoft 365 sappia dove instradare i messaggi. Non dimenticare il suffisso /api/messages all'endpoint.

Consulta Impostare l'endpoint di messaggistica agente

Test con Microsoft 365

Con il tunnel dev attivo e l'endpoint registrato, testa il tuo agente nelle applicazioni Microsoft 365.

Test in Microsoft Teams

1. Avvia il tuo agente locale utilizzando le istruzioni in Installa le dipendenze e avvia il server applicativo dell'agente.

2. Verifica la connettività del tunnel:

   devtunnel list
   

   Controlla che il tuo tunnel mostri le connessioni host attive. La colonna "Connessioni Host" dovrebbe mostrare un numero superiore a 0.

3. Interagisci con il tuo agente in Teams:

   • Apri Microsoft Teams (Web o desktop)
   • Nella barra di ricerca di Teams, cerca il tuo agente per nome o email
   • Avvia una conversazione con l'agente
   • Invia un messaggio e osserva la risposta
   • Controlla la console locale per richieste in arrivo e attività dell'agente

Testa le notifiche e-mail

Se il tuo agente è configurato per notifiche via e-mail:

1. Invia un'e-mail all'indirizzo e-mail del tuo agente
2. Metti in copia il tuo agente in una conversazione e-mail
3. Monitora la tua console locale per il webhook di notifiche
4. Verifica che il tuo agente elabori e risponda all'e-mail

Test integrazione Word

Per gli agenti che rispondono ai commenti in Word:

1. Apri un documento Word a cui il tuo agente ha accesso.
2. Aggiungi un commento che menzioni il tuo agente.
3. Verifica la tua console locale per la notifica.
4. Verifica che la risposta del tuo agente appaia in Word.

Monitora l'attività del tunnel

Tunnel dev fornisce l'ispezione del traffico per facilitare la diagnosi dei problemi di connessione e comprendere il flusso delle richieste:

devtunnel show <tunnel-id>

Questo comando mostra:

• Connessioni attive e dettagli delle sessioni.
• Informazioni su richieste e risposte.
• Statistiche sul volume del traffico.
• Errori e problemi di connessione.

Puoi anche monitorare l'attività del tunnel in tempo reale osservando l'output del comando devtunnel host.

Mantieni le connessioni del tunnel

I tunnel dev richiedono che il processo devtunnel host rimanga in esecuzione. Se l'inattività, problemi di rete o il computer va in sospensione causano l'interruzione della connessione, devi riavviare il processo.

Controlla lo stato del tunnel

Verifica se il tuo tunnel è attivo:

devtunnel list

L'output mostra:

• ID tunnel: Il tuo identificatore del tunnel
• Connessioni host: Numero di connessioni attive (dovrebbe essere una o più quando devtunnel host è in esecuzione)
• Porte: porte configurate
• Scadenza: Tempo di scadenza del tunnel

Se Connessioni host mostra 0, il tunnel esiste ma attualmente non è ospitato.

Riavvia un tunnel disconnesso

Se la connessione al tunnel si interrompe, riavvialo usando lo stesso ID del tunnel:

devtunnel host <tunnel-id>

L'URL del tunnel resta invariato, quindi non è necessario aggiornare la configurazione dell'endpoint di messaggistica dell'agente.

Mantieni attivi i tunnel durante lo sviluppo

Per mantenere connessioni stabili:

• Tieni aperta la finestra del terminale: Non chiudere il terminale in funzione devtunnel host.
• Previeni la modalità standby del computer: Configura il sistema affinché resti attivo durante le sessioni di test.
• Monitora gli errori di connessione.: Controlla l'uscita del terminale devtunnel host per messaggi di disconnessione.
• Riavvia dopo che la rete cambia: Se cambi rete o ti riconnetti alla VPN, riavvia il tunnel.

Eseguire la pulizia

Al termine dei test con tunnel dev:

Ferma il tunnel

Premi Ctrl+C nel terminale che esegue devtunnel host per arrestare il tunnel.

Questo comando rimuove l'URL del tunnel dev dall'endpoint di messaggistica dell'agente. Quando distribuisci in produzione, imposta l'URL dell'endpoint ospitato nel cloud.

Limiti

Considera queste limitazioni durante i test con i tunnel dev:

• Solo per sviluppo: Usa tunnel dev per sviluppo e test, non per la produzione.
• Prestazioni: Aspettati una latenza più alta rispetto agli agenti ospitati nel cloud a causa del routing di rete.
• Stabilità della connessione: le connessioni tunnel potrebbero occasionalmente interrompersi e richiedere un riavvio manuale.
• Considerazioni sulla sicurezza: Il flag --allow-anonymous è comodo per i test, ma non usarlo con dati sensibili.
• Gestione delle sessioni: Potresti dover riautenticarti periodicamente a seconda della durata della sessione.

Passaggi successivi

Dopo aver completato con successo i test con tunnel dev:

• Distribuisci il tuo agente nel cloud: Distribuisci su Azure, imposta l'endpoint di messaggistica dell'agente in AWS, oppure imposta l'endpoint di messaggistica dell'agente in GCP.
• Configura gli endpoint di messaggistica dell'agente: Endpoint di messaggistica dell'agente.
• Segui l'intero ciclo di vita di sviluppo di Agent 365: Ciclo di vita di sviluppo di Agent 365.

Risoluzione dei problemi

Se incontri problemi durante i test tramite tunnel dev, inizia da qui per soluzioni comuni per tunnel, connettività ed endpoint. Per una risoluzione più ampia dei problemi di Agent 365 (configurazione, autenticazione e messaggistica), consulta Risoluzione dei problemi.

Errore di connessione al tunnel

Sintomi: tunnel dev non si avvia o si disconnette immediatamente.

Soluzioni:

• Verifica di aver effettuato l'accesso: devtunnel user login
• Controlla se un altro processo utilizza la stessa porta
• Assicurati che il firewall consenta le connessioni tunnel dev
• Elimina e ricrea il tunnel: devtunnel delete <tunnel-id> poi creane uno nuovo

I messaggi non raggiungono l'agente locale

Sintomi: Microsoft 365 indica che il messaggio è stato inviato, ma il tuo agente locale non lo riceve.

Soluzioni:

• Conferma che il tuo agente sia in esecuzione in locale
• Verifica che il tunnel sia attivo: devtunnel list dovrebbe mostrare "Connesso"
• Controlla la configurazione dell'endpoint in a365.config.json e verifica che l'URL del tuo tunnel dev sia impostato come endpoint di messaggistica
• Consulta i log di tunnel dev nel terminale che esegue devtunnel host per errori di connessione
• Assicurati che la tua porta locale corrisponda alla porta del tunnel (entrambe dovrebbero essere 3978 per impostazione predefinita)

Errori di autenticazione tramite tunnel dev

Sintomi: errori 401 o 403 durante i test attraverso tunnel dev.

Soluzioni:

• Verifica che l'autenticazione tramite agente sia configurata (l'autenticazione tramite token bearer non funziona con l'integrazione di Dev Tunnels per Microsoft 365).
• Controlla le credenziali del progetto dell'agente in a365.generated.config.json.
• Conferma che il tuo agente disponga dei permessi necessari per le operazioni che stai testando.
• Assicurati che i tuoi token di autenticazione non siano scaduti.

URL del tunnel cambiato o scaduto

Sintomi: L'URL del tunnel che funzionava in precedenza non indirizza più al tuo agente.

Soluzioni:

• Controlla lo stato del tunnel usando devtunnel list.
• Riavvia il tunnel usando devtunnel host <tunnel-id>.
• Aggiorna l'endpoint di messaggistica se l'URL è cambiato usando a365 setup blueprint --endpoint-only.