Bereitstellen des Agents für Azure

Von Bedeutung

Sie müssen Teil des Frontier-Vorschauversionsprogramms sein, um Vorabzugriff auf Microsoft Agent 365 zu erhalten. Frontier verbindet Sie direkt mit den neuesten KI-Innovationen von Microsoft. Frontier-Vorschauversionen unterliegen den bestehenden Vorschauversionsbedingungen Ihrer Kundenvereinbarungen. Da sich diese Funktionen noch in der Entwicklung befinden, können sich ihre Verfügbarkeit und Merkmale im Laufe der Zeit ändern.

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

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.

Informationen zum Aktualisieren des Messaging-Endpunkts finden Sie in den folgenden Ressourcen. Sie zeigen, wie Sie den Messaging-Endpunkt aktualisieren können, wenn Sie Ihren Agent für andere Cloudanbieter wie Amazon Web Services oder Google Cloud Platform 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 sicher, dass Sie über die folgenden Elemente verfügen:

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 getestet und optional mit Microsoft 365 mithilfe von Dev Tunnels getestet haben, um zu überprüfen, ob der Agentcode wie erwartet erstellt und ausgeführt werden kann.
• Gültiger Agent-Blueprint durch Abschließen des Setup-Agent-Blueprint-Schritts.
• Aktuelle Konfigurationsdateien a365.config.json, a365.generated.config.json und Konfigurationsdateien im Code (z. B. env-Datei).

Erforderliche Tools

• Azure CLI installiert und authentifiziert (Install Azure CLI)

Bereitstellen auf Azure

Stellen Sie Ihren Agentanwendungscode in Azure mithilfe von Azure-Standardtools wie azure CLI, Azure-Portal oder GitHub-Aktionen bereit.

Bereitstellen der Agentanwendung

Verwenden Sie den Azure CLI-Befehlaz webapp deploy, 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

Verwenden Sie für GitHub-Aktionen die Azure Web Apps Deploy-Aktion.

Warnung

Verwaltung geheimer Schlüssel: Speichern von Umgebungsvariablen, einschließlich API-Schlüsseln und geheimen Schlüsseln, als Azure-App-Einstellungen und nicht in Code- oder Konfigurationsdateien. Verwenden Sie für Produktionsumgebungen Azure Key Vault für vertrauliche geheime Schlüssel. Erfahren Sie mehr über die sichere Speicherung von App-Geheimnissen in der ASP.NET Core-Entwicklung und den Azure Key Vault-Konfigurationsanbieter. Übergeben Sie niemals .env-Dateien mit vertraulichen Informationen an die Quellcodeverwaltung.

Überprüfen der Bereitstellung

Verwenden Sie nach Abschluss der Bereitstellung diese Liste und die Anweisungen in den folgenden Abschnitten, um die Bereitstellung zu überprüfen.

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

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

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

1. Navigieren Sie im Azure-Portal 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. Wechseln Sie zum 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. Wechseln Sie zu Ihrer Web-App.
2. Gehe zu Einstellungen>Umgebungsvariablen.
3. Überprüfen Sie, ob Ihre Einstellungen vorhanden sind.

Wenn die Umweltvariablen nicht gesetzt sind:

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

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

Testen Sie, dass der Endpunkt, den Sie in Ihrer Web App -Übersichtsseite finden, mithilfe von PowerShell oder anderen Mitteln vorhanden ist. Andernfalls siehe 404 für den 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.

Ihren Agenten veröffentlichen

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.

Tipp

Der Agent 365 Troubleshooting Guide enthält übergeordnete Empfehlungen zur Fehlerbehebung, Best Practices und Links zu Inhalten zur Fehlerbehebung für jeden Teil des Entwicklungszyklus von Agent 365.

Deploy-Befehl fehlschlägt

Symptom: Die Bereitstellung in Azure schlägt fehl.

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
  

• 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
  

• Ü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 ist erfolgreich, die Web-App wird jedoch nicht ausgeführt.

Lösung: Verwenden Sie az webapp start, um az webapp show 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

Die Anwendung stürzt beim Start ab

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

Häufige Ursachen:

• Fehlende Abhängigkeiten – Überprüfen Sie die Buildausgabe, um sicherzustellen, dass sie alle erforderlichen Pakete enthält.
• Fehlende Umgebungsvariablen – Überprüfen Sie, ob alle erforderlichen Einstellungen konfiguriert sind.
• Nichtübereinstimmung der Laufzeitversion – Stellen Sie sicher, dass die Azure-Runtime Ihrer Entwicklungsumgebung entspricht.
• Codefehler – Überprüfen Sie Anwendungsprotokolle auf bestimmte 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

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.

Weitere Hilfe finden Sie unter: Problembehandlung beim Messaging-Endpunkt.