Distribuire l'agente in Azure

Hai creato il tuo agente e l'hai testato localmente. Ora, portarlo in vita nel cloud. Questo passaggio è facoltativo. È possibile ignorarlo se l'agente è già stato distribuito in un cloud (non è nemmeno necessario essere Azure).

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

Per aggiornare l'endpoint di messaggistica, vedere le risorse seguenti. Illustrano come aggiornare l'endpoint di messaggistica se l'agente è stato distribuito ad altri provider di servizi cloud, ad esempio Amazon Web Services o Google Cloud Platform:

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

Prerequisiti

Prima di iniziare, assicurarsi di avere gli elementi seguenti:

Account e autorizzazioni obbligatori

• Sottoscrizione Azure con accesso contributore.
• Codice agente funzionante con un endpoint di messaggistica valido e raggiungibile. Assicurarsi di testare l'agente in locale e facoltativamente testato con Microsoft 365 usando Dev Tunnels per verificare che il codice dell'agente possa essere compilato ed eseguito come previsto.
• Completa il passaggio del progetto agente di configurazione per ottenere un progetto agente valido.
• File di configurazione aggiornati, a365.config.json, a365.generated.config.json, e file di configurazione nel codice (ad esempio, file con estensione .env).

Strumenti necessari

• Azure CLI installato e autenticato (Installare Azure CLI)

Distribuire in Azure

Distribuire il codice dell'applicazione agente in Azure usando strumenti standard di Azure, ad esempio l'interfaccia della riga di comando di Azure, il portale di Azure o GitHub Actions.

Distribuire l'applicazione agente

Usare il comando Azure CLI az webapp deploy per distribuire l'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, usare l'azione Distribuisci app Web di Azure.

Verificare la distribuzione

Al termine della distribuzione, usare questo elenco e le istruzioni riportate nelle sezioni seguenti per verificare la distribuzione.

✅ Comando di dispiegamento completato senza errori
✅ L'app web è in esecuzione
✅ I log delle applicazioni mostrano un avvio riuscito
✅ Le variabili ambientali sono configurate
✅ L'endpoint di messaggistica risponde

Verifica il comando di distribuzione completato senza errori

Al termine della distribuzione, verificare l'esito positivo nei log di distribuzione:

1. Vai alla tua app web nel portale di Azure.
2. Vai su Impostazioni>Configurazione per verificare le impostazioni dell'app.
3. Controlla i log di distribuzione nel centro di distribuzione.

Per vedere la storia dettagliata del dispiegamento:

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

Se la compilazione fallisce:

• Pulisci e ricostruisci prima localmente per confermare che la costruzione funzioni.
• Controlla la mancanza di dipendenze o errori di sintassi.
• Vedi il comando Deploy fallisce.

Se l'app va in crash dopo il deployment:

• Controlla i log per messaggi di errore specifici.
• Verifica che tutte le variabili ambientali richieste siano impostate.
• Vedi l'applicazione si blocca all'avvio.

Verifica che l'app web sia in esecuzione

Usa il az webapp show comando 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 atteso di questo comando è Running.

Verifica i log delle applicazioni che mostrano un avvio riuscito

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

1. Cercare l'app Web in base al nome nel portale di Azure.
2. Vai a Panoramica>Registri>Flusso di Registri.

In alternativa, puoi usare il comando PowerShell az webapp log tail per leggere i log delle app web:

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

Se ci sono messaggi di crash o errore nei log, vedi Arresto dell'applicazione all'avvio.

Verifica che le variabili dell'ambiente siano configurate

Nel portale di Azure:

1. Vai alla tua app Web.
2. Vai su Impostazioni>Variabili dell'ambiente.
3. Verificare l'esistenza delle impostazioni.

Se le variabili di ambiente non sono impostate:

• Ripetere la distribuzione per sincronizzare dal file .env.
• In alternativa, impostarli manualmente nel portale di Azure.
• Vedi Variabili di ambiente non impostate o errate.

