Configure o Agent 365 CLI para as nuvens do governo dos EUA

Por padrão, a CLI do Agente 365 é direcionada para a nuvem comercial da Microsoft. Ele autentica usando https://login.microsoftonline.com, chama o Microsoft Graph em https://graph.microsoft.com, e chama os serviços do Agent 365 em https://agent365.svc.cloud.microsoft. As nuvens do governo dos EUA para o Microsoft 365 são a Government Community Cloud (GCC), GCC High e Department of Defense (DoD). Para usar a CLI em uma dessas nuvens, selecione o ambiente da nuvem e configure os endpoints dessa nuvem.

Este artigo explica como a CLI resolve as configurações de nuvem e como configurá-las no arquivo a365.config.json ou com variáveis de ambiente.

Note

A resolução de endpoints consciente da nuvem está disponível nas versões recentes da CLI do Agente 365. Atualize para a versão mais recente antes de configurar uma nuvem do governo dos EUA. Para instruções de atualização, veja Atualizar o Agent 365 CLI.

Importante

Endpoints configuráveis não garantem que todo serviço ou recurso do Agent 365 esteja disponível em todas as nuvens. Alguns serviços e recursos disponíveis na nuvem comercial podem ainda não estar disponíveis no GCC, GCC High ou DoD. Confirme a disponibilidade do serviço para sua nuvem antes de iniciar a configuração. Para a disponibilidade de recursos do Agent 365 no GCC, veja a descrição do serviço do Microsoft Agent 365.

Ambientes de nuvem com suporte

O nome do ambiente informa à CLI qual nuvem você está mirando. Defina explicitamente para toda nuvem do governo dos EUA.

Nuvem environment valor Sufixo da variável de ambiente (<ENV>)
Comercial (padrão) prod PROD
GCC gcc GCC
GCC High gcc-high GCC_HIGH
DoD dod DOD

O nome do ambiente controla dois comportamentos:

  • A CLI lê as variáveis com escopo de ambiente que correspondem ao nome do ambiente. Por exemplo, com gcc-high, a CLI lê A365_GRAPH_BASE_URL_GCC_HIGH.
  • A instalação concede permissões sobre o recurso Agent 365 Observability para a nuvem selecionada. Para mais informações, veja Permissões de observabilidade.

O nome do ambiente não altera o host de autoridade, a URL base do Microsoft Graph ou os endpoints do serviço Agent 365 por si só. Configure esses endpoints para sua nuvem conforme descrito em Configurar GCC e Configurar GCC High ou DoD.

Importante

Não use como ambiente o nome da nuvem AzureUSGovernment da CLI do Azure. Esse nome não distingue entre GCC, GCC High e DoD, então a CLI reporta um erro de configuração quando precisa de configurações específicas da nuvem. Utilize gcc, gcc-high, ou dod em vez disso.

Como a CLI resolve as configurações da nuvem

A CLI primeiro resolve o nome do ambiente e depois o usa para resolver cada endpoint.

Nome do ambiente

A CLI usa o primeiro valor que encontra:

  1. O campo environment em a365.config.json.
  2. A variável de ambiente A365_ENVIRONMENT.
  3. Para comandos de configuração que rodam sem um arquivo a365.config.json, o nome da nuvem ativa da CLI do Azure (az cloud show). Se a nuvem da CLI do Azure for AzureUSGovernment, a configuração para e pede que você defina A365_ENVIRONMENT para gcc, gcc-high, ou dod.
  4. A opção padrão, prod.

Quando a instalação gera um arquivo a365.config.json, ele registra os valores resolvidos environment, authorityHost e graphBaseUrl para que comandos posteriores sejam direcionados à mesma nuvem.

O develop list-available comando não lê a365.config.json. Ele sempre lê o ambiente de A365_ENVIRONMENT, então defina essa variável quando usar o comando em uma nuvem do governo dos EUA.

Host de autoridade e URL base do Microsoft Graph

Para cada endpoint, a CLI usa o primeiro valor que encontra:

  1. A variável de ambiente com escopo de ambiente (A365_AUTHORITY_HOST_<ENV> ou A365_GRAPH_BASE_URL_<ENV>).
  2. O campo de correspondência em a365.config.json (authorityHost ou graphBaseUrl).
  3. O padrão da nuvem comercial (https://login.microsoftonline.com ou https://graph.microsoft.com).

A CLI não lê essas configurações dessas variáveis sem sufixo, como A365_GRAPH_BASE_URL.

Cada valor resolvido deve ser uma origem HTTPS origin: apenas esquema, host e porta opcional. Não inclua um caminho, string de consulta, fragmento ou informações do usuário. Por exemplo, a CLI aceita https://login.microsoftonline.us , mas rejeita https://login.microsoftonline.us/common. Se um valor falhar na validação, a CLI para com um erro.

A CLI aplica consistentemente o host de autoridade resolvida e a URL base do Graph em processos de configuração, consentimento, autenticação, consulta do Microsoft Entra ID, limpeza e criação de instância. Ele armazena tokens separadamente para cada host de autoridade, então trocar de nuvem não reutiliza tokens de outra nuvem.

Importante

Associe o host de autoridade e a URL base do Graph para a mesma nuvem. Se você sobrescrever um, sobrescreva o outro para que autenticação e chamadas de plano de dados Graph tenham como alvo o mesmo ambiente.

Endpoints de serviço do Agent 365

A CLI chama os serviços do Agent 365 para descobrir servidores do Model Context Protocol (MCP), gerenciar servidores MCP e registrar o endpoint de mensagens do agente. Configure estes endpoints de serviço apenas com variáveis de ambiente. Esses endpoints não possuem a365.config.json campos.

Variable Description
A365_DISCOVER_ENDPOINT_<ENV> A URL completa do endpoint de descoberta do Agent 365 Tools. A CLI chama essa URL para descobrir servidores MCP. Também utiliza a origem da URL para chamadas de serviço Agent 365 relacionadas, incluindo gerenciamento de servidores MCP e registro de endpoints de mensagens. O valor padrão é https://agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers.
A365_CREATE_ENDPOINT_<ENV> A URL completa que a CLI chama para registrar o endpoint de mensagens do agente. Esse valor tem precedência sobre a origem de A365_DISCOVER_ENDPOINT_<ENV>.
A365_DELETE_ENDPOINT_<ENV> A URL completa que a CLI chama para remover o registro do endpoint de mensagens do agente. Esse valor tem precedência sobre a origem de A365_DISCOVER_ENDPOINT_<ENV>.

Cada valor deve ser uma URL HTTPS absoluta. Inclua um caminho se o endpoint precisar, mas não inclua uma string de consulta, fragmento ou informações do usuário.

Importante

Definir apenas o nome do ambiente não redireciona as chamadas de serviço do Agente 365 do serviço comercial. Se você não configurar A365_DISCOVER_ENDPOINT_<ENV>, a CLI chama o serviço comercial Agent 365, mesmo em uma nuvem do governo dos EUA.

Configurar o GCC

O GCC usa o host da autoridade comercial e a URL base do Microsoft Graph, então você não precisa sobrescrevê-los. Para obter mais informações, consulte Implantações de nuvem nacional do Microsoft Graph. Defina o ambiente para gcc e aponte as chamadas de serviço do Agente 365 para o serviço GCC.

Em a365.config.json, defina o environment campo:

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

Depois, defina as variáveis de ambiente. Definir A365_ENVIRONMENT também cobre comandos que não leem a365.config.json, como develop list-available. No Bash, execute os seguintes comandos:

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

No Windows PowerShell, execute os seguintes comandos:

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

Configurar GCC High ou DoD

GCC High e DoD usam seu próprio host de autoridade e URL base do Microsoft Graph:

Nuvem environment valor Host de autoridade (authorityHost) URL base do 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

Esses valores vêm dos artigos a seguir. Verifique-os quanto aos endpoints atuais:

Os inquilinos do GCC High e do DoD usam o Azure Governamental. O Agent 365 CLI usa o CLI do Azure para algumas operações, como detectar seu locatário, então faça login no CLI do Azure no Azure Governamental. Para instruções, veja Conectar-se ao Azure Governamental com a CLI do Azure. Os serviços do Azure no Azure Governamental também usam nomes de domínio diferentes do Azure global. Por exemplo, se você hospeda seu agente no Serviço de Aplicativo do Azure, seu endpoint de mensagens usa um domínio Azure Governamental. Para o mapeamento de endpoints, veja Comparar o Azure Governamental e o Azure global.

Defina esses valores em a365.config.json ou com variáveis de ambiente. Variáveis com escopo de ambiente têm precedência sobre os campos correspondentes a365.config.json, então use-as para substituir uma configuração versionada por máquina ou por pipeline.

Configure no arquivo a365.config.json

O exemplo a seguir tem como alvo 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": "."
}

Configurar com variáveis de ambiente

O exemplo a seguir do Bash tem como alvo a 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"

O exemplo a seguir do PowerShell do Windows tem como alvo o 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"

Para DoD, defina o ambiente para dod, use o DOD sufixo e use a URL base do Microsoft Graph do DoD.

Se os serviços do Agent 365 estiverem disponíveis na sua nuvem, também defina A365_DISCOVER_ENDPOINT_<ENV> para o endpoint de descoberta dessa nuvem. Caso contrário, o CLI chama o serviço comercial Agent 365. Para mais informações, veja endpoints de serviço do Agent 365.

Referência de configuração

Esta seção lista as a365.config.json propriedades e variáveis de ambiente que controlam as configurações da nuvem.

Propriedades de a365.config.json

Property Description Required Default
environment O nome do ambiente de nuvem. Use prod, gcc, gcc-high ou dod. Esse valor determina quais variáveis com escopo de ambiente a CLI lê e quais configurações de recursos de observabilidade usam esse valor. No prod
authorityHost O host de autoridade OAuth para a nuvem selecionada. O valor deve ser uma origem com HTTPS. No https://login.microsoftonline.com
graphBaseUrl A URL base do Microsoft Graph para a nuvem selecionada. O valor deve ser uma origem HTTPS. No https://graph.microsoft.com

Variáveis de ambiente

Variable Description
A365_ENVIRONMENT O nome do ambiente de nuvem. A CLI usa esse valor quando a365.config.json não define environment, e para comandos que não leem a365.config.json. O valor padrão é prod.
A365_AUTHORITY_HOST_<ENV> O host de autoridade OAuth. Esse valor tem precedência sobre authorityHost em a365.config.json.
A365_GRAPH_BASE_URL_<ENV> A URL base do Microsoft Graph. Esse valor tem precedência sobre graphBaseUrl em a365.config.json.
A365_DISCOVER_ENDPOINT_<ENV> O endpoint de descoberta do Agent 365 Tools. O CLI também usa sua origem para chamadas de serviço relacionadas do Agent 365.
A365_CREATE_ENDPOINT_<ENV> A URL de registro do endpoint de mensagens.
A365_DELETE_ENDPOINT_<ENV> A URL de remoção do endpoint de mensagens.
A365_MCP_APP_ID_<ENV> O ID de recurso da aplicação Agent 365 Tools que a CLI usa para adquirir tokens para servidores de ferramentas. A maioria dos desenvolvedores não precisa definir essa variável.

Como o sufixo de ambiente é derivado

A CLI deriva o <ENV> sufixo de cada variável com escopo de ambiente a partir do nome do seu ambiente. A CLI corta o nome, substitui cada caractere que não seja letra ou dígito por um sublinhado (_), e converte para maiúsculas. Um nome vazio torna-se PROD.

Nome do ambiente Sufixo normalizado Variável de exemplo
gcc GCC A365_DISCOVER_ENDPOINT_GCC
gcc-high GCC_HIGH A365_GRAPH_BASE_URL_GCC_HIGH
dod DOD A365_AUTHORITY_HOST_DOD

O nome do ambiente e o sufixo da variável devem resultar no mesmo valor normalizado. Por exemplo, A365_ENVIRONMENT=gcc-high faz par com A365_AUTHORITY_HOST_GCC_HIGH.

Permissões de observabilidade

Durante a configuração, a CLI concede ao blueprint do agente a permissão Agent365.Observability.OtelWrite sobre o recurso de Observabilidade do Agente 365 da nuvem selecionada:

Nuvem ID de aplicação de recurso de observabilidade
Comercial 9b975845-388f-4429-889e-eab1ef63949c
GCC 2c672ad5-b104-44ed-8069-bb68dd138546
GCC High 009c6bd0-82e4-4466-95b3-4c996521f3d7
DoD a9e04047-c6a7-430b-a7ae-faf8f8eed1b7

Versões anteriores da CLI sempre concediam a permissão sobre o recurso comercial de Observabilidade. Se você configurar um agente em uma nuvem do governo dos EUA com uma versão anterior, configure o ambiente para sua nuvem e execute a365 setup all novamente para que a CLI conceda a permissão para o recurso de Observabilidade da sua nuvem.

Verificar sua configuração

Depois de configurar uma nuvem, execute um comando somente leitura e confirme que a CLI usa os endpoints esperados. Por exemplo:

Solucionar problemas de configuração da nuvem

A tabela a seguir lista erros comuns de configuração na nuvem e como resolvê-los.

Sintoma Cause Resolução
Authority host must be an HTTPS origin without a path, query, fragment, or user info. (ou o mesmo erro para a URL base do Graph) A autoridade host ou URL base do Graph inclui um caminho, string de consulta ou fragmento. Use uma origem HTTPS simples. Por exemplo, use https://login.microsoftonline.us em vez de https://login.microsoftonline.us/common/oauth2/v2.0/authorize.
Uma mensagem de erro informa que AzureUSGovernment ou a nuvem do CLI do Azure não distingue GCC Moderate (GCC), GCC High e DoD. O ambiente é AzureUSGovernment, ou a configuração detectou essa nuvem pela CLI do Azure. Defina o ambiente para gcc, gcc-high, ou dod.
A CLI chama o serviço comercial Agent 365 em uma nuvem do governo dos EUA. A365_DISCOVER_ENDPOINT_<ENV> não está definido, ou seu sufixo não corresponde ao nome do ambiente. Defina A365_DISCOVER_ENDPOINT_<ENV> com o sufixo do seu ambiente.
Setup concede permissões sobre o recurso comercial de Observabilidade. O ambiente não está definido, então a CLI usa prod. Configure o ambiente da sua nuvem e execute a configuração novamente.
PowerShell fallback is available only for commercial Graph and authority endpoints. O login do Microsoft Graph falhou, e a CLI não pode voltar ao PowerShell Connect-MgGraph quando você usa endpoints personalizados. Resolva a falha no login. Por exemplo, confirme que você registrou seu aplicativo cliente na sua nuvem e que você faz login com uma conta no tenant da sua nuvem.

Conteúdo relacionado

  • Last updated on