Referencia de comandos de la CLI setup del agente 365

Configure el entorno del Agente 365 con control pormenorizado sobre cada paso. Este comando administra el flujo de trabajo de instalación inicial para los planos técnicos del Agente 365.

rol Minimum requerido: Azure Colaborador + Agent ID Developer

Note

El rol que contiene determina la cantidad de la configuración que se completa en una sola ejecución. El administrador global puede completar todos los pasos a la vez. El Administrador del ID del Agente y el Desarrollador del ID del Agente pueden completar todos los pasos excepto la concesión de permisos de OAuth2 (consentimiento del administrador), que requieren la acción de un Administrador Global. Cuando la configuración termina, la CLI imprime los siguientes pasos para el Administrador Global directamente en la salida.

Syntax

a365 setup [command] [options]

Options

Option	Description
-?, , -h, --help	Mostrar información de ayuda y uso.

Orden de ejecución recomendado

# 0. Check prerequisites (optional)
a365 setup requirements

# 1. Create blueprint
a365 setup blueprint

# 2. Configure MCP permissions
a365 setup permissions mcp

# 3. Configure bot permissions
a365 setup permissions bot

# 4. Configure CopilotStudio permissions (if needed)
a365 setup permissions copilotstudio

# 5. Configure custom permissions (if needed)
a365 setup permissions custom

O bien, ejecute todos los pasos a la vez:

# Full setup using config file (a365.config.json)
a365 setup all

# Config-free: no a365.config.json needed
a365 setup all --agent-name "MyAgent"

Si se ejecuta como Administrador de ID de agente o Desarrollador de ID de agente (no Administrador Global), a365 setup all completa todos los pasos, excepto los otorgamientos de permisos de OAuth2. Cuando termina, el resultado incluye los siguientes pasos para que un Administrador Global complete las subvenciones — incluyendo un enlace directo o una URL de consentimiento que puedan abrir.

setup requirements

Valide los requisitos previos para la configuración del Agente 365. Ejecuta comprobaciones de requisitos modulares y proporciona instrucciones para cualquier problema que encuentre.

a365 setup requirements [options]

Este comando ejecuta los pasos siguientes:

• Comprueba todos los requisitos previos necesarios para la configuración del Agente 365.
• Informa de cualquier problema con instrucciones de resolución detalladas.
• Continúa comprobando todos los requisitos incluso si se produce un error en algunas comprobaciones.
• Proporciona un resumen de todas las comprobaciones al final.

Tip

Si eres Administrador Global y la Agent 365 CLI conocida aplicación cliente no aparece en tu tenant, setup requirements te pide que la crees automáticamente. Introduce un ID de aplicación existente o escribe C para crear la app y concede el consentimiento del administrador en un solo paso, sin necesidad de registro manual en Entra.

requirements Opciones

Option	Description
-v, --verbose	Habilite el registro detallado.
--category <category>	Haz comprobaciones solo para una categoría específica, como Azure, Authentication, PowerShell o Tenant Enrollment.
-?, , -h, --help	Mostrar información de ayuda y uso.

Note

setup requirements No requiere un archivo de configuración: ejecútalo en cualquier directorio.

setup blueprint

Cree un plano técnico del agente (Entra ID registro de aplicaciones).

Permisos mínimos necesarios: rol de desarrollador de id. de agente

a365 setup blueprint [options]

blueprint Opciones

Option	Description
-n, --agent-name <name>	Nombre de la base del agente. Cuando proporcionas esta opción, no necesitas un archivo de configuración. El comando detecta automáticamente el ID de inquilino de az account show. Anula con --tenant-id.
--tenant-id <tenantId>	Identificador de inquilino de Azure AD. Overrides auto-detection. Se usa con --agent-name.
-v, --verbose	Mostrar la salida detallada.
--dry-run	Mostrar lo que haría el comando sin ejecutarlo.
--skip-requirements	Omitir la comprobación de validación de requisitos. Úselo con precaución.
--no-endpoint	No registre el punto de conexión de mensajería (solo plano técnico).
--endpoint-only	Registre solo el punto de conexión de mensajería. Requiere un plano técnico existente.
--update-endpoint <url>	Elimina el endpoint de mensajería existente y registra uno nuevo con la URL especificada.
--m365	Trata a este agente como un agente M365. Registra el punto final de mensajería a través de la plataforma MCP. Por defecto es false (opt-in).
-?, , -h, --help	Mostrar información de ayuda y uso.

setup permissions

Configure las concesiones de permisos de OAuth2 y los permisos heredables.

Permisos mínimos necesarios: Administrador global

a365 setup permissions [command] [options]

Options

