Freigeben über

Agent-Blueprint-Einrichtung

Wichtig

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.

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.
    • Erstellt Microsoft Entra-Anwendungsregistrierungen
    • 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

Anmerkung

Die Einrichtung dauert in der Regel 3 bis 5 Minuten und speichert die Konfiguration automatisch in a365.generated.config.json. Wenn Sie als globaler Administrator ausgeführt werden, öffnet die CLI möglicherweise ein Browserfenster für die Administratorzustimmung – schließen Sie den Zustimmungsfluss ab, um fortzufahren. Wenn Sie als Agent-ID-Administrator oder Entwickler ausgeführt werden, wird kein Browserfenster angezeigt; die CLI generiert Zustimmungs-URLs, damit ein globaler Administrator später abgeschlossen werden kann.

Einrichten mithilfe von Agent ID-Administrator oder Agent-ID-Entwickler

Wenn Sie als Agent ID-Administrator oder Agent-ID-Entwickler (nicht globaler Administrator) ausgeführt werden, a365 setup all werden die meisten Schritte automatisch ausgeführt, aber OAuth2-Berechtigungserteilungen erfordern einen separaten globalen Administratorschritt.

Welche Schritte werden automatisch ausgeführt:

  • Azure-Infrastruktur (Ressourcengruppe, App Service Plan, Web App)
  • Agent-Blueprint-Registrierung
  • Vererbbare Berechtigungen für Agentinstanzen

Für welche Schritte ein globaler Administrator erforderlich ist:

  • Delegierte OAuth2-Berechtigungserteilungen (AllPrincipals Zustimmung) für Microsoft Graph, Agent 365-Tools, Messaging Bot-API, Observability-API und Power Platform-API

So führen Sie die Einrichtung mithilfe eines Nicht-Administratorkontos aus:

# Step 1: Run setup as Agent ID Admin or Developer
a365 setup all
# Setup completes all steps it can. The CLI displays next steps
# showing how a Global Administrator can complete the OAuth2 grants.

# Step 2: Share the config folder with a Global Administrator.
# The folder contains a365.config.json and a365.generated.config.json.

# Step 3: The Global Administrator runs:
a365 setup admin --config-dir "<path-to-config-folder>"

Alternativ kann der globale Administrator die kombinierte Zustimmungs-URL öffnen, die von der CLI gespeichert a365.generated.config.json wird (Feld: combinedAdminConsentUrl) und die Zustimmung in einem einzigen Browserbesuch erteilen. Weitere Informationen finden Sie unter a365 setup admin.

Ü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",
"messagingEndpoint": "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 Blueprints Microsoft Entra ID
    messagingEndpoint 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

    Anmerkung

    Wenn Sie Setup als Agent-ID-Administrator oder Agent-ID-Entwickler ausgeführt haben, ist dies möglicherweise leer und completed kann seinfalse, resourceConsents bis ein globaler Administrator ausgeführt wirda365 setup admin, um die OAuth2-Berechtigungserteilung abzuschließen.

  2. Überprüfen Sie 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 Anwendungen von Microsoft Entra in 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 (Berechtigungen für delegierte und Anwendungen)
      • Messaging-Bot-API-Berechtigungen

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

  4. Überprüfen Sie die erstellte Konfigurationsdatei:

    Sie sollten über eine Datei mit dem Namen a365.generated.config.json verfügen, die alle Konfigurationsdaten enthält.

    Verwenden Sie den PowerShell-Befehl "Testpfad ", um zu überprüfen, ob er vorhanden ist.

    # 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 in Microsoft Entra registrierten Agent-Blueprint:

    Suchen Sie im Microsoft Entra Admin Center nach Ihrem agentBlueprintId 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:

Berechtigungen für Agents

