Configure the Agent 365 CLI for US Government clouds

By default, the Agent 365 CLI targets the Microsoft commercial cloud. It authenticates by using https://login.microsoftonline.com, calls Microsoft Graph at https://graph.microsoft.com, and calls Agent 365 services at https://agent365.svc.cloud.microsoft. The Microsoft 365 US Government clouds are Government Community Cloud (GCC), GCC High, and Department of Defense (DoD). To use the CLI in one of these clouds, select the cloud environment and configure the endpoints for that cloud.

This article explains how the CLI resolves cloud settings and how to configure them in your a365.config.json file or with environment variables.

Note

Cloud-aware endpoint resolution is available in recent versions of the Agent 365 CLI. Update to the latest version before you configure a US Government cloud. For update instructions, see Update the Agent 365 CLI.

Important

Configurable endpoints don't guarantee that every Agent 365 service or feature is available in every cloud. Some services and features that are available in the commercial cloud might not yet be available in GCC, GCC High, or DoD. Confirm service availability for your cloud before you run setup. For Agent 365 feature availability in GCC, see the Microsoft Agent 365 service description.

Supported cloud environments

The environment name tells the CLI which cloud you target. Set it explicitly for every US Government cloud.

Cloud environment value Environment variable suffix (<ENV>)
Commercial (default) prod PROD
GCC gcc GCC
GCC High gcc-high GCC_HIGH
DoD dod DOD

The environment name controls two behaviors:

  • The CLI reads the environment-scoped variables that match the environment name. For example, with gcc-high, the CLI reads A365_GRAPH_BASE_URL_GCC_HIGH.
  • Setup grants permissions on the Agent 365 Observability resource for the selected cloud. For more information, see Observability permissions.

The environment name doesn't change the authority host, Microsoft Graph base URL, or Agent 365 service endpoints on its own. Configure those endpoints for your cloud as described in Configure GCC and Configure GCC High or DoD.

Important

Don't use the Azure CLI cloud name AzureUSGovernment as the environment. That name doesn't distinguish between GCC, GCC High, and DoD, so the CLI reports a configuration error when it needs cloud-specific settings. Use gcc, gcc-high, or dod instead.

How the CLI resolves cloud settings

The CLI resolves the environment name first, and then uses it to resolve each endpoint.

Environment name

The CLI uses the first value it finds:

  1. The environment field in a365.config.json.
  2. The A365_ENVIRONMENT environment variable.
  3. For setup commands that run without an a365.config.json file, the name of the active Azure CLI cloud (az cloud show). If the Azure CLI cloud is AzureUSGovernment, setup stops and asks you to set A365_ENVIRONMENT to gcc, gcc-high, or dod.
  4. The default, prod.

When setup generates an a365.config.json file, it records the resolved environment, authorityHost, and graphBaseUrl values so later commands target the same cloud.

The develop list-available command doesn't read a365.config.json. It always reads the environment from A365_ENVIRONMENT, so set that variable when you use the command in a US Government cloud.

Authority host and Microsoft Graph base URL

