Plano del agente de configuración

El plano del agente define la identidad, los permisos y los requisitos de infraestructura de tu agente. Crea cada instancia de agente a partir de esta plantilla de agente.

Para más información sobre la identidad del Agente 365, consulte Identidad del Agente 365.

Prerrequisitos

Antes de comenzar, asegúrese de que tiene los siguientes requisitos previos:

1. CLI del Agente 365 - Consulta la instalación del CLI del Agente 365.

2. Permisos necesarios:

   • Usuario inquilino válido con uno de los siguientes roles:
     • Administrador global
     • Desarrollador de Identificación de Agente
   • Acceso a una suscripción de Azure con permisos para crear recursos

   Tip

   Los agentes (no los compañeros de equipo de IA) no necesitan un archivo de configuración. Usa a365 setup all --agent-name <name> y la CLI resuelve automáticamente tu inquilino y aplicación cliente. La configuración del compañero de equipo de IA requiere una creación manual a365.config.json.

Crear plano de agente

Utilice el comando a365 setup para crear recursos de Azure y registrar el plano técnico del agente. El plano técnico define los requisitos de identidad, permisos e infraestructura del agente. Este paso establece la base para implementar y ejecutar el agente en Azure.

Ejecución de la configuración

Ejecuta el comando de configuración:

a365 setup -h

El comando tiene varias opciones. Puedes completar toda la configuración en un solo comando usando a365 setup all o eligiendo opciones más detalladas.

Configuración del agente (valor predeterminado):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

configuración de M365 agent (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

Configuración del compañero de equipo de IA:

a365 setup all --aiteammate

Todo el proceso de configuración realiza estas operaciones:

1. Crea Azure infraestructura (si aún no existe):

   • Grupo de recursos
   • Plan de Servicio de Aplicaciones con la SKU especificada
   • Aplicación web de Azure con identidad administrada habilitada

2. Registra el plano técnico del agente:

   • Crea el esquema del agente en tu entidad de Microsoft Entra
   • Crea registros de aplicaciones de Microsoft Entra
   • Configure la identidad del agente con los permisos necesarios
   • Establece managerApplications en el esquema, que es necesario para la gestión de la plataforma.

   Importante

   Los planos técnicos deben tener managerApplications configurado para ser aceptados por la plataforma. La CLI establece esto automáticamente. Si tiene un plano técnico existente creado antes de que se introdujo este requisito, elimínelo y ejecute a365 setup all de nuevo, o bien vuelva a aplicarle una revisión manual a través del Graph API.

3. Configurar permisos de API:

   • Configura los ámbitos de la API de Microsoft Graph
   • Configura los permisos de la API de bot de mensajería
   • Aplica permisos que se pueden heredar para las instancias de agentes

4. Actualizar los archivos de configuración

   • Guarda los IDs y endpoints generados en un nuevo archivo de tu directorio de trabajo llamado a365.generated.config.json
   • Registra la identidad administrada y la información de recursos

Configuración mediante ID de desarrollador de agente

Si ejecutas como Desarrollador de ID de Agente (y no como Administrador Global), a365 setup all completa la mayoría de los pasos automáticamente, pero los otorgamientos de permisos de OAuth2 requieren un paso independiente de un Administrador Global.

Qué pasos se completan automáticamente:

• Infraestructura de Azure (grupo de recursos, plan de App Service, aplicación web)
• Registro del plano técnico del agente
• Permisos heredables para instancias de agente

Qué pasos requieren un administrador global:

• Concesión de permisos delegados de OAuth2 (AllPrincipals consentimiento) para Microsoft Graph, herramientas del agente 365, API de bot de mensajería, API de observabilidad y API de Power Platform

Cómo completar la instalación mediante una cuenta que no sea de administrador:

Ejecución de los comandos:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

Comparta los pasos siguientes impresos por la CLI con el administrador global. Pueden abrir el vínculo proporcionado o la dirección URL de consentimiento para completar las concesiones de OAuth2.

Comprobación de la configuración

Cuando finalice la instalación, verá un resumen que muestra todos los pasos completados. Compruebe los recursos creados:

1. Verificar configuración generada:

   Abra a365.generated.config.json en el directorio de trabajo. O utiliza PowerShell:

   Get-Content a365.generated.config.json | ConvertFrom-Json
   

   La salida esperada incluye estos valores críticos:

   {
   "managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "agentBlueprintClientSecretProtected": true,
   "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
   "resourceConsents": [],
   "completed": true,
   "completedAt": "xxxx-xx-xxTxx:xx:xxZ",
   "cliVersion": "x.x.xx"
   }
   

   Campos clave a verificar:

   Campo	Propósito	Qué comprobar
   managedIdentityPrincipalId	Autenticación de identidad administrada de Azure	Debería ser un GUID válido
   agentBlueprintId	Identificador único de tu agente	Utilizado en el Portal de Desarrolladores y en el centro de administración
   agentBlueprintObjectId	El Microsoft Entra ID de Blueprint
   messagingEndpoint	Enrutamiento de mensajes	Donde Teams/Outlook envían mensajes a tu agente
   agentBlueprintClientSecret	Secreto de autenticación	Debería existir (el valor está enmascarado)
   resourceConsents	Permisos de API	Debe contener recursos como Microsoft Graph, herramientas del agente 365, API de bot de mensajería, API de observabilidad
   completed	Estado de la instalación	Debería ser true

   Nota:

   Si ejecutó la instalación como Administrador de ID de agente o Desarrollador de ID de agente, resourceConsents podría estar vacío y completed podría ser false hasta que un Administrador Global complete las concesiones de permisos de OAuth2 utilizando los pasos siguientes impresos por la CLI.

2. Verifica los recursos de Azure en el Portal de Azure:

   O usa el az resource list comando PowerShell.

   # List all resources in your resource group
   az resource list --resource-group <your-resource-group> --output table
   

   Verifica que se creen los siguientes recursos:

   • Grupo de recursos:

     • Ir a Grupos de Recursos> Selecciona tu grupo de recursos
     • Verifique que contiene su Plan de Servicio de Aplicaciones y Web App

   • Plan de App Service:

     • Vaya a App Services>App Service Plans
     • Busque su plan y verifique que el nivel de precios coincida con su SKU de configuración

   • Aplicación web:

     • Vaya a App Services>Web Apps
     • Busque la aplicación web y, a continuación, vaya a Configuración>Identidad>Sistema asignado
     • Comprobar que el estado es Activado
     • Tenga en cuenta que el identificador de objeto (principal) coincide con managedIdentityPrincipalId

3. Verificar aplicaciones de Microsoft Entra en el Portal de Azure:

   Vaya a Azure Active Directory>Registros de aplicaciones>Todas las aplicaciones:

   • Busque el plano técnico del agente mediante agentBlueprintId

   • Abra la aplicación y seleccione Permisos de API

   • Los permisos de verificación se conceden con marcas verdes:

     • Microsoft Graph (permisos delegados y de aplicación)
     • Permisos de API de bot de mensajería

   • Todos los permisos muestran "Concedido para [Tu Inquilino]"

4. Verificar el archivo de configuración generado creado:

   Debe tener un archivo denominado a365.generated.config.json que contenga todos los datos de configuración.

   Use el comando test-path de PowerShell para comprobar que existe.

   # Check file exists
   Test-Path a365.generated.config.json
   # Should return: True
   

   Importante

   Guarda los archivos a365.config.json y a365.generated.config.json. Necesitas estos valores para el despliegue y la resolución de problemas.

5. Compruebe que la aplicación web tiene habilitada la identidad gestionada:

   Utiliza el az webapp identity show comando para comprobar si la identidad gestionada está habilitada.

   az webapp identity show --name <your-web-app> --resource-group <your-resource-group>
   

   Esperado:

   {
   "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "type": "SystemAssigned"
   }
   

6. Compruebe el plano técnico del agente registrado en Microsoft Entra:

   En el centro de administración de Microsoft Entra, busque su agentBlueprintId o búsquelo por nombre.

   Compruebe que:

   ✅ Aparecen el registro de aplicaciones y la aplicación empresarial
   ✅ En el blueprint de registro de la app, la pestaña de permisos de la API muestra todos los permisos
   ✅ El estado muestra "Concedido para [Tu Arrendatario]"

Para más ayuda, consulta:

• Problemas con aplicaciones cliente personalizadas

Permisos del agente

Para que las aplicaciones y los agentes puedan leer o escribir datos de Microsoft 365 (usuarios, correo, archivos, Teams, agentes, etc.), debe concederles explícitamente permisos de Microsoft Graph. Los permisos de Microsoft Graph son el modelo de autorización que controla a qué datos y acciones puede acceder una aplicación o servicio a través de las API de Microsoft Graph en Microsoft 365 y Microsoft Entra ID.

Más información: Información general sobre los permisos de Microsoft Graph

Para usar los permisos de Graph para las instancias del agente 365, el desarrollador debe declararlos en el plano técnico del agente. Cuando un administrador activa el plano técnico en el Centro de administración de Microsoft 365, el portal revisa los permisos de Graph del plano técnico y pide al administrador que dé su consentimiento.

Para comprender y validar cómo los permisos de Graph habilitan a su agente, puede:

• Vea todos los permisos de Graph que están disponibles.
• Visite el Explorador de Graph para probar las consultas, inspeccionar las respuestas y comprender los permisos.
• Use Microsoft 365 Agents Playground para probar el agente localmente antes de la implementación.

Aplicar permisos a tu plantilla

Use a365 setup permissions custom para aplicar permisos de API personalizados de forma directa a tu plantilla en Microsoft Entra.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

Para obtener información completa sobre cómo configurar y quitar permisos personalizados, consulte setup permissions custom.

Pasos siguientes

Despliega el código de tu agente en la nube:

Solución de problemas

Esta sección describe los problemas comunes al configurar planos de agentes.

Estos problemas a veces se producen durante el registro:

• Error de permisos insuficientes
• Falta de autenticación en CLI de Azure
• El recurso ya existe
• Consentimiento de administrador no completado
• Archivos de configuración ausentes o inválidos
• La instalación se completa pero los recursos no se crean
• Esquema del agente no registrado en Microsoft Entra
• Permisos de API no concedidos
• Identidad gestionada no habilitada
• El programa de instalación tarda demasiado o deja de responder
• Limpieza de un agente sin configuración
• No se puede enviar el primer mensaje en Teams

Error de permisos insuficientes

Síntoma: Error de permisos insuficientes durante a365 setup la ejecución de comandos .

Necesita uno de los siguientes roles en su entorno de Microsoft Entra:

• Administrador global
• Desarrollador de Identificación de Agente

Y acceso como colaborador o propietario de una suscripción a Azure.

Solución: Compruebe que tiene permisos necesarios en Microsoft Entra.

• Vaya a: Centro de administración Microsoft Entra> Su perfil > Roles asignados
• Comprobación del acceso a la suscripción de Azure mediante el az account show comando de PowerShell

Falta autenticación de CLI de Azure

Síntoma: La configuración falla con errores de autenticación.

Solución: Asegúrese de que está conectado a Azure y compruebe su cuenta y suscripción.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

El recurso ya existe

Síntoma: La configuración falla con un error para el grupo de recursos, el plan de servicio de aplicaciones o la aplicación web.

Soluciones: Elija una de las siguientes soluciones.

• Uso de los recursos existentes

  Si existen recursos y quieres usarlos, asegúrate de que coincidan con tu configuración. Usa el az resource list comando PowerShell.

  az resource list --resource-group <your-resource-group>
  

• Eliminar recursos en conflicto

  Elimine el grupo de recursos o cambie el nombre de los recursos en a365.config.json y vuelva a ejecutar la configuración.

  Use el az group delete comando de PowerShell para eliminar un grupo de recursos.

  # WARNING: This command deletes all resources in it
  az group delete --name <your-resource-group>
  

• Usa el comando de limpieza para empezar de cero

  Use el comando cleanup para quitar todos los recursos del Agente 365, luego use el comando a365 setup all para rehacer la configuración.

  Advertencia

  La ejecución a365 cleanup es destructiva.

  a365 cleanup
  a365 setup all
  

Consentimiento de administrador no completado

Síntoma: Ha abierto las ventanas del explorador durante la instalación, pero las cerró sin completar el consentimiento o la configuración completada, pero las concesiones de permisos de OAuth2 siguen pendientes.

Solución: Elija en función de su rol:

• Administrador global: Vuelva a ejecutar a365 setup all. La CLI solicita el consentimiento del administrador. Complete el flujo de consentimiento en la ventana del explorador que aparece.

• Administrador de ID de agente o desarrollador: no se pueden completar las concesiones de OAuth2 directamente. Ejecutar a365 setup all : el resumen de instalación imprime los pasos siguientes para un administrador global, incluido un vínculo directo o una dirección URL de consentimiento para completar las concesiones. Comparta esos detalles con el administrador global.

Archivos de configuración ausentes o inválidos

Síntoma: La configuración falla con errores de "Configuración no encontrada" o validación.

Solution:

1. Verifica que el a365.config.json archivo exista.
2. Si falta o no es válido, créelo manualmente o use a365 setup all --agent-name <name> (solo agentes).

# Verify a365.config.json exists
Test-Path a365.config.json

La instalación se completa pero los recursos no se crean

Symptom: comando setup se realiza correctamente, pero no existen Azure recursos.

Solution:

1. Para comprobar los recursos creados, abra a365.generated.config.json en el directorio de trabajo.
2. Compruebe que existen recursos Azure mediante el comando az resource list.
3. Si faltan recursos, compruebe si hay errores en la salida de instalación y vuelva a ejecutar la instalación mediante el a365 setup all comando .

# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Modelo de agente no registrado en Microsoft Entra

Síntoma: El programa de instalación se completa, pero no se encuentra la plantilla de agente en el centro de administración de Microsoft Entra.

Solution:

1. Obtenga el identificador de plano técnico de a365.generated.config.json.

   Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId
   

2. Busque en el centro de administración de Microsoft Entra:

   1. Vaya a: Centro de administración de Microsoft Entra.
   2. Vaya a Registros de aplicaciones>Todas las aplicaciones.
   3. Busca tu agentBlueprintId.

3. Si no se encuentra, vuelva a ejecutar la instalación mediante el a365 setup all comando .

   a365 setup all
   

Permisos de API no concedidos

Síntoma: El programa de instalación se completa, pero los permisos se muestran como "No concedidos" en Microsoft Entra.

Solution:

1. Abra Centro de administración Microsoft Entra.

2. Busque el registro de la aplicación de plano técnico del agente.

3. Vaya a Permisos de API.

4. Conceder consentimiento administrativo:

   1. Seleccione Conceder consentimiento administrativo para [Tu Inquilino].
   2. Confirme la acción.

5. Compruebe que todos los permisos muestren marcas de verificación verdes.

Identidad administrada no activada

Síntoma: La aplicación web existe, pero la identidad administrada no está habilitada.

Solution:

1. Compruebe el estado de la identidad administrada mediante el az webapp identity show comando .
2. Si no está habilitado, habilite manualmente mediante el az webapp identity assign comando .
3. Compruebe que está habilitado mediante el az webapp identity show comando .

# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

El programa de instalación tarda demasiado o deja de responder

Síntoma: El comando de configuración dura más de 10 minutos sin completarse.

Solution:

1. Si se ejecuta como administrador global, compruebe si una ventana del explorador está esperando el consentimiento del administrador. Complete el flujo de consentimiento para desbloquear la configuración.

2. Si la configuración deja de responder, cancélela (Ctrl+C) y verifique lo que se ha creado.

   # Check generated config
   Get-Content a365.generated.config.json | ConvertFrom-Json
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. Limpie y vuelva a intentarlo.

   a365 cleanup
   a365 setup all
   

Limpiar un agente sin configuración

Síntoma: Ha aprovisionado un agente con a365 setup all --agent-name <name> y ahora quiere quitarlo, pero no tiene un a365.config.json archivo.

Solución: Use a365 cleanup --agent-name para quitar el agente sin un archivo de configuración. La CLI lee los identificadores de recursos del archivo de configuración global generado que se escribió durante la configuración inicial de arranque.

a365 cleanup --agent-name <your-agent-name>

Si ya no tiene la configuración generada globalmente (por ejemplo, después de reinstalar la CLI), use a365 cleanup con un a365.config.json mínimo creado manualmente o elimine los recursos directamente a través de Azure Portal y centro de administración de Microsoft Entra.

No se puede enviar el primer mensaje en Teams

Síntoma: Después de aprovisionar una instancia del agente, no puede enviar un mensaje al administrador del agente como mensaje de bienvenida.

Solución: El permiso [Chat.Create][perm-chatcreate] es necesario para crear un nuevo objeto de chat. Si ya existe un chat uno a uno, esta operación devuelve el chat existente y no crea uno nuevo.

• Para implementarlo, configure los permisos heredables del plano técnico para incluir el Chat.Create ámbito.
• Configure un mensaje de chat de Teams para enviar una vez que se aprovisione una instancia del agente.
• Cree una nueva instancia del agente desde el plano técnico y pruebe el mensaje de primera ejecución.