Testa un agente locale con un dev tunnel

Un dev tunnel fornisce ad Azure servizio Bot un endpoint HTTPS pubblico che inoltra le richieste al tuo agente in esecuzione in locale. Usa un tunnel quando devi testare tramite Microsoft Teams, Microsoft 365 Copilot o un altro canale che non può connettersi direttamente a localhost.

Per i test che non richiedono un canale ospitato, usa invece Microsoft 365 Agents Playground.

Prerequisites

Prima di iniziare:

• Controlla il tuo agente localmente e identifica la sua porta. I campioni SDK degli agenti usano la porta 3978 di default.
• Provisiona una risorsa Azure Bot e abilita il canale che vuoi testare.
• Configura la connessione dell'agente con credenziali che corrispondono alla risorsa Azure Bot.
• Installa la devtunnel CLI. Per le opzioni di installazione su Windows, macOS e Linux, vedi Crea e ospita un tunnel.

Important

Usa un client secret o un certificato per i test locali tramite un dev tunnel. L'identità gestita e le credenziali federate richiedono che il codice dell'agente venga eseguito nel suo ambiente di hosting Azure configurato.

Avviare l'agente

Esegui l'agente e verifica che il suo endpoint di attività stia ascoltando localmente. L'endpoint predefinito è:

http://localhost:3978/api/messages

Se il tuo progetto utilizza un'altra porta o route, usa quel valore nei passaggi seguenti.

Crea e ospita il tunnel

Accedi ai tunnel di sviluppo:

devtunnel user login

Ospita il port agente locale:

devtunnel host -p 3978 --allow-anonymous

--allow-anonymousAzure servizio Bot permette di raggiungere il punto finale pubblico del tunnel. L'autenticazione tramite agente valida ancora le richieste a /api/messages.

Il comando restituisce un URL pubblico simile a:

https://<tunnel-id>-3978.<region>.devtunnels.ms

Mantieni il comando attivo mentre fai il test.

Configura l'endpoint di messaggistica Azure Bot

1. Nel portale Azure, apri la tua risorsa Azure Bot.

2. Selezionare Impostazioni>Configurazione.

3. Imposta l'endpoint di messaggistica sull'URL del tunnel pubblico seguito dal percorso del tuo agente:

   https://<tunnel-id>-3978.<region>.devtunnels.ms/api/messages
   

4. Salva la configurazione.

Se l'URL del tunnel cambia, aggiorna l'endpoint della messaggistica prima di effettuare un nuovo test. Puoi creare un tunnel persistente con nome se hai bisogno di un URL stabile; vedi il riferimento alla CLI dei tunnel di sviluppo.

Prova tramite il canale

Invia un messaggio all'agente dal canale configurato. La richiesta fluisce dal canale a Azure servizio Bot, attraverso il tunnel di sviluppo e verso l'endpoint locale/api/messages.

Usa l'URL di ispezione del tunnel di sviluppo mostrato dalla CLI per diagnosticare se le richieste raggiungono il tunnel. Usa i log dei tuoi agenti per diagnosticare errori di autenticazione, routing e gestore dopo che la richiesta raggiunge il processo locale.

Warning

Un tunnel pubblico espone la porta locale selezionata a internet. Esegui solo il servizio che intendi testare, mantieni l'autenticazione attiva e ferma il tunnel una volta completato il test.