Deploy agent to Azure

L'agente è stato creato e testato in locale, ora è il momento attivarlo nel cloud. Questo passaggio è opzionale e può essere saltato se hai già implementato il tuo agente su qualche cloud (non deve nemmeno essere Azure).

Questa guida ti guida nel distribuire il codice del tuo agente su Azure e pubblicarlo nel centro amministrativo Microsoft, dove diventa un asset rilevabile per la tua organizzazione.

Sono disponibili anche risorse che mostrano come aggiornare l'endpoint di messaggistica se, invece di Azure, hai già implementato il tuo agente ad altri provider cloud come 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 disporre degli elementi seguenti:

Account e autorizzazioni obbligatori

• Sottoscrizione Azure con accesso contributore.
• Codice agente funzionante con un endpoint di messaggistica valido e raggiungibile. Assicurati di aver testato il tuo agente localmente e opzionalmente testato con Microsoft 365 usando Dev Tunnels per verificare che il codice dell'agente possa essere compilato e funzioni come previsto.
• Completa il passaggio del blueprint dell'agente di configurazione per avere un blueprint valido dell'agente.
• Assicurati che i file a365.config.jsona365.generated.config.json di configurazione e il file di configurazione nel codice (ad esempio file .env) siano aggiornati.

Strumenti necessari

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

Distribuzione su Azure

Il a365 deploy comando ha due sottocomandi:

• a365 deploy app - Distribuire il codice del tuo agente sull'Azure Web App creata durante l'installazione.
• a365 deploy mcp - Aggiorna i permessi del server MCP sul tuo project dell'agente.

Questa guida si concentra sul disezionamento del codice dell'applicazione del tuo agente su Azure.

Deploy agent application

Esegui il a365 deploy comando:

a365 deploy

Opzioni di distribuzione

Il comando deploy supporta diverse opzioni utili:

Distribuzione esempio

# Preview what will be deployed
a365 deploy --dry-run

# Deploy with verbose logging for troubleshooting
a365 deploy --verbose

# Inspect the deployment package before uploading
a365 deploy --inspect

Come funziona la distribuzione

Il deployment funziona in modo diverso a seconda del linguaggio di programmazione che usi.

Verificare la distribuzione

Dopo la fine del deployment, utilizza questa lista e le istruzioni qui sotto per verificare il deployment

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

Verifica il comando di distribuzione completato senza errori

Quando esegui il comando deploy dovresti vedere:

✓ Build completed successfully
✓ Deployment completed successfully

Dovresti anche vedere il successo indicato nei log di deployment:

1. Cerca la configurazione webAppName e vai alla tua Web App nel portale 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. Naviga su Azure Portal > La tua Web App
2. Dispiegamento>Centro di Schieramento
3. Visualizza i log per la tua ultima distribuzione

Se la build 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 delle web app nel portale Azure:

1. Cerca l'app web per nome nel portale Azure.
2. Vai a Panoramica>>Stream 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 Application crashs all'avvio.

Verifica che le variabili dell'ambiente siano configurate

Nel portale di Azure:

1. Naviga nella tua Web App.
2. Vai su Impostazioni>Variabili dell'ambiente.
3. Verifica che le tue impostazioni esistano

Se le variabili di ambiente non sono impostate:

• Riesegui, distribuisci la sincronizzazione dal .env file.
• Oppure impostate manualmente in Azure Portal.
• Vedi Variabili di ambiente non impostate o errate.

Verifica le risposte dell'endpoint dei messaggi

Controlla che l'endpoint che trovi nella pagina panoramica della tua app web esista tramite Powershell o altri mezzi. Altrimenti vedi 404 sull'endpoint della 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 il dispiegamento degli agenti su Azure.

Il comando di dispiegamento fallisce

Sintomo: Errore durante a365 deploy l'esecuzione del comando.

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
  

• Configurazione mancante

  Assicurati che entrambi i file di configurazione esistano e siano corretti:

  # Verify configuration files exist
  Test-Path a365.config.json
  Test-Path a365.generated.config.json
  
  # Display configuration file contents
  a365 config display
  
  # Display generated configuration file contents
  a365 config display -g
  

• Autenticazione Azure scaduta

  Accedi di nuovo ad Azure:

  az login
  az account show  # Verify correct subscription
  

• Web App non creata

  Elenca le Web App per confermare l'esistenza del target:

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

  Se l'app web non esiste, riavvia la configurazione:

  # Verify setup was completed
  a365 config display -g
  # Check for: webAppName
  
  # Check Azure resources exist
  az resource list --resource-group <your-resource-group>
  

• 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: Il deployment ha successo ma l'app Web non è in esecuzione.

Soluzione: Usa az webapp start e az webapp show avvia l'app web e verifica 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 si avvia ma va subito in crash; I log mostrano errori.

Cause comuni:

• Dipendenze mancanti - Controlla l'output della build inclusa in tutti i pacchetti richiesti
• Variabili di ambiente mancanti - Verifica che tutte le impostazioni richieste siano configurate
• Discorrispondenza delle versioni runtime - Assicurati che Azure runtime corrisponda al tuo ambiente di sviluppo
• Errori di codice - Controlla i log delle applicazioni per 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

# Re-run deployment (it will update app settings from .env)
a365 deploy

Problemi con i pacchetti di distribuzione

Sintomo: Il deployment viene caricato ma l'applicazione non si avvia correttamente.

Soluzione: Usa il a365 deploy --inspect flag per esaminare il pacchetto di deployment:

# Inspect what will be deployed
a365 deploy --inspect

Questo flag si pausa prima del caricamento, permettendoti di:

• Controlla il contenuto della cartella di pubblicazione
• Verifica contenuti ZIP
• Assicurati che tutti i file siano inclusi

Problemi comuni da controllare:

• Mancante node_modules (Node.js)
• DLL compilate mancanti (.NET)
• Pacchetti Python mancanti

La build ha successo localmente ma fallisce in Azure

Sintomo: Il codice si compila bene sulla tua macchina ma fallisce durante la distribuzione di Azure.

Soluzioni:

• Controlla dipendenze specifiche per piattaforma

  • Alcuni pacchetti hanno build specifiche per piattaforma.
  • Assicurati che le dipendenze supportino Linux (Azure Web Apps funzionano su Linux di default).

• Verifica la corrispondenza delle versioni runtime

  Eseguire i comandi seguenti:

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

  Confronta con l'esecuzione di Azure in Portal: Impostazioni>Impostazioni>Impostazioni>generali Impostazioni dello stack.

• Prova con il logging verboso

  a365 deploy --verbose
  

Per ulteriore aiuto, vedi: Risoluzione dei problemi degli endpoint di messaggistica