Configuración de Agent 365

La CLI de Agent 365 necesita conocer tu inquilino, suscripción y otros detalles para crear los recursos necesarios para el agente, como Agent Blueprint. La CLI almacena esta información en un archivo de configuración central llamado 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 inquilino de Microsoft Entra con uno de los siguientes roles:
  • Administrador global
  • Administrador de ID de Agente
  • Desarrollador de Identificación de Agente
• Acceso a una suscripción de Azure con permisos para crear recursos

Configurar la CLI del Agente 365

El comando crea , 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 CLI de Azure integración y valores predeterminados inteligentes para minimizar la entrada manual.

Autenticación con Azure

Antes de inicializar la configuración, autentíquese con Azure mediante el comando az login:

az login

Seleccione la suscripción correspondiente cuando se le solicite. El asistente para configuración usa CLI de Azure para consultar suscripciones, grupos de recursos y planes de App Service disponibles. Para una experiencia de desarrollo fluida, configura tu cuenta de usuario inquilino con el rol y permisos adecuados, suscripción y plan de servicio de aplicaciones antes de empezar.

Inicializar configuración

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

a365 config init

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

El asistente genera automáticamente nombres de recursos relacionados (aplicación web, identidad del agente, blueprint, 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

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 archivo

Verifica visualmente que el 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 los datos de configuración

Ejecuta el 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",
  "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "resourceGroup": "your-resource-group",
  "location": "location-of-your-azure-resources",
  "environment": "prod",
  "needDeployment": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "appServicePlanName": "your-app-service-plan",
  "appServicePlanSku": "service-plan-sku",
  "webAppName": "your-web-app",
  "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)
y son identificadores GUID válidos
un GUID válido (registro personalizado de tu aplicación cliente)
✅ resourceGroup y appServicePlanName existen en la suscripción de Azure
Utiliza tu dominio de arrendatario
Indica tu directorio de código del agente
sigue el formato
se establece normalmente (típicamente)
es para la configuración inicial. Si no necesitas despliegue, aprende a configurar un endpoint de mensajería agente.

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

Agregue al archivo . 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.

Solución de problemas

Utiliza estos pasos para diagnosticar y resolver rápidamente problemas comunes con la CLI del Agente 365.

• El archivo de configuración no existe
• Faltan valores de configuración o no son válidos
• Cliente 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 nombre de la aplicación web ya está en uso

El archivo de configuración no existe

Síntoma: Los comandos CLI fallan con "Configuración no encontrada" o devuelven " ".

Solución: Crea un archivo nuevo .

Complete los pasos para Authenticate con Azure y Initialize configuration.

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 los datos de configuración.

Si algún campo es incorrecto:

• Opción 1: Vuelve a ejecutar el asistente usando el comando.
• Opción 2: Edita 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 . Por ejemplo: . Un sufijo de dominio que falta es la causa más común.

El nombre de la aplicación web ya está en uso

Síntoma: Se produce un error en el programa de instalación porque el nombre de la aplicación web ya está en uso.

Solution: Los nombres de aplicación web deben ser únicos globalmente en Azure. Actualice a un valor único o vuelva a ejecutar para generar un nuevo nombre.