Incorpore un único agente con Agent 365 CLI

Utiliza la CLI de Agent 365 para crear los objetos de identidad de Microsoft Entra para un agente y registrar el agente con Agent 365. Empieza con un agente no productivo para poder validar la identidad, los permisos, el consentimiento y el registro antes de incorporar a los agentes en masa.

Este artículo utiliza Expense Review como nombre base para un agente estándar que revisa los informes de gastos en nombre de un empleado registrado. Utiliza autenticación en nombre de (OBO) y no necesita su propia cuenta de usuario de Microsoft Entra, buzón ni presencia en Teams.

El flujo de trabajo sin configuración crea:

  • Un plano técnico de identidad de agente llamado Plano técnico de revisión de gastos.
  • Una identidad de agente llamada Agente de Revisión de Gastos.
  • Concesiones de permisos delegados para la autenticación OBO.
  • Un registro Agent 365 para el agente.
  • Un a365.generated.config.json archivo que registra los identificadores generados y el estado de configuración.

Para una explicación de los objetos identidad, véase Agent 365 identity.

Prerequisites

Antes de comenzar, asegúrese de que tiene lo siguiente:

  • Un tenant de Microsoft con el Agente 365 activado. Utiliza un tenant no productivo o un entorno de prueba para esta guía.
  • Una suscripción de Azure en el mismo inquilino.
  • El rol de Contribuidor en la suscripción de Azure.
  • Necesita al menos el rol de Desarrollador de id. de agente en Microsoft Entra ID para crear el plano técnico y la identidad del agente.
  • Hay un Administrador global disponible para conceder permisos OAuth. Si ocupas este puesto, puedes completar el flujo de trabajo en una sola sesión. De lo contrario, la CLI proporciona URLs de consentimiento para enviar a un Administrador Global.
  • Se requiere el rol Administrador de aplicaciones o Administrador global si cambia el escenario para usar autenticación de servicio a servicio (S2S).
  • .NET 8.0 o posterior.
  • La CLI de Azure, que ha iniciado sesión en el inquilino y la suscripción que desea usar.
  • La CLI de Agent 365.

La configuración de Agent 365 utiliza la aplicación empresarial Agent 365 CLI administrada por Microsoft cuando está disponible en tu inquilino. Su ID de aplicación (cliente) es f54280f4-395e-4ea8-9e48-bf2d4952aa14. Si la aplicación no está disponible, la CLI busca una aplicación propiedad del inquilino llamada CLI de Agent 365. Un Administrador Global puede crear y configurar una aplicación propiedad del tenant a partir del prompt de la CLI. Para obtener más detalles sobre la alternativa, consulte Registro personalizado de la aplicación cliente para Agent 365 CLI.

Note

Este escenario no crea un usuario agente. Los usuarios de agentes solo son necesarios cuando un agente requiere sus propios recursos con licencia de Microsoft 365, como un buzón de correo, y solo están disponibles para las organizaciones que participan en el programa de versión preliminar de Frontier.

Instalar la CLI de Agent 365

Instala la CLI como una herramienta .NET global:

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli

Si la CLI ya está instalada, actualízala:

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

Compruebe la instalación:

a365 --version

Para la resolución de problemas de instalación y ubicaciones de archivos compatibles, consulte Instalar y usar la CLI del Agente 365.

Seleccionar el inquilino y la suscripción

Inicie sesión en Azure:

az login

Haz una lista de las suscripciones disponibles en tu cuenta:

az account list --output table

Selecciona la suscripción en el tenant donde quieres incorporar al agente:

az account set --subscription "<subscription-id-or-name>"

Confirma el tenant activo y la suscripción:

az account show --query "{tenantId:tenantId, subscriptionId:id, subscriptionName:name}" --output table

Anota el ID del inquilino. La CLI lo detecta desde la cuenta activa de CLI de Azure. También puedes proporcionarlo explícitamente usando --tenant-id.

Valida los requisitos previos

Ejecuta la comprobación de requisitos desde cualquier directorio:

a365 setup requirements

El comando verifica la autenticación, el acceso a Azure, el registro del tenant, los roles y la aplicación cliente. Continúa tras una comprobación fallida para que puedas revisar todos los problemas detectados juntos.

Resuelve todas las comprobaciones requeridas fallidas antes de continuar. Si la aplicación empresarial administrada por Microsoft no está disponible, sigue la indicación para seleccionar o crear una aplicación cliente propiedad del tenant y luego vuelve a ejecutar el comando.

Important

No modifiques la aplicación CLI Agent 365 gestionada por Microsoft. La CLI valida su entidad de servicio y los ámbitos en su token de acceso, pero no modifica el registro de aplicación de Microsoft.

Previsualizar los cambios de incorporación

Crea un directorio de trabajo vacío para la configuración generada y luego cámbialo a él:

New-Item -ItemType Directory -Path .\expense-review-agent
Set-Location .\expense-review-agent

Previsualice los cambios sin crear objetos de inquilino:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false `
    --dry-run

Revisa el ID del tenant, los nombres de objetos derivados, la aplicación cliente seleccionada, los permisos y el modo de autenticación. Este escenario utiliza el modo de autenticación por defecto obo porque el agente actúa en nombre de un empleado iniciado sesión.

Si el tenant detectado no es correcto, especifícalo explícitamente:

a365 setup all `
    --agent-name "Expense Review" `
    --tenant-id "<tenant-id>" `
    --aiteammate false `
    --dry-run

Incorporar al agente

Ejecuta el mismo comando sin --dry-run:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false

La CLI vuelve a validar los requisitos, crea el blueprint y la identidad del agente, configura los permisos delegados, registra al agente y escribe a365.generated.config.json.

Si inicias sesión como Administrador Global, completa cualquier solicitud de consentimiento que se abra durante la configuración. Si utilizas el rol de Desarrollador de id. de agente o AAdministrador de id. de agente, la CLI completa los pasos permitidos por su rol e imprime las acciones de consentimiento para un Administrador global. Envíe las direcciones URL de consentimiento generadas al Administrador global y pídale que complete todas las concesiones.

Note

La instalación sin necesidad de configuración asume que el agente está hospedado externamente. No crea recursos de alojamiento en Azure ni actualiza un proyecto de agente.

Comprobar el resultado de incorporación

Revisa el resumen de la configuración. Cada paso requerido debe aparecer como completado. Si un Administrador global aún necesita conceder consentimiento, complete esta transferencia antes de considerar la incorporación finalizada.

Inspecciona la configuración generada:

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

Confirma que la salida contiene:

  • Un ID de plantilla de agente.
  • Un estado de configuración completada, sin acciones de consentimiento pendientes.

Confirma que el resumen de configuración informa de la creación correcta de la identidad del agente y del registro correcto del agente.

Luego verifica el registro en el centro de administración de Microsoft 365:

  1. Vaya al Centro de administración de Microsoft 365.
  2. Seleccione Agentes>Todos los agentes.
  3. Encuentra Expense Review Agent.
  4. Abre el agente y confirma que sus datos de identidad y registro coinciden con la configuración generada.

Solucionar problemas de incorporación

Síntoma Resolution
La comprobación de requisitos informa del inquilino o la suscripción incorrectos. Ejecuta az account set --subscription "<subscription-id-or-name>", verifica el resultado con az account show, y vuelve a ejecutar la comprobación de requisitos. Alternativamente, pasa --tenant-id a a365 setup all.
No se encuentra la aplicación CLI Agent 365 gestionada por Microsoft. Actualiza la CLI y vuelve a ejecutar a365 setup requirements. Si la implementación gradual no ha llegado a tu tenant, utiliza una aplicación cliente del tenant.
El instalador informa que falta un rol requerido. Asigne los roles Colaborador y Desarrollador de id. de agente al operador. Deja tiempo para que las asignaciones se propaguen, vuelve a iniciar sesión y vuelve a ejecutar la comprobación de requisitos.
La configuración se completa pero lista las acciones de consentimiento pendientes. Que un Administrador Global abra todas las URL de consentimiento impresas por la CLI y conceda los permisos solicitados.
El plano técnico o la identidad existe, pero el agente no está en Todos los agentes. Revisa el resumen de configuración para detectar un fallo en el registro del agente. Después de resolver el error, vuelve a ejecutar a365 setup all --agent-name "Expense Review" --agent-registration-only.
La instalación seleccionó el patrón de autenticación incorrecto. Utiliza el modo OBO predeterminado cuando el agente actúa en nombre de un usuario que ha iniciado sesión. Usa --authmode s2s para trabajo de fondo o --authmode both cuando se requieren ambos patrones. Las concesiones de S2S requieren Administrador de aplicaciones o Administrador global.

Para más resoluciones específicas de CLI, véase Resolución de problemas de Agent 365.

Pasos siguientes

  • Se actualizó por última vez el