Bereitstellen des Agents für Azure

Sie haben Ihren Agent erstellt und lokal getestet – jetzt ist es an der Zeit, ihn in der Cloud zum Leben zu erwecken. Dieser Schritt ist optional und kann übersprungen werden, wenn Sie Ihren Agent bereits in einer Cloud bereitgestellt haben (muss nicht einmal Azure werden).

Dieser Leitfaden führt Sie durch die Bereitstellung Ihres Agentcodes nach Azure und Veröffentlichen Sie ihn im Microsoft Admin Center, wo es zu einem auffindbaren Objekt für Ihre Organisation wird.

Es stehen auch Ressourcen zur Verfügung, die zeigen, wie Sie den Messaging-Endpunkt aktualisieren können, wenn Sie Ihren Agenten bereits auf anderen Cloud-Anbietern wie Amazon Web Services oder der Google Cloud Platform und nicht auf Azure bereitgestellt haben:

• Verwenden Sie Agentencode, der in Amazon Web Services bereitgestellt wird
• Verwenden Sie Agentencode, der in der Google Cloud Platform bereitgestellt wird

Voraussetzungen

Bevor Sie beginnen, stellen Sie folgendes sicher:

Erforderliche Konten und Berechtigungen

• Azure Abonnement mit Mitwirkenderzugriff.
• Funktionierender Agentencode mit einem gültigen und erreichbaren Messaging-Endpunkt. Stellen Sie sicher, dass Sie ihren Agent lokal testet haben und optional mit tested with Microsoft 365 using Dev Tunnels um zu überprüfen, ob der Agentcode erstellt und wie erwartet ausgeführt werden kann.
• Schließen Sie den Schritt des Setup-Agenten-Blueprints ab, um einen gültigen Agenten-Blueprint zu haben.
• Stelle sicher, dass die Konfigurationsdateien a365.config.json, a365.generated.config.json sowie die Konfigurationsdatei im Code (z. B. .env-Datei) aktuell sind.

Erforderliche Tools

• Azure CLI installiert und authentifiziert (Install Azure CLI)
• A365 CLI installiert (Agent 365 CLI)

Bereitstellen auf Azure

Das Kommandoa365 deploy hat zwei Unterkommandos:

• a365 deploy app – Stellt Ihren Agentcode in der während des Setups erstellten Azure Web App bereit.
• a365 deploy mcp - Aktualisiert die MCP-Serverberechtigungen auf deinem Agenten-Blueprint.

Dieser Leitfaden konzentriert sich auf die Bereitstellung ihres Agentanwendungscodes für Azure.

Bereitstellen der Agentanwendung

Führe den Befehla365 deploy aus:

a365 deploy

Bereitstellungsoptionen

Der Deploy-Befehl unterstützt mehrere nützliche Optionen:

Beispiel für die Bereitstellung

# 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

Funktionsweise der Bereitstellung

Die Bereitstellung funktioniert je nach verwendeter Programmiersprache unterschiedlich.

Überprüfen der Bereitstellung

Nachdem die Bereitstellung abgeschlossen ist, verwenden Sie diese Liste und die untenstehenden Anweisungen, um die Bereitstellung zu überprüfen

✅ Bereitstellungsbefehl ohne Fehler abgeschlossen
✅ Die Webanwendung läuft
✅ Anwendungsprotokolle zeigen einen erfolgreichen Start
✅ Umgebungsvariablen werden konfiguriert
✅ Messaging-Endpunkt antwortet

Überprüfen Sie, ob der Bereitstellungsbefehl fehlerfrei abgeschlossen ist

Wenn du den Deploy-Befehl ausführst, solltest du sehen:

✓ Build completed successfully
✓ Deployment completed successfully

Sie sollten auch Erfolg in den Bereitstellungsprotokollen finden.

1. Suchen Sie im Azure-Portal nach Ihrer konfigurierten webAppName, und wechseln Sie zu Ihrer Web App.
2. Gehe zur Einstellungskonfiguration>, um die App-Einstellungen zu überprüfen.
3. Überprüfen Sie die Bereitstellungsprotokolle im Bereitstellungszentrum.

Um die detaillierte Einsatzhistorie zu sehen:

1. Navigieren Sie zu Azure Portal > Ihre Web App
2. Einsatz>Einsatzzentrum
3. Sehen Sie sich die Protokolle Ihrer neuesten Bereitstellung an

Wenn der Build fehlschlägt:

• Zuerst lokal reinigen und wieder aufbauen, um sicherzustellen, dass der Bau funktioniert.
• Überprüfe auf fehlende Abhängigkeiten oder Syntaxfehler.
• Siehe Deploy-Befehl fehlschlägt.

Wenn die App nach der Bereitstellung abstürzt:

• Überprüfen Sie die Protokolle auf spezifische Fehlermeldungen.
• Überprüfen Sie, dass alle erforderlichen Umweltvariablen gesetzt sind.
• Siehe Anwendung stürzt beim Start ab.

Überprüfen Sie, ob die Webanwendung läuft

Verwenden Sie den Befehl,az webapp show um zu überprüfen, ob die Webanwendung läuft.

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

Die erwartete Ausgabe dieses Befehls ist Running.

Überprüfen Sie, ob die Anwendungsprotokolle einen erfolgreichen Start zeigen

So zeigen Sie Web-App-Protokolle im Azure-Portal an:

1. Suchen Sie im Azure-Portal nach der Web-App anhand ihres Namens.
2. Gehe zu Überblick>Logs>Log Stream.

Alternativ können Sie den PowerShell-Befehlaz webapp log tail verwenden, um Web-App-Logs zu lesen:

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

Wenn es Abstürze oder Fehlermeldungen in den Logs gibt, siehe Anwendung stürzt beim Start ab.

Überprüfen Sie, ob die Umgebungsvariablen konfiguriert sind

Im Azure Portal:

1. Navigiere zu deiner Web-App.
2. Gehe zu Einstellungen>Umgebungsvariablen.
3. Überprüfe, ob deine Einstellungen existieren

Wenn die Umweltvariablen nicht gesetzt sind:

• Die Bereitstellung erneut ausführen, um die Synchronisation mit der .env Datei durchzuführen.
• Oder manuell in Azure Portal festgelegt.
• Siehe Umgebungsvariablen nicht gesetzt oder falsch.

Überprüfen Sie, ob der Messaging-Endpunkt antwortet

Überprüfen Sie, ob der Endpunkt, den Sie auf Ihrer Web-App Übersichtsseite finden, über Powershell oder andere Mittel existiert. Ansonsten siehe 404 am Messaging-Endpunkt.

Nächste Schritte

Als Nächstes veröffentlichen Sie Ihre Agent-Anwendung im Microsoft Admin Center, damit Sie Agent-Instanzen und Benutzer daraus erstellen können.

Dein Agent ist jetzt live in der Cloud und bereit, auf agentische Anfragen zu reagieren. Während Ihr Agent reale Anfragen bearbeitet, sollten Sie folgende Schritte für Ihren Code in Betracht ziehen:

• Überwachen Sie die Leistung: Nutzen Sie Observability-Funktionen , um das Verhalten der Agenten zu verfolgen und Antworten zu optimieren.
• Fügen Sie weitere Tools hinzu: Entdecken Sie den Werkzeugkatalog, um die Fähigkeiten Ihres Maklers zu erweitern.
• Iterieren und verbessern: Aktualisieren Sie Ihren Agentencode, neu deployen und neu veröffentlichen (denken Sie daran, die Versionsnummer zu erhöhen!).
• Skaliere über deine Organisation hinweg: Teile die Erfolgsgeschichten deines Agenten, um die Adoption zu fördern.

Problembehandlung

In diesem Abschnitt werden häufige Probleme beim Bereitstellen von Agents für Azure beschrieben.

Deploy-Befehl fehlschlägt

Symptom: Fehler während der a365 deploy Befehlsausführung.

Häufige Ursachen und Lösungen:

• Baufehler

  Baue das Projekt lokal neu auf, um detaillierte Kompilierungsfehler zu sehen:

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

• Fehlende Konfiguration

  Stelle sicher, dass beide Konfigurationsdateien existieren und korrekt sind:

  # 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
  

• Azure-Authentifizierung ist abgelaufen

  Melden Sie sich erneut bei Azure an:

  az login
  az account show  # Verify correct subscription
  

• Web-App nicht erstellt

  Web-Apps auflisten, um zu bestätigen, dass das Ziel vorhanden ist:

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

  Wenn es keine Web-App gibt, starte die Einrichtung erneut:

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

