Distribuire l'agente in Azure

Hai creato il tuo agente e lo hai testato localmente. Ora è il momento di attivarlo nel cloud. Questo passaggio è facoltativo. Puoi saltare questo passaggio se hai già distribuito il tuo agente su una piattaforma cloud (non deve nemmeno essere Azure).

Questa guida illustra come distribuire il codice dell'agente in Azure e pubblicarlo nell'interfaccia di amministrazione di Microsoft, in cui diventa un asset registrato per l'organizzazione.

Per aggiornare l'endpoint di messaggistica, consulta le seguenti risorse. Mostrano come puoi aggiornare l'endpoint di messaggistica se hai distribuito il tuo agente ad altri provider cloud come Amazon Web Services o Google Cloud Platform:

• Usa il codice dell'agente distribuito su Amazon Web Services
• Usa il codice agente distribuito su Google Cloud Platform

Prerequisiti

Prima di iniziare, accertati di avere quanto segue:

Account e autorizzazioni obbligatori

• Abbonamento di Azure con accesso come collaboratore.
• Codice dell'agente operativo con un endpoint di messaggistica valido e raggiungibile. Assicurati di aver testato il tuo agente localmente ed eventualmente di averlo testato con Microsoft 365 usando Dev Tunnels, per verificare che il codice dell'agente possa essere compilato e funzionare come previsto.
• Convalida il blueprint dell'agente completando il passaggio relativo al blueprint dell'agente di configurazione.
• File di configurazione a365.config.jsonaggiornati, a365.generated.config.json e file di configurazione nel codice (ad esempio, file .env).

Strumenti richiesti

