Einrichtung der Agent-365-Konfiguration

Der Agent 365 CLI muss Ihren Mieter, Ihr Abonnement und weitere Details kennen, um die erforderlichen Agentenressourcen 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
• Zugriff auf ein Azure-Abonnement mit Berechtigungen zum Erstellen von Ressourcen

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.

Authentifizieren mit Azure

Bevor Sie die Konfiguration initialisieren, authentifizieren Sie sich mit Azure mithilfe des Befehls az login:

az login

Wählen Sie bei entsprechender Eingabeaufforderung das geeignete Abonnement aus. Der Konfigurations-Assistent verwendet Azure CLI, um verfügbare Abonnements, Ressourcengruppen und App-Dienstpläne abzufragen. Für das reibungsloseste Entwicklungserlebnis richten Sie Ihr Mieter-Benutzerkonto mit der richtigen Rolle sowie den richtigen Berechtigungen, einem Abonnement und dem App-Service-Plan ein, bevor Sie beginnen.

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 zugehörige Ressourcennamen (Web-App, Agenten-Identität, Blueprint, Agent-Benutzer) und validiert 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

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",
  "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "resourceGroup": "your-resource-group",
  "location": "location-of-your-azure-resources",
  "environment": "prod",
  "needDeployment": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "appServicePlanName": "your-app-service-plan",
  "appServicePlanSku": "service-plan-sku",
  "webAppName": "your-web-app",
  "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 und subscriptionId sind gültige GUIDs
✅ clientAppId ist eine gültige GUID (deine benutzerdefinierte Client-App-Registrierung)
✅ resourceGroup und appServicePlanName in Ihrem Azure-Abonnement vorhanden
✅ managerEmail verwendet deine Mandanten-Domain
✅ deploymentProjectPath weist auf dein Agentencode-Verzeichnis
✅ agentUserPrincipalName folgt dem Format agentname@tenant.com
✅ environment wird festgelegt (typischerweise prod)
✅ needDeployment ist true für die initiale Einrichtung. Wenn du keine Bereitstellung brauchst, lerne, wie man einen Agent-Messaging-Endpunkt einrichtet.

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.

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 Abonnement
• Fehler bei der Überprüfung der benutzerdefinierten Client-App
• Ungültiger Agent-Benutzerprinzipalname
• Der Name der Web-App ist bereits vergeben

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 zur Authentifizierung mit Azure und 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.

Web-App-Name bereits vergeben

Symptom: Setup schlägt fehl, da der Web-App-Name bereits verwendet wird.

Solution: Web App-Namen müssen in Azure global eindeutig sein. Aktualisieren Sie webAppName in a365.config.json auf einen eindeutigen Wert, oder führen Sie a365 config init erneut aus, um einen neuen Namen zu generieren.