Condividi tramite

Test agenti utilizzando i Dev Tunnel

Importante

Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.

Utilizzando i Dev Tunnel, 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 reali, così puoi validare il comportamento degli agenti negli ambienti Microsoft 365 reali prima di distribuirlo sul cloud.

Prerequisiti

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

Configura il Dev Tunnel

Configura un Dev Tunnel per esporre il tuo endpoint agente locale ai servizi 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.

Suggerimento

Usalo devtunnel list per vedere tutti i tunnel e devtunnel delete <tunnel-id> rimuovere i tunnel che non ti servono più.

Configura l'endpoint di messaggistica agente

Registra l'URL del tuo Dev Tunnel (ad esempio, https://abc123xyz.devtunnels.ms:3978/api/messages) come endpoint di messaggistica agente, così Microsoft 365 sa dove instradare i messaggi. Non dimenticare il /api/messages suffisso all'endpoint.

Si veda Imposta l'endpoint di messaggistica agente

Test con Microsoft 365

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

Testare 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

Integrazione con parole di prova

Per gli agenti che rispondono ai commenti su Word:

  1. Apri un documento Word a cui il tuo agente abbia accesso.
  2. Aggiungi un commento che menzioni il tuo agente.
  3. Controlla la tua console locale per la notifica.
  4. Verifica che la risposta del tuo agente sia presente 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)
  • Port: 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 il sleep del computer - Configura il sistema affinché resti sveglio 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.

Suggerimento

Se il tuo tunnel si disconnette spesso, controlla le impostazioni di rete e le regole del firewall per assicurarti che non stiano bloccando la connessione.

Pulizia

Quando finisci di testare con i Dev Tunnels:

Fermate il tunnel

Premi Ctrl+C il terminale in funzione devtunnel host per fermare 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.

Annotazioni

Il tunnel rimane disponibile per un uso futuro finché non lo elimini esplicitamente usando devtunnel delete <tunnel-id>.

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:

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

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 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 Dev Tunnel nel terminale in esecuzione devtunnel host per 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:

  • Verifica che l'autenticazione agentica sia configurata (l'autenticazione con bearer token non funziona con i Dev Tunnel 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: URL del tunnel precedentemente funzionante non invoglia 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.
  • Last updated on