Konfigurieren Sie die Agent 365 CLI für US Government-Clouds

Standardmäßig zielt die Agent 365 CLI auf die Microsoft Commercial Cloud ab. Es authentifiziert sich, indem es https://login.microsoftonline.com verwendet, Microsoft Graph bei https://graph.microsoft.com aufruft und Agent 365-Dienste bei https://agent365.svc.cloud.microsoft aufruft. Die Microsoft 365 US-Regierungsclouds sind Government Community Cloud (GCC), GCC High und Department of Defense (DoD). Um die CLI in einer dieser Clouds zu verwenden, wählen Sie die Cloud-Umgebung aus und konfigurieren Sie die Endpunkte für diese Cloud.

Dieser Artikel erklärt, wie die CLI Cloud-Einstellungen ermittelt und wie man diese in Ihrer a365.config.json Datei oder mit Umgebungsvariablen konfiguriert.

Note

Cloud-bewusste Endpunkt-Auflösung ist in neueren Versionen der Agent 365 CLI verfügbar. Aktualisieren Sie auf die neueste Version, bevor Sie eine US Government Cloud konfigurieren. Für Update-Anweisungen siehe Agent 365 CLI aktualisieren.

Important

Konfigurierbare Endpunkte garantieren nicht, dass jeder Agent 365-Dienst oder jede Funktion in jeder Cloud verfügbar ist. Einige Dienste und Funktionen, die in der kommerziellen Cloud verfügbar sind, sind möglicherweise noch nicht in GCC, GCC High oder DoD verfügbar. Bestätige die Verfügbarkeit des Dienstes für deine Cloud, bevor du die Einrichtung startest. Für die Verfügbarkeit der Agent-365-Funktionen in GCC siehe die Servicebeschreibung von Microsoft Agent 365.

Unterstützte Cloudumgebungen

Der Umgebungsname sagt der CLI, welche Cloud du anvisierst. Setze es explizit für jede US Government Cloud.

Wolke environment Wert Umgebungsvariablen-Suffix (<ENV>)
Kommerziell (Standard) prod PROD
GCC gcc GCC
GCC High gcc-high GCC_HIGH
Verteidigungsministerium dod DOD

Der Name der Umgebung steuert zwei Verhaltensweisen:

  • Die CLI liest die umgebungsbezogenen Variablen, die mit dem Umgebungsnamen übereinstimmen. Zum Beispiel liest die CLI gcc-high mit A365_GRAPH_BASE_URL_GCC_HIGH.
  • Die Einrichtung gewährt Berechtigungen für die Agent 365 Observability-Ressource für die ausgewählte Cloud. Weitere Informationen finden Sie unter Observability-Berechtigungen.

Der Umgebungsname ändert weder den Autoritätshost, die Microsoft Graph-Basis-URL noch die Endpunkte des Agent-365-Dienstes von selbst. Konfigurieren Sie diese Endpunkte für Ihre Cloud, wie in Configure GCC und Configure GCC High oder DoD beschrieben.

Important

Verwende nicht den Azure CLI-Cloud-Namen AzureUSGovernment als Umgebung. Dieser Name unterscheidet nicht zwischen GCC, GCC High und DoD, daher meldet die CLI einen Konfigurationsfehler, wenn cloud-spezifische Einstellungen benötigt werden. Verwenden Sie gcc, gcc-high, oder dod stattdessen.

Wie die CLI Cloud-Einstellungen ermittelt

Die CLI löst zuerst den Umgebungsnamen auf und verwendet ihn dann, um jeden Endpunkt zu lösen.

Umgebungsname

Die CLI verwendet den ersten Wert, den sie findet:

  1. Das environment Feld in a365.config.json.
  2. Die A365_ENVIRONMENT Umgebungsvariable.
  3. Für Setup-Befehle, die ohne Datei a365.config.json ausgeführt werden, ist der Name der aktiven Azure CLI-Cloud (az cloud show). Wenn die Azure CLI-Cloud AzureUSGovernment ist, stoppt das Setup und fordert Sie auf, gcc-high auf gcc, dod oder A365_ENVIRONMENT festzulegen.
  4. Der Standardwert, prod.

Wenn die Einrichtung eine a365.config.json Datei generiert, zeichnet sie die aufgelösten environment, authorityHost, und graphBaseUrl Werte auf, sodass spätere Befehle auf dieselbe Cloud abzielen.

Der develop list-availableBefehl liest a365.config.json nicht. Es liest immer die Umgebung aus A365_ENVIRONMENT, also setze diese Variable, wenn du den Befehl in einer US-Regierungscloud verwendest.