For each endpoint, the CLI uses the first value it finds:

  1. The environment-scoped environment variable (A365_AUTHORITY_HOST_<ENV> or A365_GRAPH_BASE_URL_<ENV>).
  2. The matching field in a365.config.json (authorityHost or graphBaseUrl).
  3. The commercial-cloud default (https://login.microsoftonline.com or https://graph.microsoft.com).

The CLI doesn't read these settings from unsuffixed variables such as A365_GRAPH_BASE_URL.

Each resolved value must be an HTTPS origin: a scheme, host, and optional port only. Don't include a path, query string, fragment, or user information. For example, the CLI accepts https://login.microsoftonline.us but rejects https://login.microsoftonline.us/common. If a value fails validation, the CLI stops with an error.

The CLI applies the resolved authority host and Graph base URL consistently across setup, consent, authentication, Microsoft Entra ID query, cleanup, and create-instance flows. It caches tokens separately for each authority host, so switching clouds doesn't reuse tokens from another cloud.

Important

Pair the authority host and the Graph base URL for the same cloud. If you override one, override the other so authentication and Graph data-plane calls target the same environment.

Agent 365 service endpoints

The CLI calls Agent 365 services to discover Model Context Protocol (MCP) servers, manage MCP servers, and register the agent's messaging endpoint. Configure these service endpoints with environment variables only. These endpoints don't have a365.config.json fields.

Variable Description
A365_DISCOVER_ENDPOINT_<ENV> The full URL of the Agent 365 Tools discovery endpoint. The CLI calls this URL to discover MCP servers. It also uses the URL's origin for related Agent 365 service calls, including MCP server management and messaging endpoint registration. The default value is https://agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers.
A365_CREATE_ENDPOINT_<ENV> The full URL that the CLI calls to register the agent's messaging endpoint. This value takes precedence over the origin of A365_DISCOVER_ENDPOINT_<ENV>.
A365_DELETE_ENDPOINT_<ENV> The full URL that the CLI calls to remove the agent's messaging endpoint registration. This value takes precedence over the origin of A365_DISCOVER_ENDPOINT_<ENV>.

Each value must be an absolute HTTPS URL. Include a path if the endpoint needs one, but don't include a query string, fragment, or user information.

Important

Setting the environment name alone doesn't switch Agent 365 service calls away from the commercial service. If you don't set A365_DISCOVER_ENDPOINT_<ENV>, the CLI calls the commercial Agent 365 service, even in a US Government cloud.

Configure GCC

GCC uses the commercial authority host and Microsoft Graph base URL, so you don't need to override them. For more information, see Microsoft Graph national cloud deployments. Set the environment to gcc and point Agent 365 service calls at the GCC service.

In a365.config.json, set the environment field:

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

Then set the environment variables. Setting A365_ENVIRONMENT also covers commands that don't read a365.config.json, such as develop list-available. In Bash, run the following commands:

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

In Windows PowerShell, run the following commands:

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

Configure GCC High or DoD

GCC High and DoD use their own authority host and Microsoft Graph base URL:

Cloud environment value Authority host (authorityHost) Microsoft Graph base URL (graphBaseUrl)
GCC High gcc-high https://login.microsoftonline.us https://graph.microsoft.us
DoD dod https://login.microsoftonline.us https://dod-graph.microsoft.us

These values come from the following articles. Check them for the current endpoints:

GCC High and DoD tenants use Azure Government. The Agent 365 CLI uses the Azure CLI for some operations, such as detecting your tenant, so sign in to the Azure CLI in Azure Government. For instructions, see Connect to Azure Government with Azure CLI. Azure services in Azure Government also use different domain names than global Azure. For example, if you host your agent in Azure App Service, your messaging endpoint uses an Azure Government domain. For the endpoint mapping, see Compare Azure Government and global Azure.

Set these values in a365.config.json or with environment variables. Environment-scoped variables take precedence over the matching a365.config.json fields, so use them to override a checked-in configuration per machine or per pipeline.

Configure in a365.config.json

The following example targets 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": "."
}

Configure with environment variables

The following Bash example targets 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"

The following Windows PowerShell example targets 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"

For DoD, set the environment to dod, use the DOD suffix, and use the DoD Microsoft Graph base URL.

If Agent 365 services are available in your cloud, also set A365_DISCOVER_ENDPOINT_<ENV> to the discovery endpoint for that cloud. Otherwise, the CLI calls the commercial Agent 365 service. For more information, see Agent 365 service endpoints.

Configuration reference

This section lists the a365.config.json properties and environment variables that control cloud settings.

a365.config.json properties

