Einrichtung Agent Blueprint

Der Agenten-Blueprint definiert die Identität, Berechtigungen und Infrastrukturanforderungen Ihres Agenten. Erstellen Sie jede Agenteninstanz aus diesem Agenten-Blueprint.

Weitere Informationen zur Identität von Agent 365 finden Sie unter Identität von Agent 365.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über die folgenden Voraussetzungen verfügen:

1. Agent 365 CLI – Siehe Agent 365 CLI Installation.

2. Erforderliche Berechtigungen:

   • Gültiger Mandantenbenutzer mit einer der folgenden Rollen:
     • Globaler Administrator
     • Administrator der Agenten-ID
     • Agent-ID-Entwickler
   • Zugriff auf ein Azure-Abonnement mit Berechtigungen zum Erstellen von Ressourcen

3. Gültige a365.config.json Datei in deinem Arbeitsverzeichnis, eingerichtet über diesen Schritt: Einrichtung der Agent-365-Konfiguration.

Agenten-Blueprint erstellen

Verwenden Sie den Befehl a365 setup, um Azure Ressourcen zu erstellen und Ihren agent-Blueprint zu registrieren. Der Blueprint definiert die Identitäts-, Berechtigungs- und Infrastrukturanforderungen des Agents. In diesem Schritt wird die Grundlage für die Bereitstellung und Ausführung Ihres Agents in Azure eingerichtet.

Setup ausführen

Führe den Setup-Befehl aus:

a365 setup -h

Der Befehl hat verschiedene Optionen. Man kann das gesamte Setup mit einem einzigen Befehl abschließen, indem man detailliertere Optionen verwendet a365 setup all oder auswählt.

Der gesamte Einrichtungsprozess führt folgende Operationen aus:

1. Creates Azure Infrastructure (sofern noch nicht vorhanden):

   • Ressourcengruppe
   • App Service-Plan mit angegebener SKU
   • Azure Web App mit aktivierter verwalteter Identität

2. Registriert den Agenten-Blueprint:

   • Erstellt den Agent-Blueprint in Ihrem Microsoft Entra Mandanten.
   • Microsoft Entra-Anwendungsregistrierungen erstellen
   • Konfiguriert die Agent-Identität mit den erforderlichen Berechtigungen

3. Konfiguriert API-Berechtigungen:

   • Richtet Microsoft Graph API Bereiche ein
   • Konfiguriert Messaging-Bot-API-Berechtigungen
   • Wendet vererbbare Berechtigungen für Agent-Instanzen an

4. Aktualisiert die Konfigurationsdateien:

   • Speichert generierte IDs und Endpunkte in einer neuen Datei in deinem Arbeitsverzeichnis namens a365.generated.config.json
   • Erfasst verwaltete Identitäts- und Ressourceninformationen

Überprüfen Sie das Setup

Nach Abschluss des Aufbaus sieht man eine Zusammenfassung, die alle abgeschlossenen Schritte zeigt. Überprüfen Sie die erstellten Ressourcen:

1. Überprüfen Sie die generierte Konfiguration:

   a365 config display -g
   

   Die erwartete Leistung umfasst folgende kritische Werte:

   {
   "managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "agentBlueprintClientSecretProtected": true,
   "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMessagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
   "resourceConsents": [],
   "completed": true,
   "completedAt": "xxxx-xx-xxTxx:xx:xxZ",
   "cliVersion": "x.x.xx"
   }
   

   Wichtige Felder zur Verifizierung:

   Feld	Zweck	Was man überprüfen sollte
   managedIdentityPrincipalId	Azure verwaltete Identitätsauthentifizierung	Sollte eine gültige GUID sein
   agentBlueprintId	Die eindeutige Kennung Ihres Agenten	Verwendung im Developer Portal und im Verwaltungszentrum
   agentBlueprintObjectId	Die Microsoft Entra ID von Blueprint
   botMessagingEndpoint	Nachrichtenweiterleitung	Wo Teams/Outlook Nachrichten an Ihren Agent senden
   agentBlueprintClientSecret	Authentifizierungsgeheimnis	Sollte existieren (Wert ist maskiert)
   resourceConsents	API-Berechtigungen	Sollte Ressourcen wie Microsoft Graph, Agent 365-Tools, Messaging Bot-API, Observability-API enthalten
   completed	Aufbaustatus	Sollte so sein true

2. Überprüfen Sie die Azure-Ressourcen im Azure Portal:

   Oder benutze den az resource list PowerShell-Befehl.

   # List all resources in your resource group
   az resource list --resource-group <your-resource-group> --output table
   

   Überprüfen Sie, ob die folgenden Ressourcen erstellt wurden:

   • Ressourcengruppe:

     • Gehe zu Ressourcengruppen Wähle> deine Ressourcengruppe aus
     • Überprüfen Sie, ob sie Ihren App Service-Plan und die Web-App enthält.

   • App Service Plan:

     • Gehen Sie zu App Services>App Service-Pläne.
     • Suchen Sie Ihren Plan, und überprüfen Sie, ob der Tarif Ihrer Konfigurations-SKU entspricht.

   • Web-App:

     • Wechseln Sie zu App Services>Web Apps
     • Suchen Sie Ihre Web-App, und wechseln Sie dann zu Einstellungen>Identität>System zugewiesen.
     • Überprüfen Sie, ob der Status Ein ist.
     • Beachten Sie, ob die Objekt-ID (Prinzipal-ID) mit managedIdentityPrincipalId übereinstimmt.

