Configura l'interfaccia della riga di comando di Agent 365 per i cloud US Government

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.

Note

La risoluzione endpoint cloud-aware è disponibile nelle versioni più recenti della CLI di Agent 365. Aggiorna all'ultima versione prima di configurare un cloud del Governo degli Stati Uniti. Per le istruzioni di aggiornamento, vedi Aggiornare l'interfaccia della riga di comando di Agent 365.

Important

Gli endpoint configurabili non garantiscono che ogni servizio o funzionalità di Agent 365 sia disponibile in ogni cloud. Alcuni servizi e funzionalità disponibili nel cloud commerciale potrebbero non essere ancora disponibili in GCC, GCC High o DoD. Verifica la disponibilità del servizio per il tuo cloud prima di avviare la configurazione. Per la disponibilità delle funzionalità di Agent 365 in GCC, consulta la descrizione del servizio Microsoft Agent 365.

Ambienti cloud supportati

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

Cloud environment Valore Suffisso variabile ambientale (<ENV>)
Commerciale (impostazione predefinita) prod PROD
GCC gcc GCC
GCC High gcc-high GCC_HIGH
Dipartimento della Difesa (DoD) dod DOD

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.

Important

Non usare il nome AzureUSGovernment cloud di interfaccia della riga di comando di Azure come ambiente. Quel nome non distingue tra GCC, GCC High e DoD, quindi la CLI segnala un errore di configurazione quando serve impostazioni specifiche per il cloud. Usa gcc, gcc-high, oppure dod invece.

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. L'impostazione predefinita, 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.

Important

Abbina l'host dell'autorità e l'URL base di Graph per lo stesso cloud. Se sovrascrivi uno, sovrascrivi l'altro in modo che le chiamate di autenticazione e Graph data-plane puntino allo stesso ambiente.

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 campi a365.config.json.

Variable Description
A365_DISCOVER_ENDPOINT_<ENV> L'URL completo dell'endpoint di scoperta di Agent 365 Tools. La CLI chiama questo URL per scoprire i server MCP. Utilizza inoltre l'origine dell'URL per le chiamate di servizio Agent 365 correlate, inclusa la gestione dei server MCP e la registrazione degli endpoint di messaggistica. Il valore predefinito è https://agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers.
A365_CREATE_ENDPOINT_<ENV> L'URL completo che la CLI chiama per registrare l'endpoint di messaggistica dell'agente. Questo valore ha la precedenza sull'origine di A365_DISCOVER_ENDPOINT_<ENV>.
A365_DELETE_ENDPOINT_<ENV> L'URL completo che la CLI chiama per rimuovere la registrazione dell'endpoint messaggistica dell'agente. Questo valore ha la precedenza sull'origine di A365_DISCOVER_ENDPOINT_<ENV>.

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

Important

Impostare solo il nome dell'ambiente non reindirizza le chiamate al servizio Agent 365 lontano dal servizio commerciale. Se non imposti A365_DISCOVER_ENDPOINT_<ENV>, la CLI chiama il servizio commerciale Agent 365, anche in un cloud del governo USA.

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:

Cloud environment Valore Host dell'autorità (authorityHost) URL base Microsoft Graph (graphBaseUrl)
GCC High gcc-high https://login.microsoftonline.us https://graph.microsoft.us
Dipartimento della Difesa (DoD) dod https://login.microsoftonline.us https://dod-graph.microsoft.us

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

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 corrispondenti a365.config.json, quindi utilizzali per sovrascrivere una configurazione sottoposta a check-in 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, l'interfaccia della riga di comando chiama il servizio 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

Proprietà Description Obbligatorio Default
environment Nome dell'ambiente cloud. Usa prod, gcc, gcc-high, o dod. Questo valore determina quali variabili con ambito ambientale l'interfaccia della riga di comando legge e quale configurazione della risorsa Osservabilità utilizza. No prod
authorityHost L'host di autorità OAuth per il cloud selezionato. Il valore deve essere un'origine di tipo HTTPS. No https://login.microsoftonline.com
graphBaseUrl L'URL base di Microsoft Graph per il cloud selezionato. Il valore deve essere un'origine di tipo HTTPS. No https://graph.microsoft.com

Variabili di ambiente

