Configurez Agent 365 CLI pour les clouds du gouvernement américain

Par défaut, l’interface en ligne de commande Agent 365 cible le cloud commercial Microsoft. Il s’authentifie en utilisant https://login.microsoftonline.com, appelle Microsoft Graph à https://graph.microsoft.com, et appelle les services Agent 365 à https://agent365.svc.cloud.microsoft. Les clouds Microsoft 365 du gouvernement américain sont Government Community Cloud (GCC), GCC High et Department of Defense (DoD). Pour utiliser la CLI dans l’un de ces clouds, sélectionnez l’environnement cloud et configurez les points de terminaison pour ce cloud.

Cet article explique comment la CLI résout les paramètres cloud et comment les configurer dans votre fichier a365.config.json ou avec des variables d’environnement.

Note

La résolution des points de terminaison compatible cloud est disponible dans les versions récentes de l’Agent 365 CLI. Mettez à jour vers la dernière version avant de configurer un cloud du gouvernement américain. Pour les instructions de mise à jour, voir Mettre à jour la CLI Agent 365.

Important

Les points de terminaison configurables ne garantissent pas que chaque service ou fonctionnalité Agent 365 soit disponible dans chaque cloud. Certains services et fonctionnalités disponibles dans le cloud commercial ne le sont peut-être pas encore dans GCC, GCC High ou DoD. Confirmez la disponibilité des services pour votre cloud avant de lancer la configuration. Pour la disponibilité des fonctionnalités Agent 365 dans le GCC, voir la description du service Microsoft Agent 365.

Environnements cloud pris en charge

Le nom de l’environnement indique à la CLI quel cloud vous ciblez. Définissez-le explicitement pour chaque cloud du gouvernement américain.

Nuage informatique environment valeur Suffixe de variable d’environnement (<ENV>)
Commercial (par défaut) prod PROD
GCC gcc GCC
GCC High gcc-high GCC_HIGH
DoD dod DOD

Le nom de l’environnement contrôle deux comportements :

  • La CLI lit les variables à portée d’environnement qui correspondent au nom de l’environnement. Par exemple, avec gcc-high, le CLI lit A365_GRAPH_BASE_URL_GCC_HIGH.
  • Le programme d’installation accorde des permissions sur la ressource Agent 365 Observability pour le cloud sélectionné. Pour plus d’informations, voir Autorisations d’observabilité.

Le nom de l'environnement ne change pas l'hôte d'autorité, l'URL de base de Microsoft Graph, ni les points de terminaison du service Agent 365 en soi. Configurez ces points de terminaison pour votre cloud comme décrit dans Configurer GCC et Configurer GCC High ou DoD.

Important

N'utilisez pas le nom de cloud Azure CLI AzureUSGovernment comme environnement. Ce nom ne fait pas la distinction entre GCC, GCC High et DoD, donc la CLI signale une erreur de configuration lorsqu’elle a besoin de paramètres spécifiques au cloud. Utilisez gcc, gcc-high, ou dod à la place.

Comment la CLI résout les paramètres du cloud

La CLI résout d’abord le nom de l’environnement, puis l’utilise pour résoudre chaque point de terminaison.

Nom de l’environnement

La CLI utilise la première valeur qu’elle trouve :

  1. Le champ environment dans a365.config.json.
  2. Variable d’environnement A365_ENVIRONMENT.
  3. Pour les commandes de configuration qui s’exécutent sans fichier a365.config.json, le nom du cloud actif Azure CLI (az cloud show). Si le cloud Azure CLI est AzureUSGovernment, la configuration s’arrête et vous demande de définir A365_ENVIRONMENT sur gcc, gcc-high ou dod.
  4. Par défaut, prod.

Lorsque la configuration génère un fichier a365.config.json, elle enregistre les valeurs résolues environment, authorityHost et graphBaseUrl afin que les commandes ultérieures ciblent le même cloud.

La develop list-available commande ne lit a365.config.jsonpas . Il lit toujours l’environnement depuis A365_ENVIRONMENT, donc définissez cette variable lorsque vous utilisez la commande dans un cloud du gouvernement américain.