3. Überprüfen Sie Microsoft Entra Applikationen im Azure Portal:

   Wechseln Sie zu Azure Active Directory>App registrations>All applications:

   • Suchen Sie nach Ihrem Agent-Blueprint nach der agentBlueprintId

   • Öffnen Sie die Anwendung, und wählen Sie API-Berechtigungen aus.

   • Überprüfen Sie, ob Berechtigungen mit grünen Häkchen erteilt werden:

     • Microsoft Graph (delegierte Berechtigungen und Anwendungs-Berechtigungen)
     • Messaging-Bot-API-Berechtigungen

   • Alle Berechtigungen zeigen "Erteilt für [Ihr Mieter]" an.

4. Überprüfen Sie die erstellte Konfigurationsdatei:

   Es sollte eine Datei geben, a365.generated.config.json die alle Konfigurationsdaten enthält.

   Sie können mit dem PowerShell-Befehl Test-Path testen, ob es existiert.

   # Check file exists
   Test-Path a365.generated.config.json
   # Should return: True
   

   Wichtig

   Speichere beide a365.config.json und a365.generated.config.json Dateien. Diese Werte benötigen Sie für die Bereitstellung und Fehlersuche.

5. Überprüfen Sie, ob die Web-App die verwaltete Identität aktiviert hat:

   Verwenden Sie den Befehl,az webapp identity show um zu prüfen, ob die verwaltete Identität aktiviert ist.

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

   Erwartet:

   {
   "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "type": "SystemAssigned"
   }
   

6. Überprüfen Sie den bei Entra registrierten Agenten-Blueprint:

   Suchen Sie im Microsoft Entra Admin Center nach Ihrem agentBlueprintId oder nach Namen.

   Überprüfen Sie Folgendes:

   ✅ App-Registrierung und Enterprise-Anwendung angezeigt
   ✅ Im App-Registrierungsblueprint zeigt der Reiter API-Berechtigungen alle Berechtigungen
   ✅ Der Status zeigt "Gewährt für [Ihren Mieter]"

Weitere Hilfe finden Sie unter:

• Konfigurationsprobleme
• Probleme mit benutzerdefinierten Client-Apps

Nächste Schritte,

Stellen Sie Ihren Agentencode in die Cloud bereit:

Problembehandlung

Dieser Abschnitt beschreibt häufige Probleme beim Einrichten von Agenten-Blueprints.

Diese Probleme treten manchmal während der Registrierung auf:

• Fehler bei unzureichenden Berechtigungen
• Fehlende Azure CLI Authentifizierung
• Eine Ressource existiert bereits
• Admin-Zustimmung nicht abgeschlossen
• Konfigurationsdateien fehlen oder sind ungültig
• Die Einrichtung ist abgeschlossen, aber die Ressourcen werden nicht erstellt
• Agenten-Bauplan nicht bei Entra registriert
• API-Berechtigungen nicht erteilt
• Verwaltete Identität nicht aktiviert
• Der Aufbau dauert zu lange oder bleibt hängen

Fehler bei unzureichenden Berechtigungen

Symptom: Fehler bei Unzureichenden Berechtigungen während a365 setup der Befehlsausführung .

Sie benötigen eine der folgenden Rollen in Ihrem Microsoft Entra Mandanten:

• Globaler Administrator
• Administrator der Agenten-ID
• Agent-ID-Entwickler

Azure-Mitwirkender- oder -Besitzerzugriff.

Lösung: Überprüfen Sie, dass Sie die erforderlichen Berechtigungen in Entra haben.

• Wechseln Sie zu: Microsoft Entra Admin Center> Ihr Profil > Zugewiesene Rollen
• Überprüfen des Azure Abonnementzugriffs mithilfe des PowerShell-Befehls az account show

Fehlende Azure CLI Authentifizierung

Symptom: Die Einrichtung schlägt mit Authentifizierungsfehlern fehl.

Solution: Stellen Sie sicher, dass Sie mit Azure verbunden sind, und überprüfen Sie Ihr Konto und Ihr Abonnement.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Eine Ressource existiert bereits

Symptom: Die Einrichtung schlägt mit Resource already exists einem Fehler für Ressourcengruppe, App Service Plan oder Web App fehl.

Lösungen: Wählen Sie eine der folgenden Lösungen

• Nutze bestehende Ressourcen

  Wenn Ressourcen vorhanden sind und du sie nutzen möchtest, stelle sicher, dass sie mit deiner Konfiguration übereinstimmen. Verwenden Sie den az resource list PowerShell-Befehl.

  az resource list --resource-group <your-resource-group>
  

