Configura la CLI dell'Agent 365 per i cloud del governo USA

Di default, la CLI Agent 365 è destinata al cloud commerciale Microsoft. Si autentica usando https://login.microsoftonline.com, chiama Microsoft Graph a https://graph.microsoft.com, e chiama i servizi Agent 365 a https://agent365.svc.cloud.microsoft. I cloud del governo statunitense di Microsoft 365 sono Government Community Cloud (GCC), GCC High e Department of Defense (DoD). Per usare la CLI in uno di questi cloud, seleziona l'ambiente cloud e configura gli endpoint per quel cloud.

Questo articolo spiega come la CLI risolve le impostazioni cloud e come configurarle nel file a365.config.json o con variabili di ambiente.

Ambienti cloud supportati

Il nome dell'ambiente indica alla CLI quale cloud intendi usare. Impostalo esplicitamente per ogni cloud del governo USA.

Il nome dell'ambiente controlla due comportamenti:

• La CLI legge le variabili con ambito ambientale che corrispondono al nome dell'ambiente. Ad esempio, con gcc-high, la CLI legge A365_GRAPH_BASE_URL_GCC_HIGH.
• Il programma di installazione concede permessi sulla risorsa Agent 365 Observability per il cloud selezionato. Per ulteriori informazioni, vedi Permessi di osservabilità.

Il nome dell'ambiente non cambia da solo l'host dell'autorità, l'URL base di Microsoft Graph o gli endpoint del servizio Agent 365. Configura quei endpoint per il tuo cloud come descritto in Configura GCC e Configura GCC High o DoD.

Come la CLI risolve le impostazioni cloud

La CLI risolve prima il nome dell'ambiente, poi lo usa per risolvere ogni endpoint.

Nome dell'ambiente

La CLI utilizza il primo valore che trova:

1. Il campo environment in a365.config.json.
2. Variabile di ambiente A365_ENVIRONMENT.
3. Per i comandi di configurazione che vengono eseguiti senza un file a365.config.json, il nome del cloud attivo di interfaccia della riga di comando di Azure (az cloud show). Se il cloud interfaccia della riga di comando di Azure è AzureUSGovernment, setup si ferma e ti chiede di impostare A365_ENVIRONMENT su gcc, gcc-high o dod.
4. Quello predefinito, prod.

Quando la configurazione genera un a365.config.json file, registra i valori risolti environment, authorityHost, graphBaseUrl e così i comandi successivi puntano allo stesso cloud.

Il develop list-available comando non legge a365.config.json. Legge sempre l'ambiente da A365_ENVIRONMENT, quindi imposta quella variabile quando usi il comando in un cloud del governo USA.

Host di autorità e URL base di Microsoft Graph

Per ogni endpoint, la CLI utilizza il primo valore che trova:

1. La variabile d'ambiente con ambito environment (A365_AUTHORITY_HOST_<ENV> o A365_GRAPH_BASE_URL_<ENV>).
2. Il campo di corrispondenza in a365.config.json (authorityHost o graphBaseUrl).
3. Il default del commercial-cloud (https://login.microsoftonline.com o https://graph.microsoft.com).

La CLI non legge queste impostazioni da variabili senza suffisso come A365_GRAPH_BASE_URL.

Ogni valore risolto deve essere un'origine HTTPS: solo uno schema, un host e una porta opzionale. Non includere un percorso, una query string, un frammento o informazioni sull'utente. Ad esempio, la CLI accetta https://login.microsoftonline.us ma rifiuta https://login.microsoftonline.us/common. Se un valore non supera la validazione, la CLI si interrompe con un errore.

La CLI applica l'host dell'autorità risolta e l'URL base Graph in modo coerente attraverso configurazione, consenso, autenticazione, query Microsoft Entra ID, pulizia e flussi di creazione-istanze. Memorizza i token separatamente per ogni host autorità, quindi cambiare cloud non riutilizza token da un altro cloud.

Endpoint di servizio Agent 365

La CLI chiama i servizi di Agent 365 per scoprire i server Model Context Protocol (MCP), gestire i server MCP e registrare l'endpoint di messaggistica dell'agente. Configura questi endpoint di servizio solo con variabili di ambiente. Questi endpoint non hanno a365.config.json campi.

Ogni valore deve essere un URL HTTPS assoluto. Includere un percorso se l'endpoint ne ha bisogno, ma non includere una stringa di query, un frammento o informazioni sull'utente.

Configura GCC

GCC utilizza l'host dell'autorità commerciale e l'URL base di Microsoft Graph, quindi non è necessario sovrascriverli. Per maggiori informazioni, consulta distribuzioni cloud nazionali di Microsoft Graph. Imposta l'ambiente su gcc e indirizza le chiamate di servizio Agent 365 al servizio GCC.

In a365.config.json, imposta il environment campo:

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

Poi imposta le variabili di ambiente. L'impostazione A365_ENVIRONMENT copre anche i comandi che non leggono a365.config.json, come develop list-available. In Bash, esegui i seguenti comandi:

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

In Windows PowerShell, esegui i seguenti comandi:

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

Configura GCC High o DoD

GCC High e DoD utilizzano il proprio host di autorità e l'URL base Microsoft Graph:

Questi valori provengono dai seguenti articoli. Controllateli per gli endpoint correnti:

• Endpoint di autenticazione Microsoft Entra per cloud nazionali
• Implementazioni cloud nazionali di Microsoft Graph

I tenant GCC High e DoD utilizzano Azure per enti pubblici. La CLI dell'Agent 365 utilizza la interfaccia della riga di comando di Azure per alcune operazioni, come il rilevamento del tuo tenant, quindi accedi all'interfaccia della riga di comando di Azure in Azure per enti pubblici. Per le istruzioni, vedi Connetti ad Azure per enti pubblici con interfaccia della riga di comando di Azure. I servizi Azure in Azure per enti pubblici utilizzano anche nomi di dominio diversi rispetto a Azure globale. Ad esempio, se ospiti il tuo agente in Servizio app di Azure, il tuo endpoint di messaggistica utilizza un dominio Azure per enti pubblici. Per la mappatura degli endpoint, vedi Confronta Azure per enti pubblici e Azure globale.

Imposta questi valori in a365.config.json o con variabili di ambiente. Le variabili con ambito ambientale hanno la precedenza sui campi a365.config.json corrispondenti, quindi utilizzali per sovrascrivere una configurazione archiviata nel repository per macchina o per pipeline.

Configura in a365.config.json

L'esempio seguente è destinato a 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": "."
}