Autorisierungsstellenhost und Microsoft Graph-Basis-URL

Für jeden Endpunkt verwendet die CLI den ersten gefundenen Wert:

  1. Die umgebungsbezogene Umgebungsvariable (A365_AUTHORITY_HOST_<ENV> oder A365_GRAPH_BASE_URL_<ENV>).
  2. Das Matching-Feld in a365.config.json (authorityHost oder graphBaseUrl).
  3. Die kommerzielle Cloud-Voreinstellung (https://login.microsoftonline.com oder https://graph.microsoft.com).

Die CLI liest diese Einstellungen nicht aus unsuffixierten Variablen wie A365_GRAPH_BASE_URL.

Jeder aufgelöste Wert muss ein HTTPS-Ursprung sein: nur ein Schema, ein Host und ein optionaler Port. Fügen Sie keinen Pfad, keine Abfragezeichenkette, kein Fragment oder keine Benutzerinformationen hinzu. Zum Beispiel akzeptiert die CLI https://login.microsoftonline.us, lehnt https://login.microsoftonline.us/common aber ab. Wenn ein Wert die Validierung nicht besteht, stoppt die CLI mit einem Fehler.

Die CLI wendet den gelösten Autoritätshost und die Graph-Basis-URL konsistent über Setup-, Consent-, Authentication-, Microsoft Entra ID-Abfrage-, Bereinigungs- und Instanzerstellungsflows an. Es speichert Token separat für jeden Autoritätshost, sodass beim Wechsel zwischen Clouds keine Token aus einer anderen Cloud wiederverwendet werden.

Important

Kombinieren Sie den Authority-Host und die Graph-Basis-URL für dieselbe Cloud. Wenn du das eine überschreibst, überschreibe das andere, sodass Authentifizierung und Graph-Dataplane-Calls auf dieselbe Umgebung abzielen.

Agent 365 Service-Endpunkte

Die CLI ruft Agent 365-Dienste auf, um Model Context Protocol (MCP)-Server zu entdecken, MCP-Server zu verwalten und den Messaging-Endpunkt des Agenten zu registrieren. Konfigurieren Sie diese Service-Endpunkte ausschließlich mit Umgebungsvariablen. Diese Endpunkte haben a365.config.json keine Felder.

Variable Description
A365_DISCOVER_ENDPOINT_<ENV> Die vollständige URL des Agent 365 Tools Discovery-Endpunkts. Die CLI ruft diese URL auf, um MCP-Server zu entdecken. Es verwendet auch den Ursprung der URL für verwandte Agent-365-Serviceanrufe, einschließlich MCP-Serververwaltung und Registrierung von Messaging-Endpunkten. Der Standardwert ist https://agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers.
A365_CREATE_ENDPOINT_<ENV> Die vollständige URL, die die CLI aufruft, um den Messaging-Endpunkt des Agenten zu registrieren. Dieser Wert hat Vorrang vor der Quelle von A365_DISCOVER_ENDPOINT_<ENV>.
A365_DELETE_ENDPOINT_<ENV> Die vollständige URL, die die CLI aufruft, um die Registrierung des Messaging-Endpunkts des Agenten zu entfernen. Dieser Wert hat Vorrang vor der Quelle von A365_DISCOVER_ENDPOINT_<ENV>.

Jeder Wert muss eine absolute HTTPS-URL sein. Fügen Sie einen Pfad hinzu, wenn der Endpunkt einen benötigt, aber keine Abfragezeichenkette, kein Fragment oder keine Benutzerinformationen.

Important

Allein die Einstellung des Umgebungsnamens führt nicht dazu, dass Agent-365-Serviceanrufe nicht vom kommerziellen Dienst weg umgeleitet werden. Wenn du A365_DISCOVER_ENDPOINT_<ENV> nicht festlegst, ruft die CLI den kommerziellen Agent 365-Dienst auf, selbst in einer US-Regierungscloud.

GCC konfigurieren

GCC verwendet den kommerziellen Autoritätshost und die Microsoft Graph-Basis-URL, sodass du sie nicht überschreiben musst. Weitere Informationen finden Sie unter Microsoft Graph National Cloud Deployments. Setze die Umgebung auf gcc und verweise Agent 365 Service Calls auf den GCC-Service.

In a365.config.json, setze das environment Feld:

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "gcc",
  "messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
  "deploymentProjectPath": "."
}

Dann setze die Umgebungsvariablen. Die Einstellung A365_ENVIRONMENT umfasst auch Befehle, die a365.config.json nicht lesen, wie zum Beispiel develop list-available. In Bash führe folgende Befehle aus:

export A365_ENVIRONMENT="gcc"
export A365_DISCOVER_ENDPOINT_GCC="https://gcc.agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers"

Führen Sie unter Windows PowerShell folgende Befehle aus:

$env:A365_ENVIRONMENT = "gcc"
$env:A365_DISCOVER_ENDPOINT_GCC = "https://gcc.agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers"

GCC High oder DoD konfigurieren

GCC High und DoD verwenden ihren eigenen Autoritätshost und eine Microsoft Graph-basierte URL:

Wolke environment Wert Autorisierungsserver-Host (authorityHost) Microsoft Graph Basis-URL (graphBaseUrl)
GCC High gcc-high https://login.microsoftonline.us https://graph.microsoft.us
Verteidigungsministerium dod https://login.microsoftonline.us https://dod-graph.microsoft.us

Diese Werte stammen aus den folgenden Artikeln. Überprüfen Sie sie auf die aktuellen Endpunkte:

GCC High- und DoD-Tenants verwenden Azure Government. Die Agent 365 CLI verwendet die Azure CLI für einige Operationen, wie zum Beispiel die Erkennung Ihres Tenants, daher melden Sie sich in der Azure CLI in Azure Government an. Für Anleitungen siehe Connect to Azure Government with Azure CLI. Azure-Dienste in Azure Government verwenden außerdem andere Domainnamen als globales Azure. Wenn du zum Beispiel deinen Agenten im Azure App Service hostest, verwendet dein Messaging-Endpunkt eine Azure Government-Domain. Für die Endpunkt-Zuordnung siehe Vergleichen Sie Azure Government und globales Azure.

Setze diese Werte in a365.config.json oder mit Umweltvariablen. Umgebungsbezogene Variablen haben Vorrang vor den entsprechenden a365.config.json Feldern, daher verwenden Sie sie, um eine eingecheckte Konfiguration pro Maschine oder Pipeline zu überschreiben.

In a365.config.json konfigurieren

Das folgende Beispiel zielt auf GCC High ab:

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "gcc-high",

  "authorityHost": "https://login.microsoftonline.us",
  "graphBaseUrl": "https://graph.microsoft.us",

  "messagingEndpoint": "https://your-app.azurewebsites.us/api/messages",
  "deploymentProjectPath": "."
}

Konfigurieren mit Umgebungsvariablen

Das folgende Bash-Beispiel zielt auf GCC High ab:

export A365_ENVIRONMENT="gcc-high"
export A365_AUTHORITY_HOST_GCC_HIGH="https://login.microsoftonline.us"
export A365_GRAPH_BASE_URL_GCC_HIGH="https://graph.microsoft.us"

Das folgende Windows PowerShell-Beispiel zielt auf GCC High ab:

$env:A365_ENVIRONMENT = "gcc-high"
$env:A365_AUTHORITY_HOST_GCC_HIGH = "https://login.microsoftonline.us"
$env:A365_GRAPH_BASE_URL_GCC_HIGH = "https://graph.microsoft.us"

Für DoD setzen Sie die Umgebung auf dod, verwenden Sie das DOD Suffix und verwenden Sie die DoD Microsoft Graph Basis-URL.

Wenn Agent-365-Dienste in Ihrer Cloud verfügbar sind, setzen Sie A365_DISCOVER_ENDPOINT_<ENV> auch auf den Discovery-Endpunkt für diese Cloud. Andernfalls ruft die CLI den kommerziellen Agent 365-Service auf. Weitere Informationen finden Sie unter Agent 365 Service Endpoints.

Konfigurationsreferenz

Dieser Abschnitt listet die a365.config.json Eigenschaften und Umgebungsvariablen auf, die Cloud-Einstellungen steuern.

Eigenschaften von a365.config.json

Property Description Erforderlich Default
environment Der Name der Cloudumgebung. Verwenden Sie prod, gcc, gcc-high, oder dod. Dieser Wert bestimmt, welche umgebungsbezogenen Variablen die CLI liest und welche Observability-Ressourceneinrichtung verwendet wird. No prod
authorityHost Der OAuth-Autorisierungshost für die ausgewählte Cloud. Der Wert muss eine HTTPS-Quelle sein. No https://login.microsoftonline.com
graphBaseUrl Die Microsoft Graph-Basis-URL für die ausgewählte Cloud. Der Wert muss eine HTTPS-Quelle sein. No https://graph.microsoft.com

Umgebungsvariablen

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 OAuth-Autoritätshost. 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> Agent 365 Tools Erkennungsendpunkt 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.

Wie das Umgebungsuffix abgeleitet wird

Die CLI leitet das <ENV> Suffix jeder umgebungsbezogenen Variablen aus deinem Umgebungsname ab. Die CLI kürzt den Namen, ersetzt jedes Zeichen, das kein Buchstabe oder eine Ziffer ist, durch einen Unterstrich (_) und wandelt es in Großbuchstaben um. Ein leerer Name wird zu PROD.

Umgebungsname Normalisiertes Suffix Beispielvariable
gcc GCC A365_DISCOVER_ENDPOINT_GCC
gcc-high GCC_HIGH A365_GRAPH_BASE_URL_GCC_HIGH
dod DOD A365_AUTHORITY_HOST_DOD

Der Umgebungsname und das Suffix der Variablen müssen auf denselben normalisierten Wert aufgelöst werden. Zum Beispiel wird A365_ENVIRONMENT=gcc-high mit A365_AUTHORITY_HOST_GCC_HIGH gekoppelt.

Berechtigungen für Observability

Während der Einrichtung gewährt die CLI dem Agent-Blueprint die Agent365.Observability.OtelWrite Berechtigung für die Agent 365 Observability-Ressource für die ausgewählte Cloud:

Wolke Observability-Ressourcen-Anwendungs-ID
Kommerziell 9b975845-388f-4429-889e-eab1ef63949c
GCC 2c672ad5-b104-44ed-8069-bb68dd138546
GCC High 009c6bd0-82e4-4466-95b3-4c996521f3d7
Verteidigungsministerium a9e04047-c6a7-430b-a7ae-faf8f8eed1b7

Frühere Versionen der CLI gewährten immer die Berechtigung für die kommerzielle Observability-Ressource. Wenn Sie einen Agenten in einer US Government Cloud mit einer früheren Version einrichten, setzen Sie die Umgebung für Ihre Cloud und führen Sie a365 setup all erneut aus, sodass die CLI die Berechtigung für die Observability-Ressource Ihrer Cloud gewährt.

Überprüfen Sie Ihre Konfiguration

Nachdem du eine Cloud konfiguriert hast, führe einen schreibgeschützten Befehl aus und prüfe, dass die CLI die erwarteten Endpunkte verwendet. Beispiel:

Cloud-Konfiguration beheben

Die folgende Tabelle listet häufige Cloud-Konfigurationsfehler und deren Behebung auf.

Symptom Ursache Resolution
Authority host must be an HTTPS origin without a path, query, fragment, or user info. (oder denselben Fehler für die Graph-Basis-URL) Der Authority-Host oder die Graph-Basis-URL enthält einen Pfad, eine Abfragezeichenfolge oder ein Fragment. Verwenden Sie einen reinen HTTPS-Ursprung. Verwenden Sie https://login.microsoftonline.us z. B. anstelle von https://login.microsoftonline.us/common/oauth2/v2.0/authorize.
Ein Fehler besagt, dass AzureUSGovernment oder die Azure CLI-Cloud nicht zwischen GCC Moderate (GCC), GCC High und DoD unterscheidet. Die Umgebung ist AzureUSGovernment, oder das Setup hat diese Cloud in der Azure CLI erkannt. Setze die Umgebung auf gcc, gcc-high, oder dod.
Die CLI ruft den kommerziellen Agent 365-Dienst in einer US-Regierungscloud auf. A365_DISCOVER_ENDPOINT_<ENV> ist nicht festgelegt, oder sein Suffix passt nicht zum Namen der Umgebung. Setzen Sie A365_DISCOVER_ENDPOINT_<ENV> mit dem Suffix für Ihre Umgebung.
Das Setup gewährt Berechtigungen für die kommerzielle Observability-Ressource. Die Umgebung ist nicht gesetzt, daher verwendet die CLI prod. Stellen Sie die Umgebung für Ihre Cloud ein und führen Sie die Einrichtung erneut aus.
PowerShell fallback is available only for commercial Graph and authority endpoints. Die Microsoft Graph-Anmeldung ist fehlgeschlagen, und die CLI kann nicht auf PowerShell Connect-MgGraph zurückgreifen, wenn man benutzerdefinierte Endpunkte verwendet. Beheben Sie den Anmeldefehler. Bestätigen Sie zum Beispiel, dass Sie Ihre Client-App in Ihrer Cloud registriert haben und sich mit einem Konto im Tenant Ihrer Cloud anmelden.

Verwandte Inhalte

  • Zuletzt aktualisiert um