Property Description Required Default
environment The cloud environment name. Use prod, gcc, gcc-high, or dod. This value determines which environment-scoped variables the CLI reads and which Observability resource setup uses. No prod
authorityHost The OAuth authority host for the selected cloud. The value must be an HTTPS origin. No https://login.microsoftonline.com
graphBaseUrl The Microsoft Graph base URL for the selected cloud. The value must be an HTTPS origin. No https://graph.microsoft.com

Environment variables

Variable Description
A365_ENVIRONMENT The cloud environment name. The CLI uses this value when a365.config.json doesn't set environment, and for commands that don't read a365.config.json. The default value is prod.
A365_AUTHORITY_HOST_<ENV> The OAuth authority host. This value takes precedence over authorityHost in a365.config.json.
A365_GRAPH_BASE_URL_<ENV> The Microsoft Graph base URL. This value takes precedence over graphBaseUrl in a365.config.json.
A365_DISCOVER_ENDPOINT_<ENV> The Agent 365 Tools discovery endpoint. The CLI also uses its origin for related Agent 365 service calls.
A365_CREATE_ENDPOINT_<ENV> The messaging endpoint registration URL.
A365_DELETE_ENDPOINT_<ENV> The messaging endpoint removal URL.
A365_MCP_APP_ID_<ENV> The Agent 365 Tools resource application ID that the CLI uses to acquire tokens for tool servers. Most developers don't need to set this variable.

How the environment suffix is derived

The CLI derives the <ENV> suffix on each environment-scoped variable from your environment name. The CLI trims the name, replaces every character that isn't a letter or digit with an underscore (_), and converts it to uppercase. An empty name becomes PROD.

Environment name Normalized suffix Example variable
gcc GCC A365_DISCOVER_ENDPOINT_GCC
gcc-high GCC_HIGH A365_GRAPH_BASE_URL_GCC_HIGH
dod DOD A365_AUTHORITY_HOST_DOD

The environment name and the suffix on the variable must resolve to the same normalized value. For example, A365_ENVIRONMENT=gcc-high pairs with A365_AUTHORITY_HOST_GCC_HIGH.

Observability permissions

During setup, the CLI grants the agent blueprint the Agent365.Observability.OtelWrite permission on the Agent 365 Observability resource for the selected cloud:

Cloud Observability resource application ID
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

Earlier versions of the CLI always granted the permission on the commercial Observability resource. If you set up an agent in a US Government cloud with an earlier version, set the environment for your cloud and rerun a365 setup all so the CLI grants the permission on your cloud's Observability resource.

Verify your configuration

After you configure a cloud, run a read-only command and confirm the CLI uses the expected endpoints. For example:

Troubleshoot cloud configuration

The following table lists common cloud configuration errors and how to resolve them.

Symptom Cause Resolution
Authority host must be an HTTPS origin without a path, query, fragment, or user info. (or the same error for the Graph base URL) The authority host or Graph base URL includes a path, query string, or fragment. Use a bare HTTPS origin. For example, use https://login.microsoftonline.us rather than https://login.microsoftonline.us/common/oauth2/v2.0/authorize.
An error says that AzureUSGovernment or the Azure CLI cloud doesn't distinguish GCC Moderate (GCC), GCC High, and DoD. The environment is AzureUSGovernment, or setup detected that cloud from the Azure CLI. Set the environment to gcc, gcc-high, or dod.
The CLI calls the commercial Agent 365 service in a US Government cloud. A365_DISCOVER_ENDPOINT_<ENV> isn't set, or its suffix doesn't match the environment name. Set A365_DISCOVER_ENDPOINT_<ENV> with the suffix for your environment.
Setup grants permissions on the commercial Observability resource. The environment isn't set, so the CLI uses prod. Set the environment for your cloud and rerun setup.
PowerShell fallback is available only for commercial Graph and authority endpoints. Microsoft Graph sign-in failed, and the CLI can't fall back to PowerShell Connect-MgGraph when you use custom endpoints. Resolve the sign-in failure. For example, confirm that you registered your client app in your cloud and that you sign in with an account in your cloud's tenant.

Related content

  • Last updated on