• Überprüfen Sie die Bereitstellungsprotokolle

  Verwenden Sie den az webapp log tail Befehl, um detaillierte Deployment-Logs anzusehen:

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

• Überprüfung:

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

Die Web-App ist gestoppt

Symptom: Die Bereitstellung gelingt, aber die Web-App läuft nicht.

Lösung: Nutze az webapp start und az webapp show um die Web-App zu starten und zu überprüfen, ob sie läuft.

# 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

Die Anwendung stürzt beim Start ab

Symptom: Die Web-App startet, stürzt aber sofort ab; Logs zeigen Fehler auf.

Häufige Ursachen:

• Fehlende Abhängigkeiten – Überprüfen Sie, ob die Build-Ausgabe alle erforderlichen Pakete enthält
• Fehlende Umweltvariablen – Überprüfen Sie alle erforderlichen Einstellungen
• Runtime-Versionskonflikt – Stellen Sie sicher, dass Azure Laufzeit Ihrer Entwicklungsumgebung entspricht.
• Codefehler – Überprüfen Sie Anwendungsprotokolle auf spezifische Ausnahmen

Lösung: Verwenden Sie die az webapp log tail, az webapp config appsettings list, und az webapp config appsettings set Befehle, um Logs anzusehen, Umweltvariablen zu überprüfen und fehlende Variablen zu setzen.

# 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 am Messaging-Endpunkt

Symptom: Die Web-App läuft, aber /api/messages der Endpunkt gibt 404 zurück.

Solution:

1. Überprüfe die Routenkonfiguration in deinem Agentencode.
2. Überprüfen Sie, ob der Endpunkt-Handler korrekt registriert ist.
3. Stellen Sie sicher, dass der korrekte Einstiegspunkt bei der Bereitstellung angegeben ist.

Testen Sie den Endpunkt, indem Sie eine GET Anfrage an die URL senden. Verwenden Sie den Befehl,az webapp config show um die Web-App-Konfiguration zu überprüfen.

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

Umweltvariablen sind nicht gesetzt oder falsch

Symptom: Die Deployment gelingt, aber der Agent funktioniert nicht; Fehlende Konfigurationsfehler in Logs.

Lösung: Verifizieren und aktualisieren Sie Umweltvariablen. Verwenden Sie die az webapp config appsettings listBefehle , und az webapp config appsettings set , um Umweltvariablen zu überprüfen und fehlende Variablen zu setzen. Dann erneut bereitstellen.

# 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

Probleme mit Bereitstellungspaketen

Symptom: Die Bereitstellung wird hochgeladen, aber die Anwendung startet nicht korrekt.

Lösung: Verwenden Sie das a365 deploy --inspect-Flag, um das Bereitstellungspaket zu überprüfen.

# Inspect what will be deployed
a365 deploy --inspect

Diese Option pausiert den Vorgang vor dem Hochladen, sodass Sie:

• Überprüfen Sie den Inhalt des Publish-Ordners
• Verifizieren Sie den Inhalt des ZIP
• Stellen Sie sicher, dass alle Dateien enthalten sind.

Häufige Probleme, die du überprüfen solltest:

• Fehlt node_modules (Node.js)
• Fehlende kompilierte DLLs (.NET)
• Fehlende Python Pakete

Build ist lokal erfolgreich, schlägt jedoch in Azure fehl.

Symptom: Code baut auf Ihrem Computer einwandfrei auf, schlägt jedoch während der Azure-Bereitstellung fehl.

Lösungen :

• Prüfen Sie plattformspezifische Abhängigkeiten

  • Einige Pakete haben plattformspezifische Builds.
  • Stellen Sie sicher, dass Abhängigkeiten Linux unterstützen (Azure Web Apps standardmäßig unter Linux ausgeführt werden).

• Überprüfen Sie die Übereinstimmung der Laufzeitversionen

  Führen Sie diese Befehle aus:

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

  Vergleich mit der Azure-Laufzeit im Portal: Einstellungen>Konfiguration>Allgemeine Einstellungen>Stack-Einstellungen.

• Testen Sie mit Verbose-Logging

  a365 deploy --verbose
  

Für weitere Hilfe siehe: Messaging-Endpunkt-Fehlerbehebung