• Widersprüchliche Ressourcen löschen

  Lösche die Ressourcengruppe oder benenne deine Ressourcen neu a365.config.json und starte die Einrichtung erneut.

  Du kannst den az group delete Powershell-Befehl verwenden, um eine Ressourcengruppe zu löschen.

  # WARNING: This command deletes all resources in it
  az group delete --name <your-resource-group>
  

• Benutze den Aufräumbefehl, um neu anzufangen

  Benutze den cleanup Befehl , um alle Ressourcen von Agent 365 zu entfernen, dann den a365 setup all Befehl , um die Einrichtung erneut auszuführen.

  Warnung

  Laufen a365 cleanup ist zerstörerisch

  a365 cleanup
  a365 setup all
  

Admin-Einwilligung nicht abgeschlossen

Symptom: Browserfenster öffnen sich während der Einrichtung, aber du hast sie ohne Einwilligung geschlossen.

Lösung: Führe den a365 setup all Befehl aus. Die CLI fordert erneut die Zustimmung des Administrators an:

Schließen Sie alle Einwilligungsvorgänge in den angezeigten Browserfenstern ab.

Konfigurationsdateien fehlen oder sind ungültig

Symptom: Die Einrichtung schlägt mit "Konfiguration nicht gefunden" oder Validierungsfehlern fehl.

Solution:

1. Überprüfen Sie, ob die a365.config.json Datei existiert.
2. Anzeige der aktuellen Konfiguration mit dem a365 config display Befehl.
3. Wenn es fehlt oder ungültig ist, initialisiere neu mit dem a365 config init-Befehl.

# Verify a365.config.json exists
Test-Path a365.config.json

# Display current configuration
a365 config display

# If missing or invalid, re-initialize
a365 config init

Die Einrichtung ist abgeschlossen, aber die Ressourcen werden nicht erstellt

Symptom: Setupbefehl ist erfolgreich, aber Azure Ressourcen sind nicht vorhanden.

Solution:

1. Überprüfe erstellte Ressourcen mit dem a365 config display -g Befehl.
2. Überprüfen Sie, ob Azure Ressourcen mit dem Befehl az resource list /> vorhanden sind.
3. Wenn Ressourcen fehlen, überprüfe auf Fehler in der Einrichtungsausgabe und führe sie mit dem a365 setup all Befehl erneut aus.

# Check created resources
a365 config display -g

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Agenten-Bauplan nicht bei Entra registriert

Symptom: Setup ist abgeschlossen, kann jedoch keinen Agent-Blueprint im Microsoft Entra Admin Center finden.

Solution:

1. Abrufen Sie die Blueprint-ID aus der generierten Konfiguration mit dem a365 config display -g Befehl.

   a365 config display -g
   # Look for: agentBlueprintId
   

2. Suchen im Microsoft Entra Admin Center:

   1. Wechseln Sie zu: Microsoft Entra Admin Center.
   2. Navigieren Sie zu App registrations>All applications
   3. Suche nach deinem agentBlueprintId

3. Wenn nicht gefunden, starte die Einrichtung mit dem a365 setup all Befehl erneut.

   a365 setup all
   

API-Berechtigungen nicht erteilt

Symptom: Die Einrichtung wird abgeschlossen, aber die Berechtigungen werden in Entra als "nicht erteilt" angezeigt.

Solution:

1. Öffnen Sie Microsoft Entra Admin Center

2. Finden Sie die Registrierung Ihrer Agenten-Blueprint-App

3. Zu API-Berechtigungen wechseln

4. Erteile die Zustimmung des Administrators:

   1. Wählen Sie Administrator-Erlaubnis für [Ihr Mieter]
   2. Bestätigen Sie die Aktion

5. Überprüfen Sie, dass alle Berechtigungen grüne Häkchen anzeigen

Verwaltete Identität nicht aktiviert

Symptom: Eine Web-App existiert, aber die verwaltete Identität ist nicht aktiviert.

Solution:

1. Überprüfen Sie den Status der verwalteten Identität mit dem az webapp identity show Befehl.
2. Wenn es nicht aktiviert ist, aktiviere es manuell mit dem az webapp identity assign Befehl.
3. Überprüfen Sie mit dem Befehl,az webapp identity show ob es aktiviert ist.

# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

Der Aufbau dauert zu lange oder bleibt hängen

Symptom: Der Setup-Befehl läuft länger als 10 Minuten, ohne abgeschlossen zu werden.

Solution:

1. Überprüfen Sie, ob die Browserfenster auf die Zustimmung warten – schließen Sie alle Einwilligungsflüsse durch.

2. Wenn es wirklich hängt, abbrechen (Strg+C) und prüfen, was erstellt wurde:

   # Check generated config
   a365 config display -g
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. Aufräumen und erneut versuchen:

   a365 cleanup
   a365 setup all