Einen einzelnen Agenten mit der Agent 365 CLI onboarden

Verwenden Sie die Agent 365 CLI, um die Microsoft Entra-Identitätsobjekte für einen Agenten zu erstellen, und registrieren Sie den Agenten bei Agent 365. Beginne mit einem Non-Production-Agenten, damit du Identität, Berechtigungen, Zustimmung und Registrierung validieren kannst, bevor du mehrere Agenten gleichzeitig registrierst.

Dieser Artikel verwendet Expense Review als Basisbezeichnung für einen Standardagenten, der Spesenberichte im Auftrag eines angemeldeten Mitarbeiters prüft. Es verwendet eine On-Behalf-Of-(OBO)-Authentifizierung und benötigt kein eigenes Microsoft Entra-Benutzerkonto, Postfach oder keine Teams-Präsenz.

Der konfigurationsfreie Workflow erzeugt:

  • Ein Agenten-Identitätsblueprint namens Expense Review Blueprint.
  • Eine Agentenidentität namens Expense Review Agent.
  • Erteilung delegierter Berechtigungen für die OBO-Authentifizierung.
  • Eine Registrierung von Agent 365 für den Agenten.
  • Eine a365.generated.config.json Datei, die die generierten Identifikatoren und den Einrichtungsstatus aufzeichnet.

Für eine Erklärung der Identitätsobjekte siehe Agent 365 Identität.

Prerequisites

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

  • Ein Microsoft-Tenant mit aktiviertem Agent 365. Verwenden Sie für diesen Walkthrough einen Nicht-Produktionstenant oder Testumgebung.
  • Ein Azure-Abonnement im selben Tenant.
  • Die Rolle Mitwirkender im Azure-Abonnement.
  • Zumindest die Rolle des Agent-ID-Entwicklers in Microsoft Entra ID ist erforderlich, um den Blueprint und die Agentenidentität zu erstellen.
  • Ein globaler Administrator steht zur Verfügung, um OAuth-Berechtigungen zu erteilen. Wenn du diese Rolle innehast, kannst du den Workflow in einer Sitzung abschließen. Andernfalls stellt die CLI Einwilligungs-URLs zum Senden an einen globalen Administrator bereit.
  • Du benötigst die Rolle des Anwendungsadministrators oder des globalen Administrators, wenn du das Szenario auf Service-to-Service-(S2S)-Authentifizierung änderst.
  • .NET 8.0 oder neuer.
  • Die Azure CLI, bei dem Mandanten und Abonnement, die du verwenden möchtest, angemeldet.
  • Die Agent 365 CLI.

Die Agent-365-Einrichtung verwendet die von Microsoft verwaltete Agent 365 CLI-Unternehmensanwendung, wenn sie in Ihrem Tenant verfügbar ist. Die Anwendungs-(Client-)ID ist f54280f4-395e-4ea8-9e48-bf2d4952aa14. Wenn die Anwendung nicht verfügbar ist, sucht die CLI nach einer mandanteneigenen Anwendung namens Agent 365 CLI. Ein Global Administrator kann eine tenant-eigene Anwendung über die CLI-Eingabe erstellen und konfigurieren. Details zum Fallback finden Sie unter Registrierung der benutzerdefinierten Client-App für Agent 365 CLI.

Note

Dieses Szenario erzeugt keinen Agent-Nutzer. Agent-Nutzer werden nur benötigt, wenn ein Agent eigene lizenzierte Microsoft 365-Ressourcen benötigt, wie etwa ein Postfach, und stehen nur Mandanten zur Verfügung, die am Frontier-Vorschauprogramm teilnehmen.

Agent 365 CLI installieren

Installieren Sie die CLI als globales .NET-Tool:

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli

Wenn die CLI bereits installiert ist, aktualisieren Sie sie:

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

Überprüfen Sie die Installation:

a365 --version

Für Installationsfehlersuche und unterstützte Dateistandorte siehe Installieren und verwenden Sie die Agent 365 CLI.

Wählen Sie den Mandanten und die Subscription aus

Melden Sie sich bei Azure an:

az login

Zeigen Sie die auf Ihrem Konto verfügbaren Abonnements an:

az account list --output table

Wählen Sie das Abonnement im Mandanten aus, in dem Sie den Agenten integrieren möchten:

az account set --subscription "<subscription-id-or-name>"

Bestätigen Sie den aktiven Mandanten und das Abonnement:

az account show --query "{tenantId:tenantId, subscriptionId:id, subscriptionName:name}" --output table

Trage die Mieter-ID ein. Die CLI erkennt dies vom aktiven Azure CLI-Konto aus. Du kannst es auch explizit angeben, indem du --tenant-id verwendest.

Prüfen Sie die Voraussetzungen

Führen Sie die Anforderungsprüfung aus einem beliebigen Verzeichnis durch:

a365 setup requirements

Der Befehl prüft Authentifizierung, Azure-Zugriff, Mandantenregistrierung, Rollen und die Client-Anwendung. Es geht nach einer fehlgeschlagenen Überprüfung weiter, sodass du alle festgestellten Probleme zusammen überprüfen kannst.

Lösen Sie alle fehlgeschlagenen erforderlichen Prüfungen, bevor Sie weitermachen. Wenn die von Microsoft verwaltete Unternehmensanwendung nicht verfügbar ist, folgen Sie der Aufforderung, um eine tenant-eigene Client-Anwendung auszuwählen oder zu erstellen, und führen Sie dann den Befehl erneut aus.

Von Bedeutung

Verändern Sie die von Microsoft verwaltete Agent 365 CLI-Anwendung nicht. Die CLI validiert ihren Service-Principal und die Scopes in Ihrem Zugriffstoken, ändert jedoch nicht die Anwendungsregistrierung von Microsoft.

Vorschau der Onboarding-Änderungen

Erstelle ein leeres Arbeitsverzeichnis für die generierte Konfiguration und wechsle dann darauf:

New-Item -ItemType Directory -Path .\expense-review-agent
Set-Location .\expense-review-agent

Zeigen Sie eine Vorschau der Änderungen an, ohne Tenant-Objekte zu erstellen:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false `
    --dry-run

Überprüfen Sie die Tenant-ID, abgeleitete Objektnamen, ausgewählte Client-Anwendung, Berechtigungen und Authentifizierungsmodus. Dieses Szenario verwendet den Standard-Authentifizierungsmodus obo , da der Agent für einen angemeldeten Mitarbeiter handelt.

Wenn der erkannte Tenant nicht korrekt ist, geben Sie ihn explizit an:

a365 setup all `
    --agent-name "Expense Review" `
    --tenant-id "<tenant-id>" `
    --aiteammate false `
    --dry-run

Agenten onboarden

Führe denselben Befehl ohne --dry-runaus:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false

Die CLI validiert die Anforderungen erneut, erstellt den Blueprint und die Agentenidentität, konfiguriert delegierte Berechtigungen, registriert den Agenten und schreibt a365.generated.config.json.

Wenn Sie sich als globaler Administrator anmelden, füllen Sie jede Zustimmungsaufforderung aus, die während der Einrichtung geöffnet wird. Wenn Sie stattdessen die Rolle Agent ID Developer oder Agent ID Administrator verwenden, erfüllt die CLI die von Ihrer Rolle erlaubten Schritte und gibt die Einwilligungsaktionen für einen globalen Administrator aus. Senden Sie die generierten Einwilligungs-URLs an den Global Administrator und bitten Sie ihn, jede Berechtigungsgewährung abzuschließen.

Note

Ein konfigurationsfreies Setup geht davon aus, dass der Agent extern gehostet wird. Es erstellt keine Azure-Hosting-Ressourcen und aktualisiert kein Agentenprojekt.

Verifizieren Sie das Onboarding-Ergebnis

Überprüfen Sie die Setup-Zusammenfassung. Jeder erforderliche Schritt sollte als abgeschlossen angezeigt werden. Wenn ein globaler Administrator weiterhin Zustimmung erteilen muss, schließen Sie diese Übergabe ab, bevor Sie das Onboarding als abgeschlossen betrachten.

Inspizieren Sie die generierte Konfiguration:

Get-Content .\a365.generated.config.json | ConvertFrom-Json

Bestätigen Sie, dass die Ausgabe Folgendes enthält:

  • Eine Agenten-Blueprint-ID.
  • Abgeschlossener Einrichtungsstatus ohne offene Einwilligungsaktionen.

Bestätigen Sie, dass die Setup-Zusammenfassung erfolgreiche Agentenidentitätserstellung und Agentenregistrierung anzeigt.

Überprüfen Sie dann die Anmeldung im Microsoft 365 Admin Center:

  1. Navigieren Sie zum Microsoft 365 Admin Center.
  2. Auswählen Agenten>Alle Agenten.
  3. Finden Sie Expense Review Agent.
  4. Öffnen Sie den Agenten und bestätigen Sie, dass seine Identität und Registrierungsdaten mit der generierten Konfiguration übereinstimmen.

Probleme beim Onboarding beheben

Symptom Resolution
Die Anforderungsprüfung meldet den falschen Mandanten oder die falsche Subscription. Führe az account set --subscription "<subscription-id-or-name>", verifiziere das Ergebnis mit az account show, und führe die Anforderungsprüfung erneut durch. Alternativ können Sie a365 setup all an --tenant-id übergeben.
Die von Microsoft verwaltete Agent 365 CLI-Anwendung wird nicht gefunden. Aktualisiere die CLI und führe a365 setup requirements erneut aus. Wenn der gestaffelte Rollout Ihren Mandanten noch nicht erreicht hat, verwenden Sie eine mandanteneigene Client-Anwendung.
Das Setup meldet, dass eine Rolle fehlt. Weisen Sie dem Betreiber die Rollen Contributor und Agent ID Developer zu. Geben Sie etwas Zeit, bis die Zuweisungen übernommen wurden, melden Sie sich erneut an und führen Sie die Anforderungsprüfung erneut durch.
Die Einrichtung ist abgeschlossen, führt jedoch noch ausstehende Einwilligungen auf. Lass einen Globalen Administrator jede von der CLI ausgedruckte Zustimmungs-URL öffnen und die angeforderten Berechtigungen gewähren.
Der Blueprint oder der Identitätstyp existiert, aber der Agent ist nicht in All Agents. Überprüfen Sie die Setup-Zusammenfassung für einen Fehler bei der Agentenregistrierung. Nachdem du den Fehler behoben hast, führe a365 setup all --agent-name "Expense Review" --agent-registration-only erneut aus.
Setup hat die falsche Authentifizierungsmethode ausgewählt. Verwenden Sie den Standard-OBO-Modus, wenn der Agent für einen angemeldeten Benutzer handelt. Verwenden Sie --authmode s2s für Hintergrundarbeiten oder --authmode both, wenn beide Muster benötigt werden. S2S-Berechtigungen erfordern einen Anwendungsadministrator oder einen globalen Administrator.

Weitere CLI-spezifische Lösungen finden Sie unter Agent 365 Troubleshooting.

Nächste Schritte

  • Zuletzt aktualisiert um