Compartir por

Esquema del agente de configuración

Importante

Debe formar parte del programa de versión preliminar Frontier para obtener acceso anticipado a Microsoft Agent 365. Frontier le conecta directamente con las innovaciones de inteligencia artificial más recientes de Microsoft. Las versiones preliminares de Frontier están sujetas a los términos de vista previa existentes en tus acuerdos con clientes. Dado que estas características siguen en desarrollo, su disponibilidad y funcionalidades pueden cambiar con el tiempo.

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.

Requisitos previos

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
      • Administrador de ID de agente
      • Desarrollador de id. de agente
    • Acceso a una suscripción de Azure con permisos para crear recursos

  3. Archivo válido a365.config.json en tu directorio de trabajo, configurado mediante este paso: Configurar la configuración del Agente 365.

Crear plano de agente

Utilice el comando a365 setup para crear recursos de Azure y registrar el blueprint 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.

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 plano técnico del agente en el inquilino de Microsoft Entra
    • Crea registros de aplicaciones de Microsoft Entra
    • Configure la identidad del agente con los permisos necesarios

  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

Nota

El programa de instalación normalmente tarda entre 3 y 5 minutos y guarda automáticamente la configuración en a365.generated.config.json. Si se ejecuta como administrador global, la CLI puede abrir una ventana del explorador para el consentimiento del administrador: complete el flujo de consentimiento para continuar. Si se ejecuta como Administrador de ID de Agente o desarrollador, no aparece ninguna ventana del explorador; la CLI genera direcciones URL de consentimiento para que un administrador global lo complete más adelante.

Configuración mediante el administrador de ID de agente o el desarrollador de ID de agente

Si se ejecuta como Administrador de ID de Agente o Desarrollador de ID de Agente (no Administrador Global), a365 setup all completa la mayoría de los pasos automáticamente, pero las concesiones 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, Bot de Mensajería API, Observabilidad API y Power Platform API.

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

# Step 1: Run setup as Agent ID Admin or Developer
a365 setup all
# Setup completes all steps it can. The CLI displays next steps
# showing how a Global Administrator can complete the OAuth2 grants.

# Step 2: Share the config folder with a Global Administrator.
# The folder contains a365.config.json and a365.generated.config.json.

# Step 3: The Global Administrator runs:
a365 setup admin --config-dir "<path-to-config-folder>"

Como alternativa, el administrador global puede abrir la dirección URL de consentimiento combinada que guarda la CLI en a365.generated.config.json (campo: combinedAdminConsentUrl) y conceder consentimiento en una sola visita del explorador. Para obtener más información, consulte a365 setup admin.

Comprobación de la configuración

Cuando termina la configuración, ves un resumen que muestra todos los pasos completados. Compruebe los recursos creados:

  1. Verificar configuración generada:

    a365 config display -g

    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ó 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 ejecute a365 setup admin para completar las concesiones de permisos de OAuth2.

  2. Verificar los recursos de Azure Portal:

    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>App registrations>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 en agentBlueprintId o busque por nombre.

    Compruebe lo siguiente:

    ✅ 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 [su inquilino]"

Para más ayuda, consulta:

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 qué datos y acciones puede tener acceso una aplicación o servicio a través de las API de Microsoft Graph en Microsoft 365 e Id. de Microsoft Entra.

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:

Aplicar permisos a tu plantilla

Use a365 config permissions para agregar los permisos de recursos necesarios a la configuración y, a continuación, ejecutarlos a365 setup permissions custom para aplicarlos al plano técnico en Microsoft Entra.

# Add resource permissions to config
a365 config permissions `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

# Apply permissions to your blueprint
a365 setup permissions custom

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:

Azure

Amazon Web Services (AWS)

Plataforma de la Nube de Google (GCP)

Publicar el agente en el centro de administración de Microsoft

Solución de problemas

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

Sugerencia

La Guía de Resolución de Problemas del Agente 365 contiene recomendaciones de alto nivel para la solución de problemas, mejores prácticas y enlaces a contenido de solución de problemas para cada parte del ciclo de vida del desarrollo del Agente 365.

Estos problemas a veces se producen durante el registro:

Error de permisos insuficientes

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

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

  • Administrador global
  • Administrador de ID de agente
  • Desarrollador de id. de agente

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

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

Nota

Si tienes el rol de Administrador de ID de agente o Desarrollador de ID de agente (no Administrador Global), a365 setup all funciona igual, pero omite las concesiones de permisos de OAuth 2.0. Una vez completada la instalación, un administrador global debe ejecutar a365 setup admin para completar las autorizaciones restantes. Este flujo de trabajo se espera para las organizaciones en las que el desarrollador del agente y el administrador global son personas diferentes.

Falta autenticación de Azure CLI

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

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. Use el flujo de trabajo de entrega:

    # Option 1: Global Admin runs setup admin
a365 setup admin --config-dir "<path-to-config-folder>"

# Option 2: Global Admin opens the combined consent URL
# Find the URL in a365.generated.config.json (combinedAdminConsentUrl field)
a365 config display -g

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. Mostrar la configuración actual usando el comando de visualización de configuración a365.
  3. Si falta o no es válido, reinicializa con el comando a365 config init.
# Verify a365.config.json exists
Test-Path a365.config.json

# Display current configuration
a365 config display

# If missing or invalid, re-initialize
a365 config init

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

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

Solution:

  1. Comprueba los recursos creados usando el a365 config display -g comando.
  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
a365 config display -g

# 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 puede encontrar la plantilla del agente en el Centro de administración de Microsoft Entra.

Solution:

  1. Obtenga el ID del esquema a partir de la configuración generada utilizando el comando a365 config display -g.

    a365 config display -g
# Look for: 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
a365 config display -g

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. Limpie y vuelva a intentarlo.

    a365 cleanup
a365 setup all

No se puede enviar el primer mensaje en Teams

Síntoma: Una vez que se aprovisiona 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.
  • Last updated on