Hôte d’autorité et URL de base Microsoft Graph

Pour chaque point de terminaison, la CLI utilise la première valeur qu’elle trouve :

  1. La variable d’environnement propre à l’environnement (A365_AUTHORITY_HOST_<ENV> ou A365_GRAPH_BASE_URL_<ENV>).
  2. Le champ d’appariement dans a365.config.json (authorityHost ou graphBaseUrl).
  3. La valeur par défaut du cloud commercial (https://login.microsoftonline.com ou https://graph.microsoft.com).

La CLI ne lit pas ces paramètres à partir de variables sans suffixe telles que A365_GRAPH_BASE_URL.

Chaque valeur résolue doit être une origine HTTPS : un schéma, un hôte et un port optionnel uniquement. N’incluez pas de chemin, de chaîne de requête, de fragment ou d’informations utilisateur. Par exemple, le CLI accepte https://login.microsoftonline.us mais rejette https://login.microsoftonline.us/common. Si une valeur ne passe pas la validation, la CLI s’arrête avec une erreur.

La CLI applique l’hôte d’autorité résolu et l’URL de base Graph de manière cohérente à travers les flux de configuration, consentement, authentification, requête Microsoft Entra ID, nettoyage et création d’instance. Il met en cache les jetons séparément pour chaque hôte d’autorité, donc changer de cloud ne réutilise pas les jetons d’un autre cloud.

Important

Associez l’hôte d’autorité et l’URL de base Graph pour le même cloud. Si vous en redéfinissez un, écrasez l’autre pour que l’authentification et les appels Graph data-plane ciblent le même environnement.

Points de terminaison de service Agent 365

La CLI appelle les services Agent 365 pour découvrir les serveurs du protocole de contexte modèle (MCP), gérer les serveurs MCP et enregistrer le point de messagerie de l’agent. Configurez ces points de terminaison de service uniquement avec des variables d’environnement. Ces points de terminaison n’ont pas de champs a365.config.json.

Variable Description
A365_DISCOVER_ENDPOINT_<ENV> L’URL complète du point de terminaison de découverte d’Agent 365 Tools. Le CLI appelle cette URL pour découvrir les serveurs MCP. Il utilise également l’origine de l’URL pour les appels de service Agent 365 associés, y compris la gestion des serveurs MCP et l’enregistrement des points de terminaison de messagerie. La valeur par défaut est https://agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers.
A365_CREATE_ENDPOINT_<ENV> L’URL complète que la CLI appelle pour enregistrer le point de terminaison de messagerie de l’agent. Cette valeur prévaut sur l’origine de A365_DISCOVER_ENDPOINT_<ENV>.
A365_DELETE_ENDPOINT_<ENV> L’URL complète que la CLI appelle pour supprimer l’enregistrement du point de terminaison de messagerie de l’agent. Cette valeur a la priorité sur l’origine de A365_DISCOVER_ENDPOINT_<ENV>.

Chaque valeur doit être une URL HTTPS absolue. Incluez un chemin si le point d’accès en a besoin, mais n’incluez pas de chaîne de requête, de fragment ou d’informations utilisateur.

Important

Définir seul le nom de l’environnement ne détourne pas les appels de service Agent 365 du service public/commercial. Si vous ne configurez A365_DISCOVER_ENDPOINT_<ENV>pas, la CLI appelle le service commercial Agent 365, même dans un cloud du gouvernement américain.

Configurer GCC

GCC utilise l'hôte de l'autorité commerciale et l'URL de base de Microsoft Graph, donc vous n'avez pas besoin de les remplacer. Pour plus d’informations, consultez Déploiements cloud nationaux de Microsoft Graph. Réglez l’environnement sur gcc et orientez les appels de service Agent 365 vers le service GCC.

Dans a365.config.json, définissez le champ environment :

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

Ensuite, définissez les variables d’environnement. Le paramètre A365_ENVIRONMENT couvre aussi les commandes qui ne lisent pas a365.config.json, comme develop list-available. Dans Bash, exécutez les commandes suivantes :

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

Dans Windows PowerShell, exécutez les commandes suivantes :

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

Configurez GCC High ou DoD

GCC High et DoD utilisent leur propre hôte d’autorité et l’URL de base Microsoft Graph :

Nuage informatique environment valeur Hôte d’autorité (authorityHost) URL de base Microsoft Graph (graphBaseUrl)
GCC High gcc-high https://login.microsoftonline.us https://graph.microsoft.us
DoD dod https://login.microsoftonline.us https://dod-graph.microsoft.us

Ces valeurs proviennent des articles suivants. Vérifiez-les pour les points de terminaison actuels :

Les locataires de GCC High et DoD utilisent Azure Government. L’Agent 365 CLI utilise la CLI Azure CLI pour certaines opérations, comme la détection de votre locataire Azure, donc connectez-vous à la CLI Azure CLI dans Azure Government. Pour les instructions, voir Se connecter à Azure Government avec Azure CLI. Les services Azure dans Azure Government utilisent également des noms de domaine différents de l’Azure global. Par exemple, si vous hébergez votre agent dans Azure App Service, votre point de terminaison de messagerie utilise un domaine Azure Government. Pour le mappage des points de terminaison, voir Comparer Azure Government et Azure global.

Placez ces valeurs dans a365.config.json ou avec des variables d’environnement. Les variables à portée d’environnement ont la priorité sur les champs correspondants a365.config.json, donc utilisez-les pour remplacer une configuration archivée dans le dépôt par machine ou pipeline.

Configurez-le dans a365.config.json

L’exemple suivant cible GCC High :

{
  "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": "."
}

Configurer avec des variables d’environnement

L’exemple Bash suivant s’applique à GCC High :

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"

L’exemple suivant de PowerShell Windows cible GCC High :

$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"

Pour le DoD, réglez l’environnement sur dod, utilisez le DOD suffixe, et utilisez l’URL de base Microsoft Graph du DoD.

Si les services Agent 365 sont disponibles dans votre cloud, définissez également A365_DISCOVER_ENDPOINT_<ENV> sur le point de terminaison de découverte pour ce cloud. Sinon, le CLI appelle le service commercial Agent 365. Pour plus d’informations, voir les points de terminaison de service Agent 365.

Référence de configuration

Cette section liste les a365.config.json propriétés et variables d’environnement qui contrôlent les paramètres du cloud.

propriétés de a365.config.json

Propriété Description Obligatoire Default
environment Nom de l’environnement cloud. Utiliser prod, gcc, gcc-high, ou dod. Cette valeur détermine quelles variables à portée d’environnement le CLI lit et quelle configuration de ressource Observability est utilisée. No prod
authorityHost L’hôte d’autorité OAuth pour le cloud sélectionné. La valeur doit être une origine HTTPS. No https://login.microsoftonline.com
graphBaseUrl L’URL de base Microsoft Graph pour le cloud sélectionné. La valeur doit être une origine de type HTTPS. No https://graph.microsoft.com

Variables d’environnement

Variable Description
A365_ENVIRONMENT Nom de l’environnement cloud. La CLI utilise cette valeur lorsque a365.config.json ne définit pas environment, et pour les commandes qui ne lisent pas a365.config.json. La valeur par défaut est prod.
A365_AUTHORITY_HOST_<ENV> L’hôte d’autorité OAuth. Cette valeur prévaut sur authorityHost dans a365.config.json.
A365_GRAPH_BASE_URL_<ENV> L’URL de base de Microsoft Graph. Cette valeur prévaut sur graphBaseUrl dans a365.config.json.
A365_DISCOVER_ENDPOINT_<ENV> Le point de terminaison de découverte d’Agent 365 Tools. Le CLI utilise également son origine pour les appels de service Agent 365 apparentés.
A365_CREATE_ENDPOINT_<ENV> L’URL d’enregistrement du point de terminaison de messagerie.
A365_DELETE_ENDPOINT_<ENV> L’URL de suppression du point de terminaison de messagerie.
A365_MCP_APP_ID_<ENV> L’ID d’application de ressource Agent 365 Tools que la CLI utilise pour acquérir des jetons destinés aux serveurs outils. La plupart des développeurs n’ont pas besoin de définir cette variable.

Comment le suffixe de l’environnement est dérivé

L’interface CLI génère le suffixe <ENV> de chaque variable à portée d’environnement à partir du nom de votre environnement. La CLI coupe le nom, remplace chaque caractère qui n’est pas une lettre ou un chiffre par un soulignement (_), puis le convertit en majuscules. Un nom vide devient PROD.

Nom de l’environnement Suffixe normalisé Exemple de variable
gcc GCC A365_DISCOVER_ENDPOINT_GCC
gcc-high GCC_HIGH A365_GRAPH_BASE_URL_GCC_HIGH
dod DOD A365_AUTHORITY_HOST_DOD

Le nom de l’environnement et le suffixe sur la variable doivent se résoudre à la même valeur normalisée. Par exemple, A365_ENVIRONMENT=gcc-high est associé à A365_AUTHORITY_HOST_GCC_HIGH.

Autorisations d’observabilité

Lors de la configuration, la CLI accorde au blueprint de l’agent l’autorisation Agent365.Observability.OtelWrite sur la ressource d’observabilité Agent 365 pour le cloud sélectionné :

Nuage informatique ID d’application de ressource d’observabilité
Commercial 9b975845-388f-4429-889e-eab1ef63949c
GCC 2c672ad5-b104-44ed-8069-bb68dd138546
GCC High 009c6bd0-82e4-4466-95b3-4c996521f3d7
DoD a9e04047-c6a7-430b-a7ae-faf8f8eed1b7

Les versions antérieures de la CLI accordaient toujours la permission sur la ressource commerciale d’observabilité. Si vous configurez un agent dans un cloud du gouvernement américain avec une version antérieure, configurez l’environnement de votre cloud et relancez a365 setup all pour que la CLI accorde l’autorisation sur la ressource d’Observabilité de votre cloud.

Vérifier votre configuration

Après avoir configuré un cloud, lancez une commande en lecture seule et confirmez que la CLI utilise les points de terminaison attendus. Par exemple:

Résoudre les problèmes de configuration du cloud

Le tableau suivant liste les erreurs courantes de configuration cloud et comment les résoudre.

Symptôme Cause Résolution
Authority host must be an HTTPS origin without a path, query, fragment, or user info. (ou la même erreur pour l’URL de base du Graph) L’autorité hôte ou URL de base Graph inclut un chemin, une chaîne de requête ou un fragment. Utilisez une origine HTTPS simple. Par exemple, utilisez https://login.microsoftonline.us plutôt que https://login.microsoftonline.us/common/oauth2/v2.0/authorize.
Une erreur indique que AzureUSGovernment ou que le cloud de l’interface de ligne de commande Azure ne distingue pas GCC Moderate (GCC), GCC High et DoD. L’environnement est AzureUSGovernment, ou la configuration a détecté ce cloud via Azure CLI. Réglez l’environnement sur gcc, gcc-high, ou dod.
Le CLI appelle le service commercial Agent 365 dans un cloud du gouvernement américain. A365_DISCOVER_ENDPOINT_<ENV> n’est pas défini, ou son suffixe ne correspond pas au nom de l’environnement. Réglez A365_DISCOVER_ENDPOINT_<ENV> avec le suffixe de votre environnement.
La configuration accorde des autorisations sur la ressource commerciale Observability. L’environnement n’est pas défini, donc la CLI utilise prod. Configurez l’environnement pour votre cloud et relancez l’installation.
PowerShell fallback is available only for commercial Graph and authority endpoints. La connexion à Microsoft Graph a échoué, et le CLI ne peut pas se rabattre sur PowerShell Connect-MgGraph lorsque vous utilisez des points de terminaison personnalisés. Résolvez l’échec de l’ouverture de session. Par exemple, confirmez que vous avez enregistré votre application client dans votre cloud et que vous vous connectez avec un compte dans le tenant de votre cloud.

Contenu connexe

  • Dernière mise à jour :