Installieren und verwenden Sie die Agent 365 CLI

Die Agent 365 CLI ist ein plattformübergreifendes Befehlszeilen-Tool zur Bereitstellung und Verwaltung von Agent-365-Anwendungen auf Azure. Diese Referenz erklärt, wie man die CLI für Automatisierung und Fehlerbehebung installiert, aktualisiert, deinstalliert und verwendet.

Du musst die CLI nicht manuell installieren.Agent 365 Skills prüfen die CLI, installieren oder aktualisieren sie automatisch und führen alle erforderlichen Befehle in Ihrem Namen aus. Dieser Artikel ist eine Referenz für Entwickler, die die CLI direkt installieren oder nutzen müssen – zum Beispiel beim Bau von CI/CD-Automatisierung, bei der Fehlersuche eines bestimmten Schrittes oder bei der Arbeit ohne KI-Codieragenten.

Note

Der vollständige Entwicklerworkflow – einschließlich KI-geführter Setup, Rollenleitfaden und Schritte nach der Bereitstellung – befindet sich in "Erste Schritte mit der Agent 365-Entwicklung". Dieser Artikel ist die CLI-Referenz: Installation, Update, Deinstallation, verfügbare Befehle und Fehlerbehebung.

Alternative zum Massen-Onboarding

Wenn Sie mehrere Agenten gleichzeitig onboarden müssen, nutzen Sie die PowerShell-Skripte für das Massen-Onboarding von Agent 365 als Alternative, um den a365 CLI-Onboarding-Workflow für jeden Agenten separat auszuführen. Die Skripte stellen Blueprints, Agentenidentitäten, Agent-Benutzer und Agentenregistrierungen aus einer CSV-Datei bereit. Sie sind getrennt von der CLI und sind kein CLI-Befehl.

Für den vollständigen Workflow siehe Bulk Agent 365 Onboarding. Dieser Leitfaden behandelt Voraussetzungen, die Einrichtung der Automatisierungsanwendung, die unterstützten CSV-Felder und Validierungsregeln, Ausführung, Ergebnisse und Fehlerbehebung.

Prerequisites

Die CLI erfordert .NET 8,0 oder höher. Für alle weiteren Voraussetzungen, einschließlich eines Azure-Abonnements und erforderlicher Entra-Rollen, siehe Quickstart: Verbinden Sie einen bestehenden Agenten mit Agent 365.

Microsoft Entra-Authentifizierung

Standardmäßig verwendet die Agent-365-Einrichtung die von Microsoft verwaltete Agent 365 CLI-Unternehmensanwendung, wenn sie in Ihrem Tenant verfügbar ist.

Eigentum Value
Anzeigename Agent 365 CLI
Anwendungs-ID (Client-ID) f54280f4-395e-4ea8-9e48-bf2d4952aa14

Um die Anwendung zu überprüfen, gehen Sie zum Microsoft Entra Admin Center, wählen Sie Unternehmensanwendungen>Alle Anwendungen und suchen Sie nach der Anwendungs-ID. Die Objekt-ID des Service-Principals ist einzigartig für Ihren Mieter. Verwenden Sie nicht die Objekt-ID, bei der die CLI oder Dokumentation nach einer Anwendungs-(Client-)ID fragt.

Die CLI prüft, ob der Service Principal der Unternehmensanwendung in Ihrem Tenant vorhanden ist, und überprüft die erforderlichen delegierten Berechtigungsbereiche im Zugriffstoken. Es erstellt oder ändert die Anwendungsregistrierung von Microsoft nicht. Die von Microsoft verwaltete Anwendung erhöht den angemeldeten Nutzer nicht, umgeht Conditional Access oder Security Defaults nicht und entfernt keine separaten Einwilligungsanforderungen für Agentenressourcen.

Wenn die von Microsoft verwaltete Unternehmensanwendung nicht verfügbar ist, sucht die konfigurationsfreie Einrichtung nach einer tenant-eigenen App namens Agent 365 CLI. Bestehende Konfigurationen, die eine benutzerdefinierte Spezifikation clientAppId angeben, bleiben weiterhin unterstützt. Für Anleitungen siehe Custom Client App Registrierung für Agent 365 CLI.

Die von Microsoft verwaltete Anwendung verwendet diese interaktiven Authentifizierungsmethoden:

Umwelt Authentifizierungsmethode
Windows nativ Web-Kundenbetreuer (WAM)
Windows-Subsystem für Linux (WSL), macOS und Linux Gerätecode