Bevor Apps und Agents Microsoft 365-Daten lesen oder schreiben können (Benutzer, E-Mails, Dateien, Teams, Agents usw.), müssen Sie ihnen explizit Microsoft Graph-Berechtigungen erteilen. Microsoft Graph-Berechtigungen sind das Autorisierungsmodell, das steuert, auf welche Daten und Aktionen eine App oder einen Dienst über Microsoft Graph-APIs in Microsoft 365 und Microsoft Entra-ID zugreifen kann.

Weitere Informationen: Übersicht über Microsoft Graph-Berechtigungen

Um Graph-Berechtigungen für Agent 365-Agentinstanzen zu verwenden, muss der Entwickler sie im Agent-Blueprint deklarieren. Wenn ein Administrator den Blueprint im Microsoft 365 Admin Center aktiviert, überprüft das Portal die Graph-Berechtigungen des Blueprints und fordert den Administrator auf, diesen zuzustimmen.

Um zu verstehen und zu überprüfen, wie Graph-Berechtigungen Ihren Agent aktivieren, können Sie:

Anwenden von Berechtigungen auf Ihren Blueprint

Verwenden Sie diese Einstellung a365 config permissions , um Ihrer Konfiguration die erforderlichen Ressourcenberechtigungen hinzuzufügen, und führen Sie dann aus a365 setup permissions custom , um sie auf Ihren Blueprint in Microsoft Entra anzuwenden.