Configurare con le variabili di ambiente

Il seguente esempio di Bash ha come destinazione 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"

Il seguente esempio di PowerShell di Windows è rivolto a 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"

Per il DoD, imposta l'ambiente su dod, usa il DOD suffisso e usa l'URL base del Microsoft Graph del DoD.

Se i servizi Agent 365 sono disponibili nel tuo cloud, imposta anche A365_DISCOVER_ENDPOINT_<ENV> sull'endpoint di discovery per quel cloud. Altrimenti, CLI chiama il servizio commerciale Agent 365. Per ulteriori informazioni, consulta endpoint di servizio Agent 365.

Informazioni di riferimento sulla configurazione

Questa sezione elenca le a365.config.json proprietà e le variabili ambientali che controllano le impostazioni cloud.

Proprietà di a365.config.json

Variabili di ambiente

Come viene derivato il suffisso dell'ambiente

La CLI deriva il suffisso <ENV> di ogni variabile con scope di ambiente dal nome dell'ambiente. La CLI riduce il nome, sostituisce ogni carattere che non è lettera o cifra con un sottolineamento (_), e lo converte in maiuscolo. Un nome vuoto diventa PROD.

Il nome dell'ambiente e il suffisso sulla variabile devono risolversi allo stesso valore normalizzato. Ad esempio, A365_ENVIRONMENT=gcc-high coppie con A365_AUTHORITY_HOST_GCC_HIGH.

Permessi di osservabilità

Per gli agenti blueprint, a365 setup all non richiede il Agent365.Observability.OtelWrite permesso in nessun cloud. La registrazione dell'Agent 365 autorizza un'istanza di agente registrata a esportare la telemetria sulla rotta service-to-service (S2S) anche in assenza di tale autorizzazione. Per ulteriori informazioni, vedi Permessi di osservabilità.

La configurazione del team team AI e il a365 setup permissions bot comando concedono il Agent365.Observability.OtelWrite permesso sulla risorsa di osservabilità Agent 365 per il cloud selezionato. Se un agente esporta la telemetria sulla rotta delegata e ha bisogno di questo permesso, usa l'ID risorsa dell'applicazione per il tuo cloud:

Le versioni precedenti della CLI concedevano sempre il permesso sulla risorsa commerciale Observability. Se configuri un compagno di squadra IA in un cloud del Governo degli Stati Uniti con una versione precedente, imposta l'ambiente per il tuo cloud e riesegui a365 setup all in modo che la CLI conceda il permesso sulla risorsa di Observability del tuo cloud.

Verificare la configurazione

Dopo aver configurato un cloud, esegui un comando di sola lettura e conferma che la CLI utilizza gli endpoint attesi. Ad esempio:

• Eseguire il develop list-available comando. L'output mostra l'ambiente e l'URL dell'endpoint di scoperta che la CLI chiama.
• Acquisisci un token usando il develop get-token comando.

Risolvere i problemi di configurazione cloud

La tabella seguente elenca gli errori comuni di configurazione cloud e come risolverli.

Contenuti correlati

• Agente 365 CLI
• Riferimento CLI di Agent 365
• Autenticazione Microsoft Entra e cloud nazionali
• Implementazioni cloud nazionali di Microsoft Graph
• Confronta Azure per enti pubblici e Azure globale
• Connettiti ad Azure per enti pubblici con interfaccia della riga di comando di Azure
• Microsoft 365 endpoint GCC High del governo degli Stati Uniti
• Endpoint del DoD del governo degli Stati Uniti di Microsoft 365
• Descrizione del servizio Microsoft Agent 365