Verifica che l'endpoint di messaggistica risponda

Verificare che l'endpoint trovato nella pagina Panoramica dell'app Web esista usando PowerShell o altri mezzi. In caso contrario, vedere 404 nell'endpoint di messaggistica.

Passaggi successivi

Successivamente, pubblica la tua applicazione agente nel centro amministrativo Microsoft così puoi creare istanze e utenti di agente da essa.

Il tuo agente ora è attivo nel cloud e pronto a rispondere alle richieste agentiche. Mentre il tuo agente gestisce richieste reali, considera questi prossimi passaggi per il tuo codice:

• Monitorare le prestazioni: utilizzare le funzionalità di osservabilità per monitorare il comportamento degli agenti e ottimizzare le risposte.
• Aggiungi altri strumenti: esplora il catalogo degli strumenti per ampliare le capacità del tuo agente.
• Itera e migliora: aggiorna il codice dell'agente, ridistribuisci e ripubblica (ricordati di incrementare il numero di versione!).
• Scala in tutta la tua organizzazione: condividi le storie di successo del tuo agente per stimolare l'adozione.

Risoluzione dei problemi

Questa sezione descrive i problemi comuni durante la distribuzione degli agenti in Azure.

Il comando di dispiegamento fallisce

Sintomo: La distribuzione in Azure non riesce.

Cause e soluzioni comuni:

• Errori di compilazione

  Ricostruisci 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

  Accedere di nuovo a Azure:

  az login
  az account show  # Verify correct subscription
  

• Web App non creata

  Elenca le applicazioni web per confermare che la destinazione sia presente.

  # 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 tail comando per visualizzare i log dettagliati del deployment:

  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 è interrotta

Sintomo: La distribuzione ha esito positivo, ma l'app Web non è in esecuzione.

Soluzione: Usare 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 blocca all'avvio

Sintomo: L'app Web viene avviata ma si arresta immediatamente in modo anomalo; i log mostrano errori.

Cause comuni:

• Dipendenze mancanti : controllare l'output della compilazione per assicurarsi che includa tutti i pacchetti necessari.
• Variabili di ambiente mancanti : verificare che tutte le impostazioni necessarie siano configurate.
• Mancata corrispondenza della versione di runtime : assicurarsi che il runtime di Azure corrisponda all'ambiente di sviluppo.
• Errori di codice : controllare i log applicazioni per individuare eccezioni specifiche.

Soluzione: Usa i az webapp log tailcomandi , az webapp config appsettings list, e az webapp config appsettings set per visualizzare i log, controllare le variabili di ambiente e impostare le variabili 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 /api/messages l'endpoint restituisce 404.

Soluzione:

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

Testa l'endpoint inviando una GET richiesta all'URL. Usa il az webapp config show comando 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: Il dispiegamento ha successo ma l'agente non funziona; errori di configurazione mancanti nei log.

Soluzione: Verifica e aggiorna le variabili dell'ambiente. Usa i az webapp config appsettings listcomandi , e az webapp config appsettings set per controllare le variabili di ambiente e imposta le variabili mancanti. Poi riimpiolarsi.

# 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 non riesce in Azure.

Symptom: Il codice viene compilato correttamente nel computer ma non riesce durante la distribuzione su Azure.

Soluzioni:

• Controlla dipendenze specifiche per piattaforma

  • Alcuni pacchetti hanno build specifiche per piattaforma.
  • Assicurarsi che le dipendenze supportino Linux (Azure Web Apps eseguite in Linux per impostazione predefinita).

• Verifica la corrispondenza delle versioni runtime

  Eseguire i comandi seguenti:

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

  Confrontare il runtime di Azure nel portale: Impostazioni>Configurazione>Impostazioni generali>Impostazioni dello stack.

Per altre informazioni, vedere Risoluzione dei problemi relativi agli endpoint di messaggistica.