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.

Voraussetzungen

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 Wert
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:

Umgebung 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.

Voraussetzungen

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 also globale Werkzeuge aus jedem Verzeichnis aufrufen, ohne den Tool-Standort 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.

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.

Tipp

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.

Problembehandlung

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

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.

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 Agent-Instanzen: Agent erscheint nicht in Teams

Kann keine Agenteninstanz in Teams erstellen

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

  • Last updated on