# Add resource permissions to config
a365 config permissions `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

# Apply permissions to your blueprint
a365 setup permissions custom

Ausführliche Informationen zum Konfigurieren und Entfernen von benutzerdefinierten Berechtigungen finden Sie unter setup permissions custom.

Nächste Schritte,

Stellen Sie Ihren Agentencode in die Cloud bereit:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Agent veröffentlichen im Microsoft Admin Center

Problembehandlung

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

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.

Diese Probleme treten manchmal bei der Registrierung auf:

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

Und Azure-Abonnementmitwirkender oder Besitzerzugriff.

Lösung: Überprüfen Sie, ob Sie über erforderliche Berechtigungen in Microsoft Entra verfügen.

Anmerkung

Wenn Sie über die Rolle "Agent ID-Administrator" oder "Agent ID Developer" verfügen (nicht globaler Administrator), ist es weiterhin erfolgreich, a365 setup all aber sie überspringt OAuth2-Berechtigungserteilungen. Nach Abschluss des Setups muss ein globaler Administrator ausgeführt werden a365 setup admin , um die verbleibenden Finanzhilfen abzuschließen. Dieser Workflow wird für Organisationen erwartet, in denen der Agententwickler und der globale Administrator unterschiedliche Personen sind.

Fehlende Azure CLI Authentifizierung

Symptom: Die Einrichtung schlägt mit Authentifizierungsfehlern fehl.

Lösung: 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: Setup schlägt bei Ressourcengruppe, App Service-Plan oder Web App fehl Resource already exists .

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

  • 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öschen Sie die Ressourcengruppe, oder benennen Sie Ihre Ressourcen in a365.config.json um, und führen Sie die Einrichtung erneut aus.

    Verwenden Sie den az group delete PowerShell-Befehl, 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

    Verwenden Sie den cleanup Befehl, um alle Agent 365-Ressourcen zu entfernen, und verwenden Sie dann den Befehl zum erneuten Ausführen des a365 setup all Setups.

    Warnung

    Das Ausführen a365 cleanup ist destruktiv.

    a365 cleanup
a365 setup all

Symptom: Sie haben Browserfenster während des Setups geöffnet, aber sie ohne Zustimmung geschlossen oder das Setup abgeschlossen, aber OAuth2-Berechtigungserteilungen stehen noch aus.

Lösung: Wählen Sie basierend auf Ihrer Rolle aus:

  • Globaler Administrator: Führen Sie es erneut aus a365 setup all . Die CLI fordert zur Zustimmung des Administrators auf. Schließen Sie den Zustimmungsfluss im angezeigten Browserfenster ab.

  • Agent-ID-Administrator oder Entwickler: Sie können OAuth2-Zuschüsse nicht direkt abschließen. Verwenden Sie den Übergabeworkflow:

    # Option 1: Global Admin runs setup admin
a365 setup admin --config-dir "<path-to-config-folder>"

# Option 2: Global Admin opens the combined consent URL
# Find the URL in a365.generated.config.json (combinedAdminConsentUrl field)
a365 config display -g

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 das Argument fehlt oder ungültig ist, initialisieren Sie es mit dem a365 config init-Befehl erneut.
# 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üfen Sie mithilfe des Befehls nach Fehlern in der a365 setup allSetupausgabe, und führen Sie setup 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

Agent-Blueprint nicht in Microsoft Entra registriert

Symptom: Setup ist abgeschlossen, Aber Sie können den Agent-Blueprint im Microsoft Entra Admin Center nicht 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-Registrierungen>Alle Anwendungen".
    3. Suchen Sie nach Ihrem agentBlueprintId.

  3. Wenn sie nicht gefunden wurde, führen Sie setup mit dem a365 setup all Befehl erneut aus.

    a365 setup all

API-Berechtigungen nicht erteilt

Symptom: Das Setup wird abgeschlossen, die Berechtigungen werden jedoch in Microsoft Entra als "Nicht gewährt" angezeigt.

Solution:

  1. Öffnen Sie Microsoft Entra Admin Center.

  2. Suchen Sie ihre Agent-Blueprint-App-Registrierung.

  3. Gehen Sie zu API-Berechtigungen.

  4. Erteile die Zustimmung des Administrators:

    1. Wählen Sie Administrator-Genehmigung für [Ihr(e) Mandant] gewähren.
    2. Bestätigen Sie die Aktion.

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

Verwaltete Identität nicht aktiviert

Symptom: Web App ist vorhanden, verwaltete Identität ist jedoch nicht aktiviert.

Solution:

  1. Überprüfen Sie den Status der verwalteten Identität mithilfe des az webapp identity show Befehls.
  2. Wenn sie nicht aktiviert ist, aktivieren Sie sie manuell mithilfe des az webapp identity assign Befehls.
  3. Überprüfen Sie, ob sie mithilfe des az webapp identity show Befehls 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>

Setup dauert zu lange oder reagiert nicht mehr

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

Solution:

  1. Wenn Sie als globaler Administrator ausgeführt werden, überprüfen Sie, ob ein Browserfenster auf die Zustimmung des Administrators wartet. Schließen Sie den Zustimmungsfluss ab, um die Blockierung des Setups aufzuheben.

  2. Wenn Setup nicht mehr reagiert, brechen Sie sie ab (STRG+C), und überprüfen Sie, was erstellt wurde.

    # Check generated config
a365 config display -g

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. Bereinigen und Wiederholen.

    a365 cleanup
a365 setup all

Die erste Nachricht in Teams kann nicht gesendet werden.

Symptom: Sobald eine Agentinstanz bereitgestellt wurde, kann sie keine Nachricht als Willkommensnachricht an den Agent-Manager senden.

Lösung: Die [][Chat.Createperm-chatcreate]-Berechtigung ist erforderlich, um ein neues Chatobjekt zu erstellen. Wenn bereits ein Einzelchat vorhanden ist, gibt dieser Vorgang den vorhandenen Chat zurück und erstellt keinen neuen Chat.

  • Konfigurieren Sie zum Implementieren die vererbbaren Berechtigungen Ihres Blueprints , um den Chat.Create Bereich einzuschließen.
  • Konfigurieren Sie eine Teams-Chatnachricht so, dass sie gesendet wird, sobald eine Agentinstanz bereitgestellt wurde.
  • Erstellen Sie eine neue Agentinstanz aus dem Blueprint, und testen Sie die Erste Ausführungsnachricht.
  • Last updated on