Configuración de Agent 365

La CLI de Agent 365 necesita conocer su entidad y otros detalles para crear los recursos de agente necesarios, como la plantilla del agente. La CLI almacena esta información en un archivo de configuración central llamado a365.config.json a tu directorio de trabajo. Todos los comandos de la CLI utilizan este archivo de configuración.

Prerrequisitos

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

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

Permisos necesarios:

• Usuario válido de un tenant de Microsoft Entra con uno de los roles siguientes:
  • Administrador global
  • Administrador de ID de Agente
  • Desarrollador de Identificación de Agente

Configurar la CLI del Agente 365

El a365 config init comando crea a365.config.json, el archivo de configuración central utilizado por todos los comandos CLI del Agente 365, en tu directorio de trabajo. La CLI proporciona un asistente interactivo con Azure CLI integración y valores predeterminados inteligentes para minimizar la entrada manual.

Inicializar configuración

Ejecuta el a365 config init comando para iniciar el asistente de configuración interactivo:

a365 config init

El asistente usa Azure CLI integración y valores predeterminados inteligentes para minimizar la entrada manual. Se te solicita:

El asistente genera automáticamente nombres de recursos relacionados (identidad del agente, plano técnico, usuario del agente) y valida el tipo de proyecto. Antes de guardar, puede configurar opcionalmente permisos de plano técnico personalizados para recursos externos (como la presencia de Teams o los archivos de OneDrive) y personalizar cualquiera de los nombres generados.

Aprende más sobre la estructura de los archivos de configuración

Permisos de plano técnico personalizados

Si el agente necesita acceso a los recursos más allá del conjunto predeterminado (Microsoft Graph, Messaging Bot API, Observability API, Power Platform), declarelos en el campo customBlueprintPermissions de a365.config.json:

{
  "customBlueprintPermissions": [
    {
      "resourceAppId": "00000003-0000-0000-c000-000000000000",
      "resourceName": "Microsoft Graph",
      "scopes": ["Mail.Read", "Mail.Send"]
    },
    {
      "resourceAppId": "<your-api-app-id>",
      "resourceName": "My Custom API",
      "scopes": ["MyApi.ReadWrite"]
    }
  ]
}

Después de agregar permisos personalizados a a365.config.json, aplíquelos al plano técnico:

a365 setup permissions custom

O inclúyelos en la configuración completa:

a365 setup all

Verificar archivos de configuración del Agente 365

El Agente 365 utiliza múltiples archivos de configuración a lo largo del ciclo de desarrollo:

Tras completar la configuración, verifica que tienes los siguientes elementos:

Verificar la creación del a365.config.json archivo

Verifica visualmente que el a365.config.json archivo existe. O bien, utiliza el comando PowerShell Test-Path en un script para automatizar esta verificación.

# Check file exists in current working directory
Test-Path a365.config.json
# Should return: True

Verificar a365.config.json los datos de configuración

Ejecuta el a365 config display comando para ver la configuración actual de la CLI del Agente 365.

a365 config display

La salida de este comando es la siguiente:

{
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "environment": "prod",
  "aiTeammate": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "agentIdentityDisplayName": "your-agent-name Identity",
  "agentBlueprintDisplayName": "your-agent-name Blueprint",
  "agentUserPrincipalName": "youragent@yourtenant.onmicrosoft.com",
  "agentUserDisplayName": "your-agent-name Agent User",
  "managerEmail": "manager@yourtenant.com",
  "agentUserUsageLocation": "usage-location",
  "deploymentProjectPath": "C:\\path\\to\\your\\project",
  "agentDescription": "your-agent-name - Agent 365 Agent"
}

Lista de verificación

✅ Todos los campos tienen valores válidos (sin cadenas vacías ni nulos)
✅ tenantId es un GUID válido
✅ clientAppId es un GUID válido (registro personalizado de su aplicación cliente)
✅ managerEmail Utiliza tu dominio de inquilino
✅ deploymentProjectPath señala a su directorio de código de agente
✅ agentUserPrincipalName sigue el formato agentname@tenant.com
✅ environment se establece (normalmente prod)

Si tu configuración no coincide con la salida esperada, consulta la sección de Solución de problemas para soluciones detalladas.

Agregue a365.generated.config.json al archivo .gitignore. Este archivo contiene secretos generados y nunca se debe confirmar en el control de código fuente.

Paso siguiente

Si todo está en orden, estás listo para continuar.

Configuración sin ajustes previos con --agent-name

Puede aprovisionar agentes (no compañeros de equipo de IA) sin crear un a365.config.json archivo. La CLI resuelve automáticamente los valores necesarios en tiempo de ejecución.

# Provision an Agent without a config file
a365 setup all --agent-name <your-agent-name>

Al proporcionar --agent-name:

• La CLI detecta automáticamente el Tenant ID de az account show. Invalide con --tenant-id <id> si es necesario.
• La CLI busca un registro de aplicación de Entra denominado Agent 365 CLI en el inquilino para resolver la aplicación cliente. No es necesario incluir clientAppId en la configuración.
• La ruta de acceso del proyecto de implementación tiene como valor predeterminado el directorio actual. Ejecute el comando desde la carpeta del proyecto del agente.

Para limpiar los recursos aprovisionados sin un archivo de configuración:

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

El proceso de limpieza lee los identificadores de recursos del archivo de configuración global generado por la configuración de arranque, por lo que no se requiere a365.config.json.

Modos de identidad del agente

El aiTeammate campo controla cómo se aprovisionan las instancias del agente y qué identidad llevan en tiempo de ejecución. Elija el modo correcto en función de lo que el agente debe hacer.

Modo estándar (aiTeammate: false): valor predeterminado

Use este modo cuando el agente actúe como servicio o integración de back-end, procesando mensajes, respondiendo a eventos o llamando a las API, sin necesidad de una identidad de usuario por instancia. Este modo amplía la gama de agentes que puede crear: cualquier servicio que se comunique con la plataforma del Agente 365 se puede registrar como agente, aunque no represente a un usuario o participe en experiencias de colaboración orientadas al usuario.

Este modo es el valor predeterminado. Ejecute el programa de instalación sin marcas o pase --aiteammate false explícitamente:

# Standard setup (default)
a365 setup all

# Equivalent explicit form
a365 setup all --aiteammate false

Los agentes también admiten el aprovisionamiento sin necesidad de configuración mediante --agent-name. Consulte Configuración sin necesidad de configuración con --agent-name.

Modo de compañero de equipo de IA (aiTeammate: true)

Use este modo cuando el agente necesite actuar como participante de primera clase junto con usuarios humanos, por ejemplo, unir reuniones, enviar mensajes en nombre de un usuario o asignar tareas en un flujo de trabajo. Las instancias del agente aprovisionadas en este modo reciben una identidad de usuario dedicada, lo que permite a la plataforma identificar e interactuar individualmente con cada instancia.

La configuración del compañero de equipo de IA requiere que a365.config.json se inicialice con a365 config init. Pase --aiteammate true para seleccionar este modo:

a365 setup all --aiteammate true

Solución de problemas

Utilice estos pasos para diagnosticar y resolver rápidamente problemas comunes con a365.config.json y la CLI de Agent 365.

• El archivo de configuración no existe
• Valores de configuración faltantes o inválidos
• Inquilino o suscripción no válidos
• Error en la validación de aplicaciones cliente personalizadas
• Nombre principal de usuario del agente no válido

El archivo de configuración no existe

Síntoma: Los comandos CLI fallan con "Configuración no encontrada" o Test-Path a365.config.json devuelve False.

Solución: Crea un archivo nuevo a365.config.json .

Complete los pasos para inicializar la configuración.

Faltan valores de configuración o no son válidos

Síntoma: El archivo de configuración existe, pero tiene campos vacíos o errores de validación.

Solución: Sigue los pasos para verificar a365.config.json los datos de configuración.

Si algún campo es incorrecto:

• Opción 1: Reejecuta el mago usando el a365 config init comando.
• Opción 2: Edita a365.config.json manualmente con los valores correctos.

Cliente o suscripción no válidos

Síntoma: La CLI falla con errores de autenticación o autorización.

Solution:

Use estos comandos para volver a autenticarse con Azure, comprobar la cuenta con sesión iniciada, cambiar a la suscripción correcta y reinicializar la configuración de la CLI del Agente 365.

# Re-authenticate with Azure
az login

# Verify you're logged into the correct account
az account show

# If needed, switch to the correct subscription
az account set --subscription "<subscription-name-or-id>"

# Re-initialize configuration
a365 config init

Error en la validación de aplicaciones cliente personalizadas

Síntoma: El asistente de configuración falla al validar el ID personalizado de la aplicación del cliente.

Solución: Revisa el registro personalizado de tu app de cliente para asegurarte de que tu registro incluye todos los permisos y el consentimiento del administrador.

Nombre principal de usuario del agente no válido

Síntoma: Se produce un error en la validación del nombre principal de usuario del agente durante la configuración.

Solución: Asegúrese de que el UPN sigue el formato username@domain. Por ejemplo: demo.agent@contoso.onmicrosoft.com. Un sufijo de dominio que falta es la causa más común.