• Interfaccia della riga di comando di Azure installata e autenticata (Installa l'interfaccia della riga di comando di Azure)

Distribuisci in Azure

Distribuisci il codice dell'applicazione dell'agente su Azure utilizzando strumenti standard di Azure come l’interfaccia della riga di comando di Azure, il portale di Azure o GitHub Actions.

Distribuire l'applicazione dell'agente

Usa il az webapp deploycomando dell'interfaccia della riga di comando di Azure per distribuire la tua applicazione:

# Build your project first (example for .NET)
dotnet publish -c Release -o ./publish

# Deploy to Azure Web App
az webapp deploy --name <your-web-app> --resource-group <your-resource-group> --src-path ./publish

Per GitHub Actions, usa l'azione Distribuzione delle app Web di Azure.

Verificare la distribuzione

Dopo la fine della distribuzione, utilizza questo elenco e le istruzioni nelle sezioni seguenti sotto per verificare la distribuzione.

✅ Comando di distribuzione completato senza errori
✅ L'app Web è in esecuzione
✅ I log dell'applicazione mostrano l'avvio completato
✅ Le variabili di ambiente sono configurate
✅ L'endpoint di messaggistica risponde

Verifica che il comando di distribuzione sia stato completato senza errori

Dopo il completamento della distribuzione, verifica il completamento nei log di distribuzione:

1. Passare all'app Web nel portale di Azure.
2. Vai a Impostazioni>Configurazione per verificare le impostazioni dell'app.
3. Controlla i log di distribuzione nel centro di distribuzione.

Per vedere la cronologia dettagliata della distribuzione:

1. Accedi al portale di Azure > L'applicazione Web
2. Distribuzione>Centro di distribuzione
3. Visualizzare i log per l'ultima distribuzione

Se la creazione non riesce:

• Pulisci e ricostruisci prima localmente per confermare che la costruzione funzioni.
• Verifica la presenza di dipendenze mancanti o errori di sintassi.
• Vedi Il comando di distribuzione non riesce.

Se l'app si arresta dopo la distribuzione:

• Controlla i registri per messaggi di errore specifici.
• Verifica che tutte le variabili di ambiente obbligatorie siano impostate.
• Vedi L'applicazione si arresta all'avvio.

Verificare che l'app Web sia in esecuzione

Usa il az webapp showcomando per verificare che l'app Web sia in esecuzione.

az webapp show --name <your-web-app> --resource-group <your-resource-group> --query state

L'output previsto di questo comando è Running.

Verifica che i log dell'applicazione mostrino un avvio riuscito

Per visualizzare i log dell'app Web nel portale di Azure:

1. Cerca l'app Web per nome nel portale di Azure.
2. Vai a Panoramica>Log>Flusso di log.

In alternativa, puoi usare il az webapp log tailcomando PowerShell per leggere i log dell'app Web:

az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

Se ci sono messaggi di arresto anomalo o errore nei log, consulta L'applicazione si arresta all'avvio.

Verifica che le variabili di ambiente siano configurate

Nel portale di Azure:

1. Vai all'app Web.
2. Vai su Impostazioni>Variabili di ambiente.
3. Verifica che le impostazioni siano presenti.

Se le variabili di ambiente non sono impostate:

• Ripeti la distribuzione per sincronizzare dal file .env.
• Oppure impostale manualmente nel portale di Azure.
• Consulta Variabili di ambiente non impostate o errate.

Verifica che l'endpoint di messaggistica risponda

Verifica che l'endpoint trovato nella pagina Panoramica della tua app web esista utilizzando PowerShell o altri strumenti. Altrimenti, vedi 404 sull'endpoint di messaggistica.

Passaggi successivi

Successivamente, pubblica la tua applicazione dell'agente nell'interfaccia di amministrazione di Microsoft così puoi creare utenti e istanze di agente da essa.

Il tuo agente ora è attivo nel cloud e pronto a rispondere alle richieste relative agli agenti. Quando l'agente comincia a gestire le richieste reali, considera i passaggi successivi per il codice:

• Monitora le prestazioni: utilizza le funzionalità di osservabilità per tenere traccia del comportamento dell'agente e ottimizzare le risposte.
• Aggiungi altri strumenti: esplora il catalogo degli strumenti per espandere le funzionalità dell'agente.
• Esegui l'iterazione e migliora: aggiorna il codice dell'agente, ridistribuisci e ripubblica (ricordati di incrementare il numero di versione).
• Scalabilità nell'organizzazione: condividi le storie di successo dell'agente per favorire l'adozione.

Risoluzione dei problemi

Questa sezione descrive i problemi comuni nella distribuzione degli agenti su Azure.

Il comando di distribuzione non riesce

Sintomo: la distribuzione su Azure non è riuscita.

Cause comuni e soluzioni:

• Errori di compilazione

  Crea nuovamente il progetto localmente per vedere errori di compilazione dettagliati:

  # .NET
  dotnet clean
  dotnet build --verbosity detailed
  
  # Python
  uv build
  
  # Node.js
  npm install
  npm run build
  

• Autenticazione di Azure scaduta

  Accedi nuovamente a Azure:

  az login
  az account show  # Verify correct subscription
  

• App Web non creata

  Elenca le app Web per confermare che il target esista:

  # List Web Apps in resource group
  az webapp list --resource-group <your-resource-group> --output table
  

• Controlla i log di distribuzione

  Usa il az webapp log tailcomando per visualizzare i log dettagliati della distribuzione:

  az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
  

• Verifica:

  # Web App should be running
  az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
  # Expected: "Running"
  

L'app web si interrompe

Sintomo: la distribuzione è stata completata ma l'app Web non è in esecuzione.

Soluzione: usa az webapp start e az webapp show per avviare l'app Web e verificare che sia in esecuzione.

# Start the Web App
az webapp start --name <your-app> --resource-group <your-resource-group>

# Verify it's running
az webapp show --name <your-app> --resource-group <your-resource-group> --query state

L'applicazione si arresta all'avvio

Sintomo: l'app Web si avvia ma si arresta immediatamente; i log mostrano errori.

Cause comuni:

• Dipendenze mancanti: verifica l'output della creazione per assicurarti che includa tutti i pacchetti richiesti.
• Variabili di ambiente mancanti: verifica che tutte le variabili necessarie siano configurate.
• Mancata corrispondenza della versione runtime: assicurati che il runtime di Azure corrisponda all'ambiente di sviluppo.
• Errori di codice: controlla i log dell'applicazione per eccezioni specifiche.

Soluzione: usa i comandi az webapp log tail, az webapp config appsettings list e az webapp config appsettings set per visualizzare i log, controllare le variabili di ambiente e impostare quelle mancanti.

# View application logs
az webapp log tail --name <your-app> --resource-group <your-resource-group>

# Check environment variables
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Manually set a missing variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings KEY=VALUE

404 sull'endpoint di messaggistica

Sintomo: l'app Web è in esecuzione ma l'endpoint /api/messages restituisce 404.

Soluzione:

1. Verifica la configurazione del percorso nel codice del tuo agente.
2. Controlla che il gestore dell'endpoint sia registrato correttamente.
3. Assicurati che il punto d'ingresso corretto sia specificato durante la distribuzione.

Testa l'endpoint inviando una richiesta GET all'URL. Usa il az webapp config showcomando per controllare la configurazione dell'app Web.

curl https://<your-app-name>.azurewebsites.net/api/messages
az webapp config show --name <your-app> --resource-group <your-resource-group>

Variabili di ambiente non impostate o errate

Sintomo: la distribuzione viene completata, ma l'agente non funziona; nei log compaiono errori dovuti a configurazioni mancanti.

Soluzione: verifica e aggiorna le variabili di ambiente. Usa i comandi az webapp config appsettings list e az webapp config appsettings set per controllare le variabili di ambiente e impostare quelle mancanti. Quindi, esegui nuovamente la distribuzione.

# List all app settings
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Set a specific variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings API_KEY=your-value

La compilazione ha esito positivo in locale, ma ha esito negativo in Azure

Sintomo: il codice viene compilato correttamente sul tuo PC ma non riesce durante la distribuzione su Azure.

Soluzioni:

• Controlla le dipendenze specifiche per piattaforma

  • Alcuni pacchetti hanno versioni specifiche per piattaforma.
  • Assicurati che le dipendenze supportino Linux (le app Web di Azure vengono eseguite su Linux per impostazione predefinita).

• Verifica la corrispondenza delle versioni di runtime

  Eseguire i comandi seguenti.

  # Check your local version
  dotnet --version  # .NET
  node --version    # Node.js
  python --version  # Python
  

  Esegui il confronto con il runtime di Azure runtime nel portale: Impostazioni>Configurazione>Impostazioni generali>Impostazioni stack.

Per ulteriore assistenza, consulta: Risoluzione dei problemi degli endpoint di messaggistica.