Agent in Azure bereitstellen

Sie haben Ihren Agent erstellt und lokal getestet. Jetzt bringen Sie ihn in der Cloud zum Leben. Dieser Schritt ist optional. Sie können diesen Schritt überspringen, wenn Sie Ihren Agent bereits in einer Cloud bereitgestellt haben (es muss nicht einmal Azure sein).

Diese Anleitung führt Sie durch die Bereitstellung Ihres Agent-Codes in Azure und die Veröffentlichung im Microsoft Admin Center, wo er zu einem registrierten Objekt für Ihre Organisation wird.

Um den Messaging-Endpunkt zu aktualisieren, konsultieren Sie bitte die folgenden Ressourcen. Sie zeigen, wie Sie den Messaging-Endpunkt aktualisieren können, wenn Sie Ihren Agent bei anderen Cloud-Anbietern wie Amazon Web Services oder Google Cloud Platform bereitgestellt haben:

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

Voraussetzungen

Bevor Sie beginnen, sollten Sie sicherstellen, dass folgende Elemente vorhanden sind:

Erforderliche Konten und Berechtigungen

• Azure-Abonnement mit Mitwirkendenzugriff.
• Funktionsfähiger Agentcode mit einem gültigen und erreichbaren Messaging-Endpunkt. Vergewissern Sie sich, dass Sie Ihren Agent lokal getestet und optional mit Microsoft 365 über Entwicklertunnel getestet haben, um sicherzustellen, dass der Agentcode wie erwartet gebaut und ausgeführt werden kann.
• Erstellen Sie einen gültigen Agenten-Blueprint, indem Sie den Schritt Agenten-Blueprint einrichten ausführen.
• Aktuelle Konfigurationsdateien a365.config.json, a365.generated.config.json und eine Konfigurationsdatei im Projekt (z. B. .env-Datei).

Notwendige Werkzeuge

• Azure CLI, die installiert und authentifiziert wurde (Installieren der Azure CLI)

Bereitstellung in Azure

Stellen Sie Ihren Agent-Anwendungscode mithilfe von Standard-Azure-Tools wie der Azure CLI, dem Azure-Portal oder GitHub Actions in Azure bereit.

Agent-Anwendung bereitstellen

Führen Sie den Azure CLI az webapp deploy-Befehl aus, um Ihre Anwendung bereitzustellen:

# 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

Für GitHub Actions verwenden Sie die Azure Web-Apps Deploy-Aktion.

Warnung

Geheimnisverwaltung: Speichern Sie Umgebungsvariablen, einschließlich API-Schlüsseln und Geheimnissen, als Azure-App-Einstellungen anstatt in Code- oder Konfigurationsdateien. Für Produktionsumgebungen empfiehlt Microsoft die Verwendung von Azure Key Vault für vertrauliche Geheimnisse. Weitere Informationen finden Sie unter Sicheres Speichern von App-Geheimnissen bei der Entwicklung in ASP.NET Core und Azure Key Vault-Konfigurationsanbieter. Übergeben Sie niemals .env-Dateien mit vertraulichen Informationen an die Quellcodeverwaltung.

Überprüfen der Bereitstellung

Nachdem die Bereitstellung abgeschlossen ist, verwenden Sie diese Liste und die Anweisungen in den folgenden Abschnitten, um die Bereitstellung zu verifizieren.

✅ Bereitstellungsbefehl wurde fehlerfrei ausgeführt
✅ Web-App wird ausgeführt
✅ Anwendungsprotokolle zeigen den erfolgreichen Startup
✅ Umgebungsvariablen sind konfiguriert
✅ Messaging-Endpunkt reagiert

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

Nach Abschluss der Bereitstellung überprüfen Sie den Erfolg in den Bereitstellungsprotokollen:

1. Navigieren Sie im Azure-Portal zu Ihrer Web-App.
2. Gehen Sie zu Einstellungen>Konfiguration, um die App-Einstellungen zu überprüfen.
3. Überprüfen Sie die Bereitstellungsprotokolle im Deployment Center.

Um die detaillierte Bereitstellungshistorie einzusehen:

1. Navigieren Sie zum Azure Portal > Ihre Web-App
2. Bereitstellung>Deployment Center
3. Protokolle Ihrer neuesten Bereitstellung anzeigen

Wenn der Build fehlschlägt:

• Bereinigen und erstellen Sie das Projekt zunächst lokal neu, um zu bestätigen, dass der Build funktioniert.
• Prüfen Sie auf fehlende Abhängigkeiten oder Syntaxfehler.
• Siehe Fehler beim Bereitstellen-Befehl.

Wenn die App nach der Bereitstellung abstürzt:

• Überprüfen Sie die Protokolle auf spezifische Fehlermeldungen.
• Stellen Sie sicher, dass alle erforderlichen Umgebungsvariablen festgelegt sind.
• Siehe Anwendungsabstürze beim Start.

Überprüfen Sie, ob die Web-App läuft

Verwenden Sie den az webapp show-Befehl, um zu überprüfen, ob die Web-App 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

Um Web-App-Logs im Azure-Portal anzuzeigen:

1. Suchen Sie im Azure-Portal anhand ihres Namens nach der Web-App.
2. Gehen Sie zu Übersicht>Protokolle>Log-Stream.

Alternativ können Sie den PowerShell-az webapp log tailBefehl verwenden, um die Web-App-Protokolle anzuzeigen:

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

Falls Abstürze oder Fehlermeldungen in den Logs auftreten, siehe Anwendung stürzt beim Start ab.

Bestätigen Sie, dass Umgebungsvariablen konfiguriert sind

Im Azure-Portal