Variable Description
A365_ENVIRONMENT Nome dell'ambiente cloud. La CLI usa questo valore quando a365.config.json non imposta environment, e per i comandi che non leggono a365.config.json. Il valore predefinito è prod.
A365_AUTHORITY_HOST_<ENV> L'host di autorità OAuth. Questo valore ha la precedenza su authorityHost in a365.config.json.
A365_GRAPH_BASE_URL_<ENV> L'URL base di Microsoft Graph. Questo valore ha la precedenza su graphBaseUrl in a365.config.json.
A365_DISCOVER_ENDPOINT_<ENV> L'endpoint di scoperta di Agent 365 Tools. La CLI utilizza anche la sua origine per chiamate di servizio Agent 365 correlate.
A365_CREATE_ENDPOINT_<ENV> L'URL di registrazione dell'endpoint di messaggistica.
A365_DELETE_ENDPOINT_<ENV> L'URL di rimozione dell'endpoint di messaggistica.
A365_MCP_APP_ID_<ENV> L'ID della risorsa dell'applicazione Agent 365 Tools che la CLI utilizza per acquisire token per i server degli strumenti. La maggior parte degli sviluppatori non ha bisogno di impostare questa variabile.

Come viene derivato il suffisso dell'ambiente

L'interfaccia della riga di comando ricava il suffisso <ENV> su ogni variabile con ambito di ambiente dal nome dell'ambiente. L'Interfaccia della riga di comando rimuove gli spazi iniziali e finali dal nome, sostituisce ogni carattere che non è una lettera o una cifra con un sottolineato (_) e lo converte in maiuscolo. Un nome vuoto diventa PROD.

Nome dell'ambiente Suffisso normalizzato Variabile di esempio
gcc GCC A365_DISCOVER_ENDPOINT_GCC
gcc-high GCC_HIGH A365_GRAPH_BASE_URL_GCC_HIGH
dod DOD A365_AUTHORITY_HOST_DOD

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.

Autorizzazioni di osservabilità

Durante l'installazione, la CLI concede al blueprint dell'agente il Agent365.Observability.OtelWrite permesso sulla risorsa Agent 365 Observability per il cloud selezionato:

Cloud ID dell'applicazione della risorsa di osservabilità
Commerciale 9b975845-388f-4429-889e-eab1ef63949c
GCC 2c672ad5-b104-44ed-8069-bb68dd138546
GCC High 009c6bd0-82e4-4466-95b3-4c996521f3d7
Dipartimento della Difesa (DoD) a9e04047-c6a7-430b-a7ae-faf8f8eed1b7

Le versioni precedenti della CLI concedevano sempre il permesso sulla risorsa commerciale Observability. Se configuri un agente in un cloud del governo USA con una versione precedente, imposta l'ambiente del tuo cloud e riesegui a365 setup all in modo che la CLI conceda il permesso sulla risorsa di Observability del cloud.

Verificare la configurazione

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

Risolvere i problemi di configurazione cloud

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

Sintomo Cause Resolution
Authority host must be an HTTPS origin without a path, query, fragment, or user info. (o lo stesso errore per l'URL base del Graph) L'host dell'autorità o l'URL base di Graph include un percorso, una stringa di query o un frammento. Usa un'origine HTTPS semplice. Ad esempio, usare https://login.microsoftonline.us anziché https://login.microsoftonline.us/common/oauth2/v2.0/authorize.
Un errore dice che AzureUSGovernment oppure il cloud interfaccia della riga di comando di Azure non distingue GCC Moderate (GCC), GCC High e DoD. L'ambiente è AzureUSGovernment o la configurazione ha rilevato quel cloud dall'interfaccia della riga di comando di Azure. Imposta l'ambiente su gcc, gcc-high, o dod.
La CLI chiama il servizio commerciale Agent 365 in un cloud del governo degli Stati Uniti. A365_DISCOVER_ENDPOINT_<ENV> non è impostato, oppure il suo suffisso non corrisponde al nome dell'ambiente. Imposta A365_DISCOVER_ENDPOINT_<ENV> con il suffisso per il tuo ambiente.
Il setup concede i permessi sulla risorsa commerciale di Observability. L'ambiente non è impostato, quindi la CLI usa prod. Imposta l'ambiente per il cloud e riesegui la configurazione.
PowerShell fallback is available only for commercial Graph and authority endpoints. L'accesso a Microsoft Graph non è riuscito e la CLI non può ripiegare su PowerShell Connect-MgGraph quando usi endpoint personalizzati. Risolvi l'errore di accesso. Ad esempio, conferma di aver registrato la tua app client nel tuo cloud e di aver effettuato l'accesso con un account nel tenant del tuo cloud.

Contenuti correlati

  • Ultimo aggiornamento: