Configurar la CLI de Agent 365 para las nubes del Gobierno de EE. UU.

Por defecto, la CLI Agent 365 está dirigida a la nube comercial de Microsoft. Se autentica usando https://login.microsoftonline.com, llama a Microsoft Graph en https://graph.microsoft.com, y llama a los servicios Agent 365 en https://agent365.svc.cloud.microsoft. Las nubes del Gobierno de EE. UU. para Microsoft 365 son Government Community Cloud (GCC), GCC High y Department of Defense (DoD). Para usar la CLI en una de estas nubes, selecciona el entorno de la nube y configura los endpoints de esa nube.

Este artículo explica cómo la CLI resuelve la configuración de la nube y cómo configurarla en tu archivo a365.config.json o con variables de entorno.

Note

La resolución de endpoints consciente de la nube está disponible en versiones recientes de la CLI del Agente 365. Actualiza a la última versión antes de configurar una nube del Gobierno de EE. UU. Para las instrucciones de actualización, consulte Actualizar la CLI del Agente 365.

Importante

Los endpoints configurables no garantizan que todos los servicios o funciones de Agent 365 estén disponibles en cada nube. Algunos servicios y funciones disponibles en la nube comercial pueden no estar aún disponibles en GCC, GCC High o DoD. Confirma la disponibilidad del servicio para tu nube antes de iniciar la configuración. Para la disponibilidad de funciones de Agent 365 en GCC, consulte la descripción del servicio de Microsoft Agent 365.

Entornos de nube admitidos

El nombre del entorno indica a la CLI a qué nube te diriges. Configúralo explícitamente para cada nube del gobierno de EE. UU.

Cloud environment valor Sufijo de variable de entorno (<ENV>)
Comercial (por defecto) prod PROD
GCC gcc GCC
GCC High gcc-high GCC_HIGH
DoD dod DOD

El nombre del entorno controla dos comportamientos:

  • La CLI lee las variables con alcance de entorno que coinciden con el nombre del entorno. Por ejemplo, con gcc-high, la CLI lee A365_GRAPH_BASE_URL_GCC_HIGH.
  • La configuración concede permisos sobre el recurso de observabilidad Agent 365 para la nube seleccionada. Para más información, consulte Permisos de observabilidad.

El nombre del entorno no cambia por sí solo el host de autoridad, la URL base de Microsoft Graph ni los endpoints del servicio Agent 365. Configura esos puntos finales para tu nube como se describe en Configurar GCC y Configurar GCC Alto o DoD.

Importante

No uses el nombre de la nube de CLI de Azure AzureUSGovernment como entorno. Ese nombre no distingue entre GCC, GCC High y DoD, por lo que la CLI reporta un error de configuración cuando necesita ajustes específicos de la nube. Usa gcc, gcc-high, o dod en su lugar.

Cómo resuelve la CLI la configuración de la nube

La CLI resuelve primero el nombre del entorno y luego lo utiliza para resolver cada endpoint.

Nombre del entorno

La CLI utiliza el primer valor que encuentra:

  1. El campo environment está en a365.config.json.
  2. Variable de entorno A365_ENVIRONMENT.
  3. Para comandos de configuración que se ejecutan sin un a365.config.json archivo, el nombre de la nube activa de CLI de Azure (az cloud show). Si la nube de CLI de Azure es AzureUSGovernment, la instalación se detiene y te pide que configures A365_ENVIRONMENT en gcc, gcc-high o dod.
  4. El valor por defecto, prod.

Cuando la instalación genera un archivo a365.config.json, registra los valores resueltos de environment, authorityHost y graphBaseUrl para que los comandos posteriores se dirijan a la misma nube.

develop list-available comando no lee a365.config.json. Siempre lee el entorno desde A365_ENVIRONMENT, así que establece esa variable cuando uses el comando en una nube del Gobierno de EE. UU.

Host de autoridad y URL base de Microsoft Graph

Para cada punto de conexión, la CLI utiliza el primer valor que encuentra:

  1. La variable de entorno con ámbito de entorno (A365_AUTHORITY_HOST_<ENV> o A365_GRAPH_BASE_URL_<ENV>).
  2. El campo de emparejamiento en a365.config.json (authorityHost o graphBaseUrl).
  3. El valor predeterminado de la nube comercial (https://login.microsoftonline.com o https://graph.microsoft.com).

La CLI no lee estos ajustes desde variables sin sufijo como A365_GRAPH_BASE_URL.

Cada valor resuelto debe ser un origen HTTPS: solo esquema, host y puerto opcional. No incluyas ruta, cadena de consulta, fragmento ni información de usuario. Por ejemplo, el CLI acepta https://login.microsoftonline.us pero rechaza https://login.microsoftonline.us/common. Si un valor falla en la validación, la CLI se detiene con un error.

La CLI aplica el host de autoridad resuelta y la URL base de Graph de forma consistente en los flujos de configuración, consentimiento, autenticación, consulta de Microsoft Entra ID, limpieza y creación de instancias. Almacena en caché los tokens por separado para cada host de autoridad, así que cambiar de nube no reutiliza tokens de otra nube.

Importante

Empareja el host de autoridad y la URL base de Graph para la misma nube. Si sobrescribes uno, sobrescribe el otro para que las llamadas de autenticación y Graph data-plane se dirijan al mismo entorno.

Endpoints de servicio Agent 365

La CLI llama a los servicios de Agent 365 para descubrir servidores de Model Context Protocol (MCP), gestionar servidores MCP y registrar el punto final de mensajería del agente. Configura estos endpoints de servicio solo con variables de entorno. Estos endpoints no tienen campos a365.config.json.

Variable Description
A365_DISCOVER_ENDPOINT_<ENV> La URL completa del endpoint de descubrimiento de Agent 365 Tools. La CLI llama a esta URL para descubrir servidores MCP. También utiliza el origen de la URL para llamadas de servicio Agent 365 relacionadas, incluyendo la gestión del servidor MCP y el registro de endpoints de mensajería. El valor por defecto es https://agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers.
A365_CREATE_ENDPOINT_<ENV> La URL completa a la que llama la CLI para registrar el punto final de mensajería del agente. Este valor tiene precedencia sobre el origen de A365_DISCOVER_ENDPOINT_<ENV>.
A365_DELETE_ENDPOINT_<ENV> La URL completa a la que llama la CLI para eliminar el registro del endpoint de mensajería del agente. Este valor tiene precedencia sobre el origen de A365_DISCOVER_ENDPOINT_<ENV>.

Cada valor debe ser una URL HTTPS absoluta. Incluye una ruta si el endpoint la necesita, pero no incluyas una cadena de consulta, fragmento o información de usuario.

Importante

Con solo establecer el nombre del entorno no se redirigen las llamadas de servicio de Agent 365 fuera del servicio comercial. Si no configuras A365_DISCOVER_ENDPOINT_<ENV>, la CLI llama al servicio comercial Agent 365, incluso en una nube del gobierno de EE. UU.

Configurar GCC

GCC utiliza el host de autoridad comercial y la URL base de Microsoft Graph, así que no necesitas sobrescribirlos. Para obtener más información, consulte Implementaciones de nube nacional de Microsoft Graph. Configura el entorno en gcc y apunta las llamadas de servicio del Agente 365 al servicio del GCC.

En a365.config.json, establece el environment campo:

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

Luego establece las variables de entorno. Establecer A365_ENVIRONMENT también cubre comandos que no leen a365.config.json, como develop list-available. En Bash, ejecuta los siguientes comandos:

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

En Windows PowerShell, ejecuta los siguientes comandos:

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

Configurar GCC High o DoD

GCC High y DoD utilizan su propio host de autoridad y la URL base de Microsoft Graph:

Cloud environment valor Host de autoridad (authorityHost) URL base de 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

Estos valores provienen de los siguientes artículos. Compruébalos para los puntos finales actuales:

Los inquilinos de GCC High y DoD utilizan Azure Government. La CLI de Agent 365 utiliza CLI de Azure para algunas operaciones, como detectar tu tenant, así que inicia sesión en CLI de Azure en Azure Government. Para las instrucciones, consulta Connect to Azure Government with CLI de Azure. Los servicios de Azure en Azure Government también utilizan nombres de dominio diferentes al Azure global. Por ejemplo, si alojas tu agente en Azure App Service, tu endpoint de mensajería utiliza un dominio Azure Government. Para el mapeo de endpoints, consulta Compare Azure Government y Azure global.

Establezca estos valores en a365.config.json o con variables de entorno. Las variables con alcance de entorno tienen prioridad sobre los campos correspondientes a365.config.json, por lo que úsalas para anular una configuración confirmada en el repositorio por máquina o por pipeline.

Configure en a365.config.json

El siguiente ejemplo se dirige 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 con variables de entorno

El siguiente ejemplo de Bash se aplica 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"

El siguiente ejemplo de PowerShell de Windows está dirigido 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"

Para DoD, configura el entorno en dod, usa el DOD sufijo y usa la URL base de Microsoft Graph del DoD.

Si los servicios de Agent 365 están disponibles en tu nube, también establece A365_DISCOVER_ENDPOINT_<ENV> en el endpoint de detección para esa nube. De lo contrario, el CLI llama al servicio comercial de Agent 365. Para más información, consulte los puntos de conexión del servicio de Agent 365.

Referencia de configuración

Esta sección enumera las a365.config.json propiedades y variables de entorno que controlan la configuración de la nube.

Propiedades de a365.config.json

Propiedad Description Obligatorio Default
environment Nombre del entorno de nube. Usa prod, gcc, gcc-high, o dod. Este valor determina qué variables con alcance de entorno lee la CLI y qué configuración de recursos de Observability usa. No prod
authorityHost El host de autoridad OAuth para la nube seleccionada. El valor debe ser un origen HTTPS. No https://login.microsoftonline.com
graphBaseUrl La URL base de Microsoft Graph para la nube seleccionada. El valor debe ser un origen HTTPS. No https://graph.microsoft.com

Variables de entorno

Variable Description
A365_ENVIRONMENT Nombre del entorno de nube. La CLI usa este valor cuando a365.config.json no establece environment, y para comandos que no leen a365.config.json. El valor por defecto es prod.
A365_AUTHORITY_HOST_<ENV> El host de autoridad de OAuth. Este valor tiene prioridad sobre authorityHost en a365.config.json.
A365_GRAPH_BASE_URL_<ENV> La URL base de Microsoft Graph. Este valor tiene prioridad sobre graphBaseUrl en a365.config.json.
A365_DISCOVER_ENDPOINT_<ENV> El endpoint de descubrimiento de Agent 365 Tools. La CLI también utiliza su origen para llamadas de servicio relacionadas con Agent 365.
A365_CREATE_ENDPOINT_<ENV> La URL de registro del endpoint de mensajería.
A365_DELETE_ENDPOINT_<ENV> La URL para eliminar el extremo de mensajería.
A365_MCP_APP_ID_<ENV> El ID de recurso de la aplicación Agent 365 Tools que la CLI utiliza para adquirir tokens para servidores de herramientas. La mayoría de los desarrolladores no necesitan establecer esta variable.

Cómo se deriva el sufijo de entorno

La CLI deriva el <ENV> sufijo de cada variable con alcance de entorno a partir del nombre de tu entorno. La CLI recorta el nombre, sustituye cada carácter que no sea letra o dígito por un guion bajo (_), y lo convierte a mayúsculas. Un nombre vacío se convierte en PROD.

Nombre del entorno Sufijo normalizado Variable de ejemplo
gcc GCC A365_DISCOVER_ENDPOINT_GCC
gcc-high GCC_HIGH A365_GRAPH_BASE_URL_GCC_HIGH
dod DOD A365_AUTHORITY_HOST_DOD

El nombre del entorno y el sufijo de la variable deben resolverse al mismo valor normalizado. Por ejemplo, A365_ENVIRONMENT=gcc-high se empareja con A365_AUTHORITY_HOST_GCC_HIGH.

Permisos de observabilidad

Durante la configuración, la CLI otorga al blueprint del agente el Agent365.Observability.OtelWrite permiso sobre el recurso de Observabilidad del Agente 365 para la nube seleccionada:

Cloud ID de aplicación del recurso de observabilidad
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

Las versiones anteriores de la CLI siempre otorgaban el permiso sobre el recurso comercial de observabilidad. Si configuras un agente en una nube del Gobierno de EE. UU. con una versión anterior, configura el entorno de tu nube y vuelve a ejecutar a365 setup all para que la CLI te conceda el permiso sobre el recurso de Observabilidad de tu nube.

Comprobación de la configuración

Después de configurar una nube, ejecuta un comando de solo lectura y confirma que la CLI usa los endpoints esperados. Por ejemplo:

Solucionar problemas de configuración de la nube

La siguiente tabla enumera los errores comunes de configuración de la nube y cómo resolverlos.

Síntoma Causa Resolution
Authority host must be an HTTPS origin without a path, query, fragment, or user info. (o el mismo error para la URL base de Graph) La URL base del host de autoridad o de Graph incluye una ruta, cadena de consulta o fragmento. Usa un origen HTTPS simple. Por ejemplo, use https://login.microsoftonline.us en lugar de https://login.microsoftonline.us/common/oauth2/v2.0/authorize.
Un error dice que AzureUSGovernment o la nube de CLI de Azure no distingue GCC Moderate (GCC), GCC High y DoD. El entorno es AzureUSGovernment, o la configuración detectó la nube desde la CLI de Azure. Establece el entorno en gcc, gcc-high o dod.
La CLI llama al servicio comercial Agent 365 en una nube del Gobierno de EE. UU. A365_DISCOVER_ENDPOINT_<ENV> no está configurado, o su sufijo no coincide con el nombre del entorno. Configura A365_DISCOVER_ENDPOINT_<ENV> con el sufijo de tu entorno.
La instalación otorga permisos sobre el recurso comercial de observabilidad. El entorno no está establecido, así que la CLI usa prod. Configura el entorno de tu entorno en la nube y vuelve a ejecutar la configuración.
PowerShell fallback is available only for commercial Graph and authority endpoints. El inicio de sesión de Microsoft Graph falló y la CLI no puede recurrir a PowerShell Connect-MgGraph cuando usas endpoints personalizados. Resuelve el fallo al iniciar sesión. Por ejemplo, confirma que has registrado tu aplicación cliente en tu nube y que inicias sesión con una cuenta en el tenant de tu nube.

Contenido relacionado

  • Last updated on