Einrichtung der Agent-365-Konfiguration

Die Agent 365 CLI muss Ihren Mandanten und andere Details kennen, um die erforderlichen Agentressourcen wie Agent Blueprint zu erstellen. Die CLI speichert diese Informationen in einer zentralen Konfigurationsdatei namens a365.config.json in Ihrem Arbeitsverzeichnis. Alle Befehle der CLI verwenden diese Konfigurationsdatei.

Voraussetzungen

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

• Agent 365 CLI – Siehe Agent 365 CLI Installation.

Erforderliche Berechtigungen:

• Gültiger Microsoft Entra Mandantenbenutzer mit einer der folgenden Rollen:
  • Globaler Administrator
  • Administrator der Agenten-ID
  • Agent ID Entwickler

Konfigurieren Sie die Agent 365 CLI

Der a365 config init Befehl erstellt a365.config.json, die zentrale Konfigurationsdatei, die von allen Agent 365 CLI-Befehlen verwendet wird, in Ihrem Arbeitsverzeichnis. Die CLI bietet einen interaktiven Assistenten mit Azure CLI Integration und intelligenten Standardeinstellungen, um manuelle Eingaben zu minimieren.

Initialisieren der Konfiguration

Führe den a365 config init Befehl aus, um den interaktiven Konfigurationsassistenten zu starten:

a365 config init

Der Assistent verwendet Azure CLI Integration und intelligente Standardeinstellungen, um manuelle Eingaben zu minimieren. Es wird aufgefordert, Folgendes einzugeben:

Der Assistent generiert automatisch ressourcenbezogene Namen (Agentidentität, Blueprint, Agent-Benutzer) und überprüft Ihren Projekttyp. Vor dem Speichern können Sie optional benutzerdefinierte Blueprintberechtigungen für externe Ressourcen (z. B. Teams-Anwesenheits- oder OneDrive-Dateien) konfigurieren und alle generierten Namen anpassen.

Erfahren Sie mehr über die Konfigurationsdateistruktur

Berechtigungen für benutzerdefinierte Blueprints

Wenn Ihr Agent Zugriff auf Ressourcen benötigt, die über den Standardsatz hinausgehen (Microsoft Graph, Messaging Bot-API, Observability-API, Power Platform), deklarieren Sie sie im Feld customBlueprintPermissions von a365.config.json:

{
  "customBlueprintPermissions": [
    {
      "resourceAppId": "00000003-0000-0000-c000-000000000000",
      "resourceName": "Microsoft Graph",
      "scopes": ["Mail.Read", "Mail.Send"]
    },
    {
      "resourceAppId": "<your-api-app-id>",
      "resourceName": "My Custom API",
      "scopes": ["MyApi.ReadWrite"]
    }
  ]
}

Nachdem Sie a365.config.json benutzerdefinierte Berechtigungen hinzugefügt haben, wenden Sie sie auf Ihr Blueprint an:

a365 setup permissions custom

Oder fügen Sie sie in das vollständige Setup ein:

a365 setup all

Agent-365-Konfigurationsdateien überprüfen

Agent 365 verwendet während des gesamten Entwicklungslebenszyklus mehrere Konfigurationsdateien:

Nach Abschluss der Konfiguration überprüfen Sie, ob Sie folgende Elemente haben:

Überprüfen Sie die Erstellung der a365.config.json Datei

Überprüfen Sie visuell, ob die a365.config.json Datei existiert. Oder verwenden Sie den PowerShell-Befehl Test-Path in einem Skript, um diese Verifikation zu automatisieren.

# Check file exists in current working directory
Test-Path a365.config.json
# Should return: True

Konfigurationsdaten überprüfen a365.config.json

Führe den a365 config display Befehl aus, um die aktuelle Agent 365 CLI-Konfiguration anzuzeigen.

a365 config display

Die Ausgabe dieses Befehls sieht so aus:

{
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "environment": "prod",
  "aiTeammate": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "agentIdentityDisplayName": "your-agent-name Identity",
  "agentBlueprintDisplayName": "your-agent-name Blueprint",
  "agentUserPrincipalName": "youragent@yourtenant.onmicrosoft.com",
  "agentUserDisplayName": "your-agent-name Agent User",
  "managerEmail": "manager@yourtenant.com",
  "agentUserUsageLocation": "usage-location",
  "deploymentProjectPath": "C:\\path\\to\\your\\project",
  "agentDescription": "your-agent-name - Agent 365 Agent"
}

Verifikationscheckliste

✅ Alle Felder haben gültige Werte (keine leeren Zeichenketten oder Nullen)
✅ tenantId ist eine gültige GUID
✅ clientAppId ist eine gültige GUID (deine benutzerdefinierte Client-App-Registrierung)
✅ managerEmail verwendet deine Mandanten-Domain
✅ deploymentProjectPath weist auf dein Agentencode-Verzeichnis
✅ agentUserPrincipalName folgt dem Format agentname@tenant.com
✅ environment wird festgelegt (typischerweise prod)

Wenn deine Konfiguration nicht dem erwarteten Ergebnis entspricht, siehe den Abschnitt Fehlerbehebung für detaillierte Lösungen.

Füge der a365.generated.config.json-Datei .gitignore hinzu. Diese Datei enthält generierte Geheimnisse und sollte niemals in ein Versionsverwaltungssystem überführt werden.

Nächster Schritt

Wenn alles in Ordnung ist, bist du bereit fortzufahren.

Konfigurationsfreies Setup mit --agent-name

Sie können Agents (nicht KI-Teamkollegen) bereitstellen, ohne eine a365.config.json Datei zu erstellen. Die CLI löst automatisch die erforderlichen Werte zur Laufzeit auf.

# Provision an Agent without a config file
a365 setup all --agent-name <your-agent-name>

Wenn Sie --agent-name bereitstellen:

• Die CLI erkennt die Mandanten-ID automatisch von az account show. Überschreiben Sie es --tenant-id <id> bei Bedarf.
• Die CLI findet eine Entra-App-Registrierung mit dem Namen Agent 365 CLI im Mandanten, um die Client-App aufzulösen. Sie müssen clientAppId nicht in die Konfiguration einschließen.
• Der Pfad des Bereitstellungsprojekts ist standardmäßig für das aktuelle Verzeichnis festgelegt. Führen Sie den Befehl aus Ihrem Agent-Projektordner aus.

So bereinigen Sie Ressourcen, die ohne eine Konfigurationsdatei bereitgestellt werden:

a365 cleanup --agent-name <your-agent-name>

Säuberung liest Ressourcen-IDs aus der global generierten Konfigurationsdatei, die vom Bootstrap-Setup geschrieben wurde, sodass keine a365.config.json erforderlich ist.

Agent-Identitätsmodi

Das aiTeammate Feld steuert, wie Agentinstanzen bereitgestellt werden und welche Identität sie zur Laufzeit aufweisen. Wählen Sie den richtigen Modus basierend auf dem, was Ihr Agent tun muss.

Standardmodus (aiTeammate: false) – Voreinstellung

Verwenden Sie diesen Modus, wenn Ihr Agent als Dienst oder Back-End-Integration fungiert – Nachrichten verarbeiten, auf Ereignisse reagieren oder APIs aufrufen – ohne dass eine Benutzeridentität pro Instanz erforderlich ist. Dieser Modus erweitert die Anzahl der Agents, die Sie erstellen können: Jeder Dienst, der mit der Agent 365-Plattform kommuniziert, kann als Agent registriert werden, auch wenn er keinen Benutzer darstellt oder an benutzerorientierten Zusammenarbeitserfahrungen teilnimmt.

Dieser Modus ist der Standardmodus. Führen Sie Setup ohne Kennzeichnungen aus oder übergeben Sie --aiteammate false explizit.

