Настройте CLI Agent 365 для облаков правительства США

По умолчанию CLI Agent 365 ориентирован на коммерческое облако Microsoft. Он аутентифицируется с помощью https://login.microsoftonline.com, вызывает Microsoft Graph по https://graph.microsoft.comадресу , а сервисы Agent 365 — по https://agent365.svc.cloud.microsoftадресу . Облака Microsoft 365 правительства США — это Government Community Cloud (GCC), GCC High и Министерство обороны (DoD). Чтобы использовать CLI в одном из этих облаков, выберите облачную среду и настройте конечные точки для этого облака.

В этой статье объясняется, как CLI разрешает облачные настройки и как настроить их в вашем a365.config.json файле или с помощью переменных среды.

Note

Облачное разрешение конечных точек доступно в последних версиях Agent 365 CLI. Обновите до последней версии перед настройкой облака правительства США. Инструкции по обновлению см. Обновление CLI агента 365.

Это важно

Настраиваемые конечные точки не гарантируют, что все сервисы или функции Agent 365 доступны в каждом облаке. Некоторые сервисы и функции, доступные в коммерческом облаке, могут ещё не быть доступны в GCC, GCC High или DoD. Проверьте доступность сервиса для вашего облака перед установкой. Для доступности функций Agent 365 в GCC см. описание сервиса Microsoft Agent 365.

Поддерживаемые облачные среды

Название окружения указывает CLI, на какое облако вы нацеливаетесь. Устанавливайте это явно для каждого облака правительства США.

Облачные технологии environment Значение Суффикс переменной среды (<ENV>)
Коммерческая (по умолчанию) prod PROD
GCC gcc GCC
GCC High gcc-high GCC_HIGH
Министерство обороны dod DOD

Название среды управляет двумя поведениеми:

  • CLI считывает переменные с областью действия среды, соответствующие названию среды. Например, при gcc-high, CLI читает A365_GRAPH_BASE_URL_GCC_HIGH.
  • Настройка предоставляет разрешения на ресурс наблюдаемости Agent 365 для выбранного облака. Для получения дополнительной информации см. раздел разрешения на наблюдаемость.

Название среды само по себе не меняет авторитетный хост, базовый URL Microsoft Graph или конечные точки сервиса Agent 365. Настройте эти конечные точки для вашего облака, как описано в разделах Configure GCC и Configure GCC High или DoD.

Это важно

Не используйте облачное имя AzureUSGovernment Azure CLI в качестве среды. Это название не различает GCC, GCC High и DoD, поэтому CLI сообщает об ошибке конфигурации, когда требуется облачные настройки. Используйте gcc, gcc-high, или dod вместо этого.

Как CLI решает облачные настройки

CLI сначала разрешает имя среды, а затем использует его для разрешения каждой конечной точки.

Имя операционной среды

CLI использует первое найдённое значение:

  1. Поле environment в a365.config.json.
  2. Переменная среды A365_ENVIRONMENT.
  3. Для команд настройки, выполняемых без файлаa365.config.json, имя активного облака Azure CLI (az cloud show). Если облако Azure CLI — AzureUSGovernment, настройка останавливается и просит установить A365_ENVIRONMENT , gccgcc-high, или dod.
  4. По умолчанию prod.

При создании a365.config.json файла фиксируется разрешённые environmentзначения , authorityHostи graphBaseUrl , так что последующие команды нацелены на то же облако.

develop list-available Команда не читает a365.config.json. Он всегда считывает окружение из A365_ENVIRONMENT, поэтому устанавливайте эту переменную при использовании команды в облаке правительства США.

Авторитетный хост и базовый URL Microsoft Graph

Для каждой конечной точки CLI использует первое найдённое значение:

  1. Переменная среды, ограниченная областью окружающей среды (A365_AUTHORITY_HOST_<ENV> или A365_GRAPH_BASE_URL_<ENV>).
  2. Соответствующее поле в a365.config.json (authorityHost или graphBaseUrl).
  3. Коммерческое облачное устройство по умолчанию (https://login.microsoftonline.com или https://graph.microsoft.com).

CLI не считывает эти настройки из несуффиксных переменных, таких как A365_GRAPH_BASE_URL.

Каждое разрешённое значение должно быть источником HTTPS: схемой, хостом и необязательным портом. Не включайте путь, строку запроса, фрагмент или информацию пользователя. Например, CLI принимает https://login.microsoftonline.us , но отклоняет https://login.microsoftonline.us/common. Если значение не проходит валидацию, CLI останавливается с ошибкой.

CLI последовательно применяет разрешённый авторитетный хост и базовый URL Graph в процессах настройки, согласия, аутентификации, запроса Microsoft Entra ID, очистки и создания экземпляров. Он кэширует токены отдельно для каждого хоста авторитета, поэтому переключение облаков не приводит к повторному использованию токен из другого облака.

Это важно

Объедините хост авторитета и базовый URL Graph для одного облака. Если вы переопределите одно, переопределите другое, чтобы аутентификация и вызовы по плоскости данных Graph были нацелены на одну и ту же среду.

Конечные точки обслуживания Agent 365

CLI вызывает сервисы Agent 365 для обнаружения серверов Model Context Protocol (MCP), управления MCP-серверами и регистрации конечной точки обмена сообщениями агента. Настройте эти сервисные конечные точки только с переменными среды. В этих конечных точках нет a365.config.json полей.

Variable Description
A365_DISCOVER_ENDPOINT_<ENV> Полный URL конечной точки обнаружения Agent 365 Tools. CLI вызывает этот URL для обнаружения MCP-серверов. Он также использует исходную точку URL для связанных сервисных вызовов Agent 365, включая управление сервером MCP и регистрацию конечных точек сообщений. Значение по умолчанию — https://agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers.
A365_CREATE_ENDPOINT_<ENV> Полный URL, который CLI вызывает для регистрации конечной точки обмена сообщениями агента. Это значение имеет приоритет над началом .A365_DISCOVER_ENDPOINT_<ENV>
A365_DELETE_ENDPOINT_<ENV> Полный URL, который CLI вызывает для удаления регистрации конечной точки сообщений агента. Это значение имеет приоритет над началом .A365_DISCOVER_ENDPOINT_<ENV>

Каждое значение должно быть абсолютным HTTPS-адресом. Добавьте путь, если конечной точке он нужен, но не добавляйте строку запроса, фрагмент или информацию пользователя.

Это важно

Только установка имени среды не переключает сервисные вызовы Agent 365 с коммерческой. Если вы не установили A365_DISCOVER_ENDPOINT_<ENV>, CLI вызывает коммерческий сервис Agent 365, даже в облаке правительства США.

Настройка GCC

GCC использует коммерческий авторитетный хост и базовый URL Microsoft Graph, так что вам не нужно их переопределять. Дополнительные сведения см. в статье Развертывание национального облака Microsoft Graph. Установите среду на gcc и направьте сервисные вызовы агента 365 на сервис GCC.

В , задаём a365.config.jsonenvironment поле:

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

Затем задайте переменные окружения. Настройка A365_ENVIRONMENT также охватывает команды, которые не читаются a365.config.json, например develop list-available. В Bash выполните следующие команды:

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

В Windows PowerShell выполните следующие команды:

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

Настройте GCC High или DoD

GCC High и DoD используют собственный авторитетный хост и базовый URL Microsoft Graph:

Облачные технологии environment Значение Авторитетный хост (authorityHost) Базовый URL Microsoft Graph (graphBaseUrl)
GCC High gcc-high https://login.microsoftonline.us https://graph.microsoft.us
Министерство обороны dod https://login.microsoftonline.us https://dod-graph.microsoft.us

Эти значения взяты из следующих статей. Проверьте их для текущих конечных точек:

Арендаторы GCC High и DoD используют Azure для государственных организаций. CLI Agent 365 использует Azure CLI для некоторых операций, например, для обнаружения вашего арендатора, поэтому войдите в Azure CLI в Azure для государственных организаций. Для инструкций см. Соединиться с Azure для государственных организаций с Azure CLI. Azure services in Azure для государственных организаций также используют иные доменные имена, чем глобальный Azure. Например, если вы размещаете агента в Служба приложений Azure, ваш конечный пункт обмена сообщениями использует домен Azure для государственных организаций. Для отображения конечных точек см. Сравните Azure для государственных организаций и global Azure.

Устанавливайте эти значения в a365.config.json или с переменными среды. Переменные, ориентированные на окружение, имеют приоритет над полями a365.config.json сопоставления, поэтому используйте их для переопределения отмеченной конфигурации для каждой машины или конвейера.

Настраивать в a365.config.json

Следующий пример нацелен на средний 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": "."
}

Настройка с переменными среды

Следующий пример Bash предназначен для 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"

Следующий пример Windows PowerShell предназначен для 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"

Для DoD установите среду на dod, используйте DOD суффикс и используйте базовый URL Microsoft Graph DoD.

Если сервисы Agent 365 доступны в вашем облаке, также установите A365_DISCOVER_ENDPOINT_<ENV> конечную точку обнаружения для этого облака. В противном случае CLI вызывает коммерческий сервис Agent 365. Для получения дополнительной информации см. сервисные конечные точки Agent 365.

Справочник по конфигурации

В этом разделе перечислены a365.config.json свойства и переменные среды, управляющие настройками облака.

a365.config.json свойства

Property Description Required Default
environment Имя облачной среды. Используйте prod, gcc, gcc-high, или dod. Это значение определяет, какие переменные с охватом среды читает CLI и какие ресурсы использует настройка Observability. No prod
authorityHost Хост OAuth для выбранного облака. Значение должно быть источником HTTPS. No https://login.microsoftonline.com
graphBaseUrl Базовый URL Microsoft Graph для выбранного облака. Значение должно быть источником HTTPS. No https://graph.microsoft.com

Переменные среды

Variable Description
A365_ENVIRONMENT Имя облачной среды. CLI использует это значение, когда a365.config.json не устанавливает environment, и для команд, которые не читают a365.config.json. Значение по умолчанию — prod.
A365_AUTHORITY_HOST_<ENV> Ведущий OAuth Authority. Это значение имеет приоритет над authorityHost .a365.config.json
A365_GRAPH_BASE_URL_<ENV> Базовый URL Microsoft Graph. Это значение имеет приоритет над graphBaseUrl .a365.config.json
A365_DISCOVER_ENDPOINT_<ENV> Конечная точка обнаружения Agent 365 Tools. CLI также использует свой источник для связанных сервисных вызовов Agent 365.
A365_CREATE_ENDPOINT_<ENV> URL регистрации конечной точки сообщений.
A365_DELETE_ENDPOINT_<ENV> URL удаления конечных точек сообщений.
A365_MCP_APP_ID_<ENV> Идентификатор ресурса Agent 365 Tools, который CLI использует для получения токенов для серверов инструментов. Большинству разработчиков не нужно устанавливать эту переменную.

Как производится суффикс окружения

CLI выводит <ENV> суффикс к каждой переменной с областью действия среды из имени вашей среды. CLI обрезает название, заменяет каждый символ, кроме буквы или цифры, на подчёркнутость (_), и переводит его в заглавную букву. Пустое имя становится PROD.

Имя операционной среды Нормализованный суффикс Пример переменной
gcc GCC A365_DISCOVER_ENDPOINT_GCC
gcc-high GCC_HIGH A365_GRAPH_BASE_URL_GCC_HIGH
dod DOD A365_AUTHORITY_HOST_DOD

Имя среды и суффикс переменной должны разрешиться с одним и тем же нормализованным значением. Например, A365_ENVIRONMENT=gcc-high сочетается с A365_AUTHORITY_HOST_GCC_HIGH.

Разрешения на наблюдаемость

Во время настройки CLI предоставляет чертежу агента Agent365.Observability.OtelWrite разрешение на ресурс наблюдаемости Agent 365 для выбранного облака:

Облачные технологии Идентификатор приложения ресурса наблюдаемости
Коммерция 9b975845-388f-4429-889e-eab1ef63949c
GCC 2c672ad5-b104-44ed-8069-bb68dd138546
GCC High 009c6bd0-82e4-4466-95b3-4c996521f3d7
Министерство обороны a9e04047-c6a7-430b-a7ae-faf8f8eed1b7

Ранние версии CLI всегда предоставляли разрешение на коммерческий ресурс наблюдаемости. Если вы настроили агента в облаке правительства США с более ранней версией, настройте среду для вашего облака и перезапустите a365 setup all так, чтобы CLI предоставил разрешение на ресурс наблюдаемости вашего облака.

Проверка конфигурации

После настройки облака выполните команду только для чтения и убедитесь, что CLI использует ожидаемые конечные точки. Рассмотрим пример.

Устранение неполадок в конфигурации облака

В следующей таблице приведены распространённые ошибки конфигурации облака и способы их устранения.

Симптом Причина Решение
Authority host must be an HTTPS origin without a path, query, fragment, or user info. (или такая же ошибка для базового URL графа) Авторитетный хост или базовый URL графа включает путь, строку запроса или фрагмент. Используйте чистый источник HTTPS. Например, используйте https://login.microsoftonline.us вместо https://login.microsoftonline.us/common/oauth2/v2.0/authorizeэтого.
Ошибка говорит, что AzureUSGovernment или облако Azure CLI не различает GCC Moderate (GCC), GCC High и DoD. Среда — AzureUSGovernmentэто , или установка, обнаруженная облаком из Azure CLI. Установите окружающую среду на gcc, gcc-highили dod.
CLI вызывает коммерческий сервис Agent 365 в облаке правительства США. A365_DISCOVER_ENDPOINT_<ENV> не устанавливается, или его суффикс не совпадает с названием окружения. Задайте A365_DISCOVER_ENDPOINT_<ENV> суффикс для вашей среды.
Setup предоставляет разрешения на коммерческий ресурс Observability. Среда не настроена, поэтому CLI использует prod. Настройте окружение для облака и запустите настройки заново.
PowerShell fallback is available only for commercial Graph and authority endpoints. Вход в Microsoft Graph провалился, и CLI не может вернуться к PowerShell Connect-MgGraph при использовании пользовательских конечных точек. Устраните ошибку входа. Например, подтвердите, что вы зарегистрировали клиентское приложение в облаке и что входили через аккаунт в арендаторе облака.

Связанные материалы

  • Последнее обновление: