Esquema del agente de configuración

El plano técnico del agente define los requisitos de identidad, permisos e infraestructura del agente. Cree cada instancia de agente a partir de este plano técnico de agente.

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

Requisitos previos

Asegúrese de que dispone de los siguientes requisitos previos:

1. CLI de Agent 365: consulte Instalación de la CLI de Agent 365.

2. Permisos necesarios:

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

   Sugerencia

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

Crear el plano del agente

Use el comando a365 setup para crear recursos de Azure y registrar su plano de 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

Ejecute el comando de configuración:

a365 setup -h

El comando tiene varias opciones. Puede completar toda la configuración en un solo comando usando a365 setup all o elegir opciones más granulares.

Configuración del agente (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 agente M365 (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 instalación realiza estas operaciones:

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

   • Grupo de recursos
   • Plan de App Service con la SKU especificada
   • Azure Web App con la identidad administrada habilitada

2. Registre el plano técnico del agente:

   • Crea el plano técnico del agente en el inquilino de Microsoft Entra
   • Crear registros de aplicación de Microsoft Entra
   • Configure la identidad del agente con los permisos necesarios
   • Establece managerApplications en el plano técnico, lo cual es requerido para la gestión de la plataforma

   Importante

   Los planos técnicos deben tener managerApplications establecido para ser aceptados por la plataforma. La CLI lo configura automáticamente. Si tiene un plano técnico ya creado antes de que se introdujera este requisito, elimínelo y ejecute a365 setup all de nuevo, o parchee manualmente a través de la API de Graph.

3. Configurar permisos de API:

   • Configuración de ámbitos de Microsoft Graph API
   • Configura los permisos de la API de bot de mensajería
   • Aplica permisos heredables para las instancias del agente

4. Actualizar los archivos de configuración

   • Guarda los Id. generados y los puntos de conexión en un nuevo archivo en su 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 ejecuta como Desarrollador de Id. de agente (no administrador global), a365 setup all completa automáticamente la mayoría de pasos, pero el permiso de OAuth2 concede un paso de Administrador global independiente.

Pasos que 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 las instancias del agente

Qué pasos requieren un Administrador global:

• Concesión de permisos delegados de OAuth2 (AllPrincipals consentimiento) para Microsoft Graph, Herramientas de Agent 365, Bot de Mensajería API, Observabilidad API y Power Platform API

Cómo completar la configuración usando una cuenta que no es administrador:

Ejecutar 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 siguientes pasos mostrados por la CLI con su Administrador global. Abra el vínculo proporcionado o la URL de consentimiento para completar la concesión de permisos OAuth2.

Comprobación de la configuración

Cuando finalice la configuración, se mostrará un resumen que indica todos los pasos completados. Compruebe los recursos creados:

1. Verificar la configuración generada:

   Abra a365.generated.config.json en su directorio de trabajo. O use 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	Finalidad	Elementos que se deben comprobar
   managedIdentityPrincipalId	Autenticación mediante identidades gestionadas de Azure	Debe ser un GUID válido
   agentBlueprintId	El identificador único de su agente	Utilizado en el Portal de desarrolladores y en el centro de administración
   agentBlueprintObjectId	Blueprint de Microsoft Entra ID
   messagingEndpoint	Enrutamiento de mensajes	Donde Teams/Outlook envían mensajes a su agente
   agentBlueprintClientSecret	Secreto de autenticación	Debe existir (el valor está oculto)
   resourceConsents	Permisos de API	Debe contener recursos como Microsoft Graph, Agent 365 Tools, API de bots de mensajería, API de observabilidad
   completed	Estado de configuración	Debe ser true

   Nota

   Si ejecutó el programa de 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 de permisos de OAuth2 impresas por la CLI.

2. Verificar los recursos de Azure en Azure Portal:

   O Utilice el comando de PowerShell az resource list.

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

   Compruebe que se han creado los siguientes recursos:

   • Grupo de recursos:

     • Vaya a Grupos de recursos> Seleccione su grupo de recursos
     • Compruebe que contiene el plan de App Service y la aplicación web

   • Plan de App Service:

     • Vaya a App Services>Planes de App Service
     • Busque el plan y compruebe que el plan de tarifa coincide con la 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 (entidad de seguridad) coincide con managedIdentityPrincipalId

3. Compruebe las aplicaciones de Microsoft Entra en Azure Portal:

   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

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

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

   • Todos los permisos muestran "Concedido para [su inquilino]"

4. Verificar el archivo de configuración generado:

   Debe tener un archivo llamado a365.generated.config.json que contiene toda la información de configuración.

   Utilice el comando de PowerShell Test-Path para verificar que existe.

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

   Importante

   Guarde los archivos a365.config.json y a365.generated.config.json. Necesita estos valores para la implementación y la resolución de problemas.

5. Comprobar que la aplicación web tiene habilitada la identidad administrada:

   Use 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. Verifique el plano del agente registrado en Microsoft Entra:

   En el Centro de administración Microsoft Entra, busque su agentBlueprintId o busque por nombre.

   Compruebe lo siguiente:

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

Para obtener más ayuda, consulte:

• Problemas con aplicaciones cliente personalizadas

Permisos del agente

Antes de que las aplicaciones y agentes puedan leer o escribir datos de Microsoft 365 (usuarios, correo, archivos, Teams, agentes y demás), 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 tener acceso una aplicación o servicio a través de las API de Microsoft Graph en Microsoft 365 y Microsoft Entra ID.

Para obtener más información: Descripción general de los permisos de Microsoft Graph

Para usar permisos de Graph para instancias de agente de Agent 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 Microsoft Graph del plano técnico y solicita al administrador que otorgue su consentimiento para ellos.

Para comprender y comprobar cómo los permisos de Graph facilitan el trabajo de su agente, puede:

• Ver todos los permisos de Graph disponibles.
• Visite Graph Explorer para realizar consultas de prueba, inspeccionar respuestas y comprender los permisos.
• Use Microsoft 365 Agents Playground para probar su agente localmente antes de la implementación.

Aplicar permisos a su plano técnico

Utilice a365 setup permissions custom para aplicar permisos personalizados de API directamente en su plano técnico 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 información completa sobre cómo configurar y eliminar permisos personalizados, consulte setup permissions custom.

Pasos siguientes

Implemente el código de su agente en la nube:

Solución de problemas

Esta sección describe los problemas comunes durante la configuración de planos técnicos de agentes.

Estos problemas a veces ocurren durante el registro:

• Error de permisos insuficientes
• No se ha autenticado en CLI de Azure
• El recurso ya existe
• El consentimiento de administrador no se completó
• Faltan los archivos de configuración o no son válidos
• La configuración finaliza pero los recursos no se crean
• El plano técnico del agente no está registrado en Microsoft Entra
• Permisos de API no concedidos
• Identidad administrada no habilitada
• La configuración tarda demasiado o deja de responder
• Limpiar un agente sin configuración
• No se puede enviar el primer mensaje en Teams

Error de permisos insuficientes

Síntoma: Error por permisos insuficientes durante la ejecución del a365 setupcomando.

Debe disponer de uno de los siguientes roles en su inquilino de Microsoft Entra:

• Administrador global
• Desarrollador de id. de agente

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

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

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

No se ha autenticado en CLI de Azure

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

Solución: Asegúrese de estar conectado a Azure y verifique 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 Resource already exists para el grupo de recursos, plan de App Service o aplicación web.

Soluciones: Elija una de las siguientes soluciones.

• Usar recursos existentes

  Si existen recursos y quiere usarlos, asegúrese de que coincidan con su configuración. Utilice el comando az resource list de PowerShell.

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

• Eliminar recursos en conflicto

  Elimine el grupo de recursos o renombre sus recursos en a365.config.json y vuelva a ejecutar la configuración.

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

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

• Usar el comando de limpieza para empezar de cero

  Use el cleanup comando para eliminar todos los recursos de Agent 365, luego use el a365 setup all comando para volver a ejecutar la configuración.

  Advertencia

  Ejecutar a365 cleanup es destructivo.

  a365 cleanup
  a365 setup all
  

El consentimiento de administrador no se completó

Síntoma: Ha abierto ventanas del navegador durante la configuración pero las ha cerrado sin completar el consentimiento, o la configuración se completó pero los permisos de OAuth2 siguen pendientes.

Solución: Elija según su rol:

• Administrador Global: Ejecute a365 setup all de nuevo. La CLI solicita consentimiento del administrador. Complete el flujo de consentimiento en la ventana del navegador que aparece.

• Administrador o desarrollador de Id. de agente: No puede completar las autorizaciones 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 su Administrador global.

Faltan los archivos de configuración o no son válidos

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

Solución:

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

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

La configuración finaliza pero los recursos no se crean

Síntoma: El comando de configuración tiene éxito, pero los recursos de Azure no existen.

Solución:

1. Verifique los recursos creados abriendo a365.generated.config.json en su directorio de trabajo.
2. Verifique que existan recursos de Azure usando el comando az resource list.
3. Si faltan recursos, compruebe errores en la salida de configuración y vuelva a ejecutar la configuración usando el comando a365 setup all.

# 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

El esquema del agente no está registrado en Microsoft Entra

Síntoma: La configuración se completa pero no encuentras el plano del agente en el centro de administración Microsoft Entra.

Solución:

1. Obtener un id. de proyecto de a365.generated.config.json.

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

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

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

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

   a365 setup all
   

Permisos de API no concedidos

Síntoma: La configuración se completa, pero los permisos aparecen como "No concedidos" en Microsoft Entra.

Solución:

1. Abra el Centro de administración Microsoft Entra.

2. Regístrese en la aplicación Encontrar su modelo de agente.

3. Vaya a Permisos de API.

4. Conceder consentimiento del administrador:

   1. Seleccione Conceder consentimiento de administrador para [Su inquilino].
   2. Confirme la acción.

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

Identidad administrada no habilitada

Síntoma: Existe una aplicación web, pero la identidad gestionada no está habilitada.

Solución:

1. Verifique el estado de la identidad gestionada mediante el comando az webapp identity show.
2. Si no está habilitado, habilítelo manualmente usando el comando az webapp identity assign.
3. Verifique que esté habilitado usando el comando az webapp identity show.

# 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>

La configuración tarda demasiado o deja de responder

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

Solución:

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

2. Si la configuración realmente deja de responder, cancélela (Ctrl+C) y compruebe qué 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 reintente.

   a365 cleanup
   a365 setup all
   

Limpiar un agente sin configuración

Síntoma: Se ha aprovisionado un agente con a365 setup all --agent-name <name> y ahora desea eliminarlo, pero no cuenta con un archivo de configuración a365.config.json.

Solución: Ejecute a365 cleanup --agent-name para eliminar el agente sin archivo de configuración. La CLI lee los identificadores de recursos de la configuración global generada que se creó durante el proceso de arranque inicial.

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

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

No se puede enviar el primer mensaje en Teams

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

Solución: Se requiere el permiso [Chat.Create][perm-chatcreate] 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 implementar, configure los permisos heredables de su plano técnico para incluir el ámbito Chat.Create.
• Configure un mensaje de chat en Teams para que se envíe cuando se aprovisione una instancia de agente.
• Cree una nueva instancia de agente a partir del plano técnico y pruebe el mensaje de primera ejecución.