# Standard setup (default)
a365 setup all

# Equivalent explicit form
a365 setup all --aiteammate false

Agents unterstützen auch die konfigurationsfreie Bereitstellung über --agent-name. Siehe Konfigurationsfreie Einrichtung mit --agent-name.

KI-Teamkollegenmodus (aiTeammate: true)

Verwenden Sie diesen Modus, wenn Ihr Agent zusammen mit menschlichen Benutzern als erstklassiger Teilnehmer fungieren muss , z. B. an Besprechungen teilnehmen, Nachrichten im Namen eines Benutzers senden oder Aufgaben in einem Workflow zugewiesen werden. Agentinstanzen, die in diesem Modus bereitgestellt werden, erhalten eine dedizierte Benutzeridentität, sodass die Plattform jede Instanz einzeln identifizieren und interagieren kann.

Das Einrichten von KI-Teamkollegen erfordert eine a365.config.json Initialisierung mit a365 config init. Geben Sie --aiteammate true ein, um diesen Modus auszuwählen.

a365 setup all --aiteammate true

Problembehandlung

Nutzen Sie diese Schritte, um Probleme mit a365.config.json und der Agent 365 CLI schnell zu diagnostizieren und zu beheben.

• Konfigurationsdatei ist nicht vorhanden
• Fehlende oder ungültige Konfigurationswerte
• Ungültiger Mandant oder ungültiges Abonnement
• Fehler bei der Überprüfung der benutzerdefinierten Client-App
• Ungültiger Agent-Benutzerprinzipalname

Konfigurationsdatei ist nicht vorhanden

Symptom: CLI-Befehle schlagen mit der Meldung "Konfiguration nicht gefunden" fehl oder Test-Path a365.config.json gibt False zurück.

Lösung: Erstelle eine neue a365.config.json Datei.

Führen Sie die Schritte zum Initialisieren der Konfiguration aus.

Fehlende oder ungültige Konfigurationswerte

Symptom: Die Konfigurationsdatei existiert, enthält aber leere Felder oder Validierungsfehler.

Lösung: Befolgen Sie die Schritte zur Überprüfung a365.config.json der Konfigurationsdaten.

Wenn ein Feld falsch ist:

• Option 1: Führe den Zauberer erneut aus, indem du den a365 config init Befehl benutzt.
• Option 2: Manuell mit korrekten Werten bearbeiten a365.config.json .

Ungültiger Mandant oder Abonnement

Symptom: Die CLI scheitert bei Authentifizierungs- oder Autorisierungsfehlern.

Solution:

Verwenden Sie diese Befehle, um die Authentifizierung mit Azure erneut zu erstellen, das angemeldete Konto zu überprüfen, zum richtigen Abonnement zu wechseln und die Agent 365 CLI-Konfiguration erneut zu initialisieren.

# Re-authenticate with Azure
az login

# Verify you're logged into the correct account
az account show

# If needed, switch to the correct subscription
az account set --subscription "<subscription-name-or-id>"

# Re-initialize configuration
a365 config init

Fehler bei der Überprüfung der benutzerdefinierten Client-App

Symptom: Der Konfigurationsassistent schlägt bei der Validierung der benutzerdefinierten Client-App-ID fehl.

Lösung: Überprüfen Sie die Registrierung Ihrer benutzerdefinierten Client-App, um sicherzustellen, dass Ihre App-Registrierung alle erforderlichen Berechtigungen und die Zustimmung des Administrators enthält.

Ungültiger Agent-Benutzerprinzipalname

Symptom: Die Überprüfung schlägt während der Konfiguration für den Benutzerprinzipalnamen des Agents fehl.

Lösung: Stellen Sie sicher, dass der UPN dem Format username@domainfolgt. Beispiel: demo.agent@contoso.onmicrosoft.com. Ein fehlendes Domänensuffix ist die häufigste Ursache.