Mietereigene benutzerdefinierte Anwendungen nutzen den Systembrowser, wenn WAM nicht verfügbar ist.

Agent 365 CLI installieren

Führen Sie die folgenden Schritte aus, um die Agent 365 CLI global auf Ihrem Betriebssystem zu installieren.

Prerequisites

Sie müssen .NET installiert haben. (.NET 8.0 wird empfohlen.)

Verwenden Sie dotnet tool install

Installieren Sie die Agent 365 CLI mithilfe des folgenden Befehls:

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

Die neuesten Anweisungen und verfügbaren Versionen finden Sie auf der offiziellen NuGet-Seite: Microsoft.Agents.A365.DevTools.Cli auf NuGet.org

Überprüfen der Installation

Nach der Installation der Agent 365 CLI überprüfen Sie, ob sie korrekt installiert ist, indem Sie den Befehl --help ausführen:

a365 -h

Mit diesem Befehl werden die Hilfeinformationen angezeigt und bestätigt, dass die CLI einsatzbereit ist.

Aktualisieren Sie die Agent 365 CLI

Aktualisieren Sie die Agent 365-CLI mit dem dotnet-Tool-Update-Befehl :

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

Note

Um Agent 365 CLI zu aktualisieren, benötigen Sie eine Internetverbindung, um auf das neueste NuGet-Paket zugreifen zu können: Microsoft.Agents.A365.DevTools.Cli.

Deinstalliere die Agent 365 CLI

Deinstallieren Sie die Agent 365-CLI mit dem dotnet-Tool-uninstall-Befehl:

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

Agent 365 CLI-Dateispeicherorte

Der Standardspeicherort für die ausführbare Datei eines Tools hängt vom Betriebssystem ab:

OS Pfad
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

Das SDK fügt diesen Standort zu deinem Pfad hinzu, wenn du ihn zum ersten Mal startest. Du kannst globale Werkzeuge aus jedem Verzeichnis aufrufen, ohne den Werkzeugstandort anzugeben.

Der Toolzugriff ist benutzerspezifisch und nicht global für Computer. Ein globales Tool steht nur dem Benutzer zur Verfügung, der das Tool installiert.

Clouds der US-Regierung

Standardmäßig zielt die Agent 365 CLI auf die Microsoft Commercial Cloud ab. Es authentifiziert sich unter Verwendung von https://login.microsoftonline.com, ruft Microsoft Graph bei https://graph.microsoft.com auf und ruft Agent 365-Dienste bei https://agent365.svc.cloud.microsoft auf. Um die CLI in einer Microsoft 365 US Government Cloud auszuführen, setzen Sie die Umgebung auf gcc, gcc-high, oder dod, und konfigurieren Sie die Endpunkte für diese Cloud.

Der Name der Umgebung wählt die cloud-spezifischen Einstellungen aus, ändert aber keinen Endpunkt von selbst. Für GCC setzen Sie den Agent 365 Tools Discovery-Endpunkt. Für GCC High und DoD setzen Sie außerdem den Autoritätshost und die Microsoft Graph-Basis-URL.

Setzen Sie die Umgebung, den Autoritätshost und die Graph-Basis-URL in a365.config.json (environment, authorityHost und graphBaseUrl) oder verwenden Sie die in der folgenden Tabelle aufgeführten Umgebungsvariablen. Umgebungsbezogene Variablen enden mit einem normalisierten Cloud-Name-Suffix (<ENV>), wie zum Beispiel GCC oder GCC_HIGH, und haben Vorrang vor den passenden a365.config.json Feldern.

Variable Description
A365_ENVIRONMENT Der Name der Cloudumgebung. Die CLI verwendet diesen Wert, wenn a365.config.jsonenvironment nicht festlegt, und für Befehle, die a365.config.json nicht lesen. Der Standardwert ist prod.
A365_AUTHORITY_HOST_<ENV> Der Host der OAuth-Autorität. Dieser Wert hat Vorrang gegenüber authorityHost in a365.config.json.
A365_GRAPH_BASE_URL_<ENV> Die Microsoft Graph-Basis-URL. Dieser Wert hat Vorrang gegenüber graphBaseUrl in a365.config.json.
A365_DISCOVER_ENDPOINT_<ENV> Der Agent 365 Tools Discovery-Endpunkt. Die CLI verwendet auch ihre Herkunft für verwandte Agent-365-Serviceanrufe.
A365_CREATE_ENDPOINT_<ENV> Die URL zur Registrierung des Messaging-Endpunkts.
A365_DELETE_ENDPOINT_<ENV> Die URL zum Entfernen des Nachrichtenendpunkts.
A365_MCP_APP_ID_<ENV> Die Resource Application ID von Agent 365 Tools, die die CLI verwendet, um Token für Tool-Server zu erhalten. Die meisten Entwickler müssen diese Variable nicht einstellen.

Für Cloud-Endpunktwerte, die <ENV>Suffix-Normalisierungsregeln und vollständige Beispiele siehe Agent 365 CLI für US Government Clouds konfigurieren.

Agent 365 CLI-Befehle

Für die vollständige Liste der verfügbaren Befehle verwenden Sie den --help Befehl oder siehe Agent 365 CLI Reference.

Tip

Sie müssen CLI-Befehle nicht manuell ausführen. Agent 365 Skills automatisieren den gesamten Arbeitsablauf – CLI-Installation, Konfiguration, Blueprint-Einrichtung, Bereitstellung und Veröffentlichung – mithilfe eines KI-Coding-Agenten. Verwenden Sie die CLI-Referenz hier, wenn Sie CI/CD-Automatisierung entwickeln, einen bestimmten Schritt beheben oder ohne einen KI-Codierungs-Agent arbeiten.

Vollständige Anweisungen zum Einrichten eines Agent 365-Agents mithilfe der CLI finden Sie unter Erste Schritte mit der Agent 365-Entwicklung.

Troubleshooting

Dieser Abschnitt bietet Informationen darüber, wie man Fehler mit Agent 365 CLI behebt.

Tip

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.

CLI-spezifische Themen, die in diesem Abschnitt behandelt werden:

Die von Microsoft verwaltete Agent 365 CLI-Anwendung ist nicht verfügbar

Aktualisiere die CLI und führe a365 setup requirements erneut aus. Um zu überprüfen, ob der gestaffelte Rollout Ihren Tenant erreicht hat, suchen Sie in Microsoft Entra nach Anwendungs-ID f54280f4-395e-4ea8-9e48-bf2d4952aa14in Unternehmensanwendungen.

Wenn der Service Principal nicht vorhanden ist, greift das Setup auf eine mandanteneigene App namens Agent 365 CLI zurück. Wenn du diese App noch nicht hast, folge der Registrierung der Custom Client App für Agent 365 CLI.

Die Authentifizierung des Gerätecodes ist blockiert

Die von Microsoft verwaltete Anwendung verwendet Gerätecode-Authentifizierung auf WSL, macOS und Linux. Security Defaults oder eine Conditional-Access-Richtlinie können diesen Ablauf blockieren und AADSTS530035 zurückgeben.

Deaktiviere nicht die Sicherheitsrichtlinie deiner Organisation, um diesen Fehler zu umgehen. Führe die CLI auf nativem Windows aus, um WAM zu nutzen, oder arbeite mit deinem Identitätsadministrator zusammen, um eine kundeneigene Anwendung und einen Authentifizierungsfluss zu nutzen, den deine Richtlinie erlaubt.

Die Authentifizierung scheitert mit AADSTS70007

Ältere CLI-Versionen verwenden möglicherweise mit der von Microsoft verwalteten Anwendung einen nicht unterstützten Browserantwortmodus und geben AADSTS70007 zurück. Update auf die neueste CLI-Version und erneuter Versuch:

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

Erforderliche delegierte Aufgabenbereiche fehlen

Die CLI überprüft die effektiven delegierten Berechtigungen der von Microsoft verwalteten Anwendung anhand des scp-Anspruchs im Zugriffstoken. Aktualisiere die CLI und führe a365 setup requirements erneut aus.

Fügen Sie der von Microsoft verwalteten Anwendung keine Weiterleitungs-URIs, optionalen Ansprüche, API-Berechtigungen oder mandantenlokalen Berechtigungsgewährungen hinzu. Wenn die Validierung weiterhin fehlende Scopes meldet, erfassen Sie die Trace- und Korrelations-IDs aus der Fehlermeldung und kontaktieren Sie den Microsoft-Support. Wenn Sie eine mandanteneigene App verwenden, befolgen Sie die Validierungsschritte unter Registrierung einer benutzerdefinierten Client-App für Agent 365 CLI.

Agent erscheint nicht in Teams

Fehlerbehebung bei der Erstellung von Agenteninstanzen: Agent erscheint nicht in Teams

Kann keine Agenteninstanz in Teams erstellen

Probleme mit Agenteninstanzen beheben: Kann keine Agenteninstanz in Microsoft Teams erstellen

  • Zuletzt aktualisiert um