Test agenti utilizzando i Dev Tunnel

Usando Dev Tunnel, è possibile testare l'agente Agent 365 con applicazioni Microsoft 365 (ad esempio Teams, Outlook o Word) mentre l'agente viene eseguito localmente nel computer di sviluppo. Questo approccio collega lo sviluppo locale e i test reali, in modo da poter convalidare il comportamento dell'agente negli ambienti Microsoft 365 effettivi prima della distribuzione nel cloud.

Prerequisiti

Prima di usare Dev Tunnels, assicurati di installare lo strumento a riga di comando Dev Tunnels.

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

Configura il Dev Tunnel

Configurare un dev tunnel per esporre l'endpoint dell'agente locale ai servizi di Microsoft 365.

Crea e inizia un tunnel

1. Accedi al Dev Tunnel:

   devtunnel user login
   

2. Crea un tunnel persistente:

   devtunnel create --allow-anonymous
   

   Questo comando restituisce un ID del tunnel. Salva questo identificatore per un uso futuro.

3. Configura la porta tunnel:

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

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

4. Inizia 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 passo successivo.

Configura l'endpoint di messaggistica agente

Registrare l'URL di Dev Tunnel (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 /api/messages suffisso all'endpoint.

Si veda Imposta l'endpoint di messaggistica agente

Eseguire test con Microsoft 365

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

Test in Microsoft Teams

1. Avvia il tuo agente locale usando le istruzioni in Installa dipendenze e avvia il server applicativo 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 tua console locale per richieste in arrivo e attività degli agenti

Notifiche email di test

Se il tuo agente è configurato per notifiche via email:

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

Testare l'integrazione di Word

Per gli agenti che rispondono ai commenti Word:

1. Aprire un documento Word in cui l'agente ha accesso.
2. Aggiungi un commento che menzioni il tuo agente.
3. Controlla la tua console locale per la notifica.
4. Verificare che la risposta dell'agente venga visualizzata in Word.

Monitorare l'attività del tunnel

Dev Tunnels fornisce ispezione del traffico per aiutare a debugare i 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 di connessione e avvisi.

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

Mantenere le connessioni del tunnel

I Dev Tunnel richiedono che il devtunnel host processo continui a funzionare. Se inattività, problemi di rete o il computer che va in sospensione causano la caduta della connessione, devi riavviarlo.

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 Host Connections mostra 0, il tunnel esiste ma attualmente non è ospitato.

Riavvia un tunnel disconnesso

Se la connessione al tunnel cade, riavvia usando lo stesso ID del tunnel:

devtunnel host <tunnel-id>

L'URL del tunnel rimane lo stesso, quindi non devi aggiornare la configurazione dell'endpoint della messaggistica 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.
• Prevenire lo standby del computer - Configura il sistema affinché rimanga attivo durante le sessioni di test.
• Osserva errori di connessione - Monitora l'uscita del devtunnel host terminale per i messaggi di disconnessione.
• Riavvia dopo che la rete cambia - Se cambi rete o ti riconnetti alla VPN, riavvia il tunnel.

Pulizia

Quando finisci di testare con i Dev Tunnels:

Fermate il tunnel

Premi Ctrl+C nel terminale dove è in esecuzione devtunnel host per interrompere il tunnel.

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

Limitazioni

Considera queste limitazioni durante i test con i Dev Tunnel:

• Solo sviluppo: Usa i Dev Tunnel 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 a tunnel possono occasionalmente cadere e richiedere un riavvio manuale.
• Considerazioni di sicurezza: Il --allow-anonymous flag è 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 i test di Dev Tunnel riusciti:

• Distribuire l'agente nel cloud: Deploy in Azure, Set agent messaging endpoint in AWS o Set agent messaging endpoint in GCP.
• Configura gli endpoint di messaggistica dell'agente: endpoint di messaggistica dell'agente.
• Segui l'intero ciclo di vita dello sviluppo: ciclo di vita dell'Agente 365.

Risoluzione dei problemi

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

Guasto alla connessione al tunnel

Sintomi: Dev Tunnel non si avvia o si disconnette immediatamente.

Soluzioni:

• Verifica di essere loggato: devtunnel user login
• Controlla se un altro processo utilizza la stessa porta
• Assicurati che il firewall permetta connessioni Dev Tunnel
• Elimina e ricrea il tunnel: devtunnel delete <tunnel-id> poi creane uno nuovo

I messaggi non raggiungono l'agente locale

Symptoms: Microsoft 365 indica che il messaggio è stato inviato, ma l'agente locale non lo riceve.

Soluzioni:

• Conferma che il tuo agente sia in attività locale
• Verifica che il tunnel sia attivo: devtunnel list dovrebbe mostrare "Connesso"
• Controlla la configurazione dell'endpoint: a365 config display dovrebbe mostrare l'URL del tuo Dev Tunnel
• Rivedi i log del Dev Tunnel nel terminale che esegue devtunnel host per verificare eventuali errori di connessione.
• Assicurati che la tua porta locale corrisponda alla porta tunnel (entrambe dovrebbero essere 3978 di default)

Errori di autenticazione tramite Dev Tunnel

Sintomi: errori 401 o 403 durante i test attraverso il Dev Tunnel.

Soluzioni:

• Verificare che l'autenticazione con token portatore sia configurata (l'autenticazione con token portatore non funziona con Dev Tunnels per l'integrazione con Microsoft 365).
• Controlla le credenziali del blueprint dell'agente usando a365 config display -g.
• Conferma che il tuo agente abbia i 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, un tempo funzionante, 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.