1. Navigieren Sie zu Ihrer Web-App.
2. Navigieren Sie zu Einstellungen>Umgebungsvariablen.
3. Überprüfen Sie, ob Ihre Einstellungen vorhanden sind.

Wenn die Umgebungsvariablen nicht gesetzt sind:

• Führen Sie die Bereitstellung erneut aus, um aus der .env-Datei zu synchronisieren.
• Oder manuell im Azure-Portal festlegen.
• Siehe Umgebungsvariablen nicht gesetzt oder falsch.

Überprüfen, ob der Messaging-Endpunkt antwortet

Überprüfen Sie, ob der Endpunkt, den Sie auf der Seite Übersicht Ihrer Web-App finden, existiert, indem Sie PowerShell oder andere Methoden verwenden. Ansonsten siehe 404 am Messaging-Endpunkt.

Nächste Schritte,

Veröffentlichen Sie anschließend Ihre Agent-Anwendung im Microsoft Admin Center, damit Sie daraus Agent-Instanzen und Benutzer anlegen können.

Ihren Agent veröffentlichen

Ihr Agent ist jetzt live in der Cloud und bereit, auf agentische Anfragen zu reagieren. Berücksichtigen Sie die nächsten Schritte für Ihren Code, wenn Ihr Agent reale Anforderungen verarbeitet:

• Leistung überwachen: Verwenden Sie Einblick-Funktionen zum Nachverfolgen des Agent-Verhaltens und Optimieren von Antworten.
• Weitere Tools hinzufügen: Erkunden Sie den Toolkatalog, um die Funktionen Ihres Agents zu erweitern.
• Iterieren und verbessern: Aktualisieren Sie Ihren Agent-Code, stellen Sie ihn erneut bereit und veröffentlichen Sie ihn wieder (denken Sie daran, die Versionsnummer zu erhöhen!).
• Organisationsweit skalieren: Teilen Sie die Erfolgsgeschichten Ihres Agents, um die Einführung zu beschleunigen.

Problembehandlung

Dieser Abschnitt beschreibt häufige Probleme beim Bereitstellen von Agents in Azure.

Trinkgeld

Die Agent 365 Troubleshooting-Anleitung enthält übergeordnete Empfehlungen zur Fehlerbehebung, Best Practices und Links zu Inhalten zur Fehlerbehebung für jeden Abschnitt des Entwicklungszyklus von Agent 365.

Der Bereitstellen-Befehl schlägt fehl

Symptom: Bereitstellung in Azure schlägt fehl.

Häufige Ursachen und Lösungen:

• Erstellungsfehler

  Erstellen Sie das Projekt lokal neu, um detaillierte Kompilierungsfehler zu sehen:

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

• Azure-Authentifizierung abgelaufen

  Melden Sie sich bei Azure neu an:

  az login
  az account show  # Verify correct subscription
  

• Web-App nicht erstellt

  Listen Sie Web-Apps auf, um zu bestätigen, dass das Ziel existiert:

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

• Bereitstellungsprotokolle überprüfen

  Verwenden Sie den az webapp log tail Befehl, um detaillierte Bereitstellungsprotokolle 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"
  

Web-App ist gestoppt

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

Lösung: Verwenden Sie az webapp start und az webapp show, um die Web-App zu starten, und überprüfen Sie, ob sie ausgeführt wird.

# 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

Web-App stürzt beim Start ab

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

Häufige Ursachen:

• Fehlende Abhängigkeiten – Überprüfen Sie die Build-Ausgabe, um sicherzustellen, dass alle erforderlichen Pakete enthalten sind.
• Fehlende Umgebungsvariablen – Überprüfen Sie, ob alle erforderlichen Umgebungsvariablen konfiguriert sind.
• Nicht übereinstimmende Runtime-Version – Vergewissern Sie sich, dass die Azure-Laufzeitumgebung mit Ihrer Entwicklungsumgebung übereinstimmt.
• Codefehler – Überprüfen Sie die Anwendungsprotokolle auf spezifische Ausnahmen.

Lösung: Verwenden Sie die Befehle az webapp log tail, az webapp config appsettings list und az webapp config appsettings set, um Protokolle anzuzeigen, Umgebungsvariablen 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-Fehler am Messaging-Endpunkt

Symptom: Web-App läuft, aber /api/messagesder Endpunkt liefert einen 404-Fehler.

Lösung:

1. Überprüfen Sie die Routenkonfiguration in Ihrem 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 Anforderung an die URL senden. Verwenden Sie den az webapp config show-Befehl, 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>

Umgebungsvariablen fehlen oder sind falsch konfiguriert

Symptom: Die Bereitstellung ist erfolgreich, aber der Agent funktioniert nicht; Fehler aufgrund fehlender Konfiguration in den Protokollen.

Lösung: Überprüfen und aktualisieren Sie die Umgebungsvariablen. Verwenden Sie die az webapp config appsettings list- und az webapp config appsettings set-Befehle, um die Umgebungsvariablen 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

Build läuft lokal erfolgreich, schlägt aber in Azure fehl

Symptom: Der Code wird lokal erfolgreich gebaut, aber die Bereitstellung in Azure schlägt fehl.

Lösungen:

• Prüfen Sie plattformspezifische Abhängigkeiten

  • Einige Pakete haben plattformspezifische Builds.
  • Stellen Sie sicher, dass Ihre Abhängigkeiten mit Linux kompatibel sind (Azure Web-Apps laufen standardmäßig unter Linux).

• Überprüfen Sie die Übereinstimmung der Laufzeitversionen

  Führen Sie die folgenden Befehle aus:

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

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

Weitere Informationen finden Sie unter: Messaging-Endpunkt-Fehlerbehebung.