Option	Description
-?, , -h, --help	Mostrar información de ayuda y uso.

Subcommands

Subcommand	Description
mcp	Configurar el servidor MCP OAuth2 concede y permisos heredables.
bot	Configure Messaging Bot API OAuth2 concede y permisos herebles.
custom	Aplica permisos de API personalizados al plano técnico del agente que van más allá de los permisos estándar necesarios para la operación del agente.
copilotstudio	Configura los permisos de OAuth2 y los permisos heredables para que el plano técnico del agente invoque Copilot Studio copilots a través de Power Platform API.

setup permissions mcp

Configurar el servidor MCP OAuth2 concede y permisos heredables.

Permisos mínimos necesarios: Administrador global

a365 setup permissions mcp [options]

This command:

• ToolingManifest.json Lee del deploymentProjectPath especificado en a365.config.json.
• Concede permisos delegados de OAuth2 para cada ámbito de servidor MCP al plano técnico del agente.
• Configura los permisos heredables para que las instancias del agente puedan acceder a las herramientas de MCP.
• Es idempotente y seguro para ejecutarse varias veces.

Important

• Antes de ejecutar este comando, verifica que apunta deploymentProjectPath a la carpeta del proyecto que contiene el archivo actualizado ToolingManifest.jsonde . Si el desarrollador agrega servidores MCP en otra máquina, comparta primero el actualizado ToolingManifest.json con el administrador global. La ejecución sin el correcto ToolingManifest.json no agrega los nuevos permisos de servidor MCP al plano técnico.
• Ejecute este comando después de que el desarrollador ejecute a365 develop add-mcp-servers. La adición de servidores MCP al manifiesto y la concesión de permisos al plano técnico son dos pasos independientes. Una vez completado este comando, los permisos del servidor MCP están visibles en el plano técnico del agente.

permissions mcp Opciones

Option	Description
-n, --agent-name <name>	Nombre de la base del agente. Cuando proporcionas esta opción, no necesitas un archivo de configuración.
--tenant-id <tenantId>	Identificador de inquilino de Azure AD. Overrides auto-detection. Se usa con --agent-name.
-v, --verbose	Mostrar la salida detallada.
--dry-run	Mostrar lo que haría el comando sin ejecutarlo.
--remove-legacy-scopes	Quita los ámbitos compartidos heredados (McpServers.*.All formato) del plano técnico después de migrar a permisos por servidor (Tools.ListInvoke.All). Solo úsalo después de que el SDK V2 esté confirmado en activo: los agentes en el SDK V1 pierden el acceso a la herramienta si se eliminan prematuramente.
-?, , -h, --help	Mostrar información de ayuda y uso.

Migración a permisos MCP por servidor

Use --remove-legacy-scopes al migrar desde el modelo de permisos compartidos heredados a permisos por servidor:

• Modelo compartido heredado: un identificador de aplicación de recurso único (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) con ámbitos compartidos, como McpServers.Mail.All y McpServers.Teams.All.
• Modelo por servidor: cada servidor MCP tiene su propio identificador de aplicación con el ámbito Tools.ListInvoke.All.

En el ejemplo siguiente se muestra cómo aparecen los permisos por servidor en el Centro de administración Microsoft Entra después de aplicar el plano técnico. Cada servidor MCP, como Work IQ Calendar MCP y Work IQ Mail MCP, tiene su propio ámbito delegado Tools.ListInvoke.All . Un ámbito compartido McpServersMetadata.Read.All proporciona acceso a los metadatos del servidor MCP.

setup permissions bot

Configure Messaging Bot API OAuth2 concede y permisos herebles.

Permisos mínimos necesarios: Administrador global

Requisitos previos: permisos de plano técnico y MCP (ejecute a365 setup permissions mcp primero)

a365 setup permissions bot [options]

permissions bot Opciones

Option	Description
-n, --agent-name <name>	Nombre de la base del agente. Cuando proporcionas esta opción, no necesitas un archivo de configuración.
--tenant-id <tenantId>	Identificador de inquilino de Azure AD. Overrides auto-detection. Se usa con --agent-name.
-v, --verbose	Mostrar la salida detallada.
--dry-run	Mostrar lo que haría el comando sin ejecutarlo.
-?, , -h, --help	Mostrar información de ayuda y uso.

setup permissions custom

Aplica permisos de API personalizados al plano técnico del agente que van más allá de los permisos estándar necesarios para la operación del agente. Mediante este comando, concede al agente acceso a ámbitos de Microsoft Graph adicionales, como Presencia, Archivos y Chat, o a api personalizadas registradas en el inquilino de Microsoft Entra ID de la organización.

Permisos mínimos necesarios: Administrador global

Requisitos previos: ejecute a365 setup blueprint primero.

a365 setup permissions custom [options]

This command:

• Configura las concesiones de permisos delegados de OAuth2 con el consentimiento del administrador para cada recurso configurado.
• Establece permisos heredables para que los usuarios del agente puedan heredar el acceso del plano técnico.
• Reconcilia Microsoft Entra con la configuración actual agregando nuevos permisos y quitando los permisos eliminados de la configuración.
• Es idempotente y seguro para ejecutarse varias veces.

permissions custom Opciones

Option	Description
-n, --agent-name <name>	Nombre de la base del agente. Cuando proporcionas esta opción, no necesitas un archivo de configuración.
--tenant-id <tenantId>	Identificador de inquilino de Azure AD. Overrides auto-detection. Se usa con --agent-name.
-v, --verbose	Mostrar la salida detallada.
--dry-run	Mostrar lo que haría el comando sin ejecutarlo.
--resource-app-id <guid>	ID de aplicación de recurso (GUID) para un permiso personalizado en línea. Se usa con --scopes.
--scopes <scopes>	Ámbitos delegados separados por comas para el permiso personalizado en línea. Se usa con --resource-app-id.
-?, , -h, --help	Mostrar información de ayuda y uso.

Configurar permisos personalizados en línea

Usar --resource-app-id y --scopes aplicar permisos personalizados directamente sin editar a365.config.json:

# Add Microsoft Graph extended permissions
a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Presence.ReadWrite,Files.Read.All,Chat.Read

# Add custom API permissions
a365 setup permissions custom `
  --resource-app-id <your-api-app-id> `
  --scopes CustomScope.Read,CustomScope.Write

El nombre del recurso se resuelve automáticamente desde Microsoft Entra. No necesitas especificarlo.

Configurar permisos personalizados mediante archivo de configuración

Alternativamente, añadir customBlueprintPermissions a a365.config.json y ejecutar el comando sin banderas en línea:

a365 setup permissions custom

Este comando concilia Microsoft Entra con los permisos configurados: añade nuevos permisos y elimina cualquier permiso que hayas eliminado de la configuración.

Integración con setup all

Cuando la configuración incluye permisos personalizados, la ejecución a365 setup all las configura automáticamente como parte de una sola fase de permisos por lotes. El orden de instalación completo es:

1. Blueprint
2. Lote de permisos (MCP, Bot API, Permisos de plano técnico personalizados, todos configurados juntos)

setup permissions copilotstudio

Configura los permisos de OAuth2 y los permisos heredables para que el plano técnico del agente invoque Copilot Studio copilots a través de Power Platform API.

Permisos mínimos necesarios: Administrador global

Requisitos previos: ejecute a365 setup blueprint primero.

a365 setup permissions copilotstudio [options]

This command:

• Garantiza que la entidad de servicio de Power Platform API existe en el inquilino.
• Crea una concesión de permisos de OAuth2 desde el plano técnico a Power Platform API con el CopilotStudio.Copilots.Invoke ámbito.
• Establece permisos heredables para que las instancias del agente puedan invocar Copilot Studio copilots.

permissions copilotstudio Opciones

Option	Description
-n, --agent-name <name>	Nombre de la base del agente. Cuando proporcionas esta opción, no necesitas un archivo de configuración.
--tenant-id <tenantId>	Identificador de inquilino de Azure AD. Overrides auto-detection. Se usa con --agent-name.
-v, --verbose	Mostrar la salida detallada.
--dry-run	Mostrar lo que haría el comando sin ejecutarlo.
-?, , -h, --help	Mostrar información de ayuda y uso.

Use este comando cuando el agente necesite invocar Copilot Studio copilots en tiempo de ejecución o llame a las API de Power Platform que requieren permisos de CopilotStudio.

setup all

Realice todos los pasos de configuración para configurar el entorno del Agente 365.

a365 setup all [options]

Ejecuta la configuración completa del Agente 365, todos los pasos en secuencia.

Incluye: Plano técnico y permisos.

Los pasos que se completen dependen de su rol:

Step	Global Administrator	Administrador de ID de Agente	Desarrollador de Identificación de Agente
Prerequisites check	Yes	Yes	Yes
Creación del plano técnico del agente	Yes	Yes	Yes
Permisos heredables (solo compañeros de equipo con IA)	Yes	Yes	Yes
Concesiones de permisos de OAuth2 (consentimiento del administrador)	Yes	Requiere el paso de disponibilidad general	Requiere el paso de disponibilidad general
Otorgamientos de identidad del agente (--authmode s2s o both)	Yes	Yes	PowerShell fallback

Cuando se ejecuta a365 setup all sin administrador global, la CLI:

1. Completa todos los pasos que puede (creación de planos técnicos y permisos heredables).
2. Genera direcciones URL de consentimiento del administrador por recurso y las a365.generated.config.jsonguarda en .
3. Muestra los siguientes pasos en la salida para que un Administrador Global complete las concesiones OAuth2, incluyendo un enlace directo o una URL de consentimiento.

Tip

Si es administrador global, a365 setup all completa todo en una sola ejecución sin necesidad de entrega.

Permisos mínimos requeridos:

• Rol desarrollador de id. de agente (para la creación del plano técnico)
• Global Administrator (para permisos de OAuth2 - si no está disponible, la CLI imprime los siguientes pasos en la salida)
• Administrador de ID de Agente, Administrador de Aplicaciones o Administrador Global (para concesiones de identidad de agente S2S (Servidor a Servidor) - --authmode s2s o both; si no está disponible, la CLI imprime un respaldo de PowerShell en el resumen de configuración)

setup all Opciones

Option	Description
-v, --verbose	Mostrar la salida detallada.
--dry-run	Mostrar lo que haría el comando sin ejecutarlo.
--skip-requirements	Omitir la comprobación de validación de requisitos. Use con precaución: es posible que se produzca un error en la configuración si no se cumplen los requisitos previos.
--aiteammate	Utiliza este parámetro para dirigir al flujo de agentes de equipo de IA a proporcionar solo blueprint y permisos. Sin este parámetro, el flujo de agentes blueprint crea automáticamente el principal de servicio de identidad del agente sin un usuario de Entra. Este parámetro anula el aiteammate campo en a365.config.json.
--authmode <mode>	Patrón de autenticación para la concesión de permisos de identidad de agente (solo agentes blueprint). obo (por defecto) — subvenciones delegadas con alcance de principal, sin necesidad de rol administrativo. s2s — asignaciones de roles de aplicación en el SP de identidad del agente, requieren Administrador de ID de Agente, Administrador de Aplicaciones o Administrador Global; Respaldo de PowerShell impreso si el rol está ausente. both — aplica subvenciones OBO (On-Behalf-Of) y S2S. No está soportado con --aiteammate. También puede establecerse como authMode en a365.config.json.
--agent-registration-only	Salta los pasos de blueprint y permisos y solo ejecuta el registro del agente. Use para reintentar un paso de registro con errores.
--m365	Trata a este agente como un agente M365. Registra el punto final de mensajería a través de la plataforma MCP. Por defecto es false (opt-in).
-n, --agent-name <name>	Nombre base del agente (por ejemplo, "MyAgent"). Cuando se proporciona, no se requiere ningún archivo de configuración. Deriva nombres para mostrar como "<name> Identity" y "<name> Blueprint". TenantId se detecta automáticamente desde az account show (invalida con --tenant-id). ClientAppId se resuelve buscando Agent 365 CLI en el inquilino.
--tenant-id <tenantId>	Identificador de inquilino de Azure AD. Invalida la detección automática de az account show. Úselo con --agent-name cuando se ejecuta en un entorno no interactivo o para tener como destino un inquilino específico.
-?, , -h, --help	Mostrar información de ayuda y uso.

Agent setup

Por defecto, a365 setup all ejecuta el flujo del agente blueprint. Este flujo crea un agente sin una dependencia de equipo de Dataverse o ai. Funciona para agentes que se comunican directamente con la plataforma Agent 365.

# Default: uses a365.config.json
a365 setup all

# Or explicitly (same result)
a365 setup all --aiteammate false

Para ejecutar el flujo de agentes de compañeros de IA, pasa --aiteammate.

Este flujo realiza los pasos siguientes en secuencia:

1. Requirements validation: comprueba Azure roles y requisitos previos.
2. Blueprint creation: crea o reutiliza la aplicación de plano técnico del agente de Entra ID.
3. permisos Batch: configura concesiones de permisos delegados en el plano técnico para Microsoft Graph, herramientas del agente 365, API de bot de mensajería, API de observabilidad, Power Platform y cualquier recurso personalizado.
4. Agent Identity creation : crea una identidad del agente en Entra ID a través del Graph API De identidad del agente.
5. Registro del agente : registra el agente a través de la API de registro del agente AgentX V2.
6. Sincronización de configuración: escribe la configuración de conexión en tiempo de ejecución y la configuración de observabilidad en los archivos del proyecto (appsettings.json, .env).

Note

La configuración del agente requiere seis permisos adicionales de API beta en la aplicación cliente personalizada: , , , , y AgentIdentityBlueprint.AddRemoveCreds.AllAgentIdentityBlueprint.DeleteRestore.All. AgentInstance.ReadWrite.AllAgentIdentity.ReadWrite.AllAgentIdentity.Create.AllAgentIdentity.DeleteRestore.All Consulte Registro de aplicaciones cliente personalizadas para obtener la lista completa.

Configuración sin configuración con --agent-name

Si no tiene un a365.config.json archivo, use --agent-name para ejecutar el programa de instalación sin uno. La CLI detecta automáticamente el inquilino y resuelve la aplicación cliente mediante la búsqueda del registro de aplicaciones conocido Agent 365 CLI en el inquilino.

# Preview what would happen (no changes made)
a365 setup all --agent-name "MyAgent" --dry-run

# Run the full setup
a365 setup all --agent-name "MyAgent"

Cuando se usa --agent-name:

• TenantId se detecta automáticamente desde az account show. Pase --tenant-id a invalidar.
• ClientAppId se resuelve buscando una aplicación Entra denominada Agent 365 CLI en el inquilino. Si no se encuentra, la CLI se cierra con un error. Consulte Registro de aplicaciones cliente personalizado para obtener información sobre cómo registrar esta aplicación.
• Los nombres para mostrar se derivan como "<name> Agent" (identidad) y "<name> Blueprint" (plano técnico).
• La infraestructura siempre se omite (se asume el hospedaje externo).
• Se omite la sincronización de configuración (escrituraappsettings.json), ya que no hay ninguna ruta de acceso del proyecto configurada.

Consentimiento del administrador durante la instalación

Si la aplicación cliente no tiene AllPrincipals el consentimiento del administrador para los permisos necesarios, la CLI detecta esto y le pide que conceda consentimiento de forma interactiva:

The following permissions require admin consent:
  AgentIdentity.ReadWrite.All
  AgentIdentity.Create.All
  ...
Grant admin consent for these permissions now? [y/N]:

Escriba y para conceder consentimiento en línea. Si no eres Administrador Global, rechaza — la CLI muestra los siguientes pasos para un Administrador Global en el resumen de configuración.

Concesiones de identidad del agente (--authmode)

Por defecto, a365 setup all crea concesiones delegadas con alcance principal en el principal de servicio de identidad del agente (obo modo). Estas subvenciones no requieren un rol administrativo.

Uso --authmode para controlar el tipo de subvención:

Value	Behavior	Minimum role
obo (valor predeterminado)	Subvenciones delegadas con alcance principal en la identidad del agente SP	Ninguno (ningún usuario autenticado)
s2s	Asignaciones de roles de aplicación en el SP de identidad del agente	Administrador de ID de Agente, Administrador de Aplicaciones o Administrador Global
both	Tanto subvenciones delegadas por OBO como asignaciones de roles en aplicaciones S2S	Rol en S2S (arriba) para la parte S2S

# Default — OBO delegated grants (no admin role needed)
a365 setup all

# S2S app role assignments
a365 setup all --authmode s2s

# Both OBO and S2S
a365 setup all --authmode both

Cuando el usuario iniciado sesión no cumple el rol requerido para las subvenciones S2S, la CLI imprime un bloque de respaldo de PowerShell en el resumen de configuración. Un administrador puede ejecutarlo para completar las tareas.

Configura authModea365.config.json que se aplica en cada partida sin la bandera:

{
  "authMode": "s2s"
}

Note

--authmode no se admite con --aiteammate. Los agentes compañeros de IA usan OBO automáticamente a través de la identidad del usuario agente.

Config sync

Después de una ejecución correcta, la CLI escribe automáticamente la configuración del entorno de ejecución en los archivos del proyecto:

Setting	Written to	Description
Connections.ServiceConnection	appsettings.json / .env	Identificador de cliente del plano técnico, secreto de cliente, identificador de inquilino y punto de conexión de token
Agent365Observability	appsettings.json / .env	Id. de agente (identidad del agente), identificador de plano técnico, identificador de inquilino, identificador de cliente y secreto de cliente para la exportación de telemetría
TokenValidation	appsettings.json	Configuración de validación de tokens (deshabilitada de forma predeterminada para no DW)
ConnectionsMap	appsettings.json / .env	Dirección URL de servicio predeterminada a la asignación de conexiones

La CLI crea el archivo si no existe y actualiza campos individuales sin sobrescribir el resto de la configuración.

Reintentar un registro con errores

Si la configuración completa el plano técnico y los permisos correctamente, pero se produce un error durante el registro del agente, use --agent-registration-only para reintentar solo ese paso sin repetir el trabajo anterior:

a365 setup all --agent-registration-only