Instala y usa la CLI de Agent 365

La CLI Agent 365 es una herramienta de línea de comandos multiplataforma para desplegar y gestionar aplicaciones Agent 365 en Azure. Esta referencia explica cómo instalar, actualizar, desinstalar y usar la CLI para automatización y resolución de problemas.

No necesitas instalar la CLI manualmente.Agent 365 Skills comprueba si la CLI está instalada, la instala o la actualiza automáticamente y ejecuta todos los comandos necesarios por ti. Este artículo es una referencia para desarrolladores que necesitan instalar o usar la CLI directamente, por ejemplo, al construir automatización de CI/CD, solucionar un paso específico o trabajar sin un agente de codificación de IA.

Note

El flujo de trabajo completo para desarrolladores , incluida la configuración guiada por IA, la guía de roles y los pasos posteriores a la implementación, se encuentra en Introducción al desarrollo del agente 365. Este artículo es la referencia de la CLI: instalación, actualización, desinstalación, comandos disponibles y resolución de problemas.

Prerequisites

La CLI requiere .NET 8.0 o posterior. Para todos los demás requisitos previos, incluyendo una suscripción a Azure y los roles obligatorios de Entra, consulta Inicio rápido: Conectar un agente existente al Agente 365.

autenticación de Microsoft Entra

Por defecto, la configuración de Agent 365 utiliza la aplicación empresarial Agent 365 CLI administrada por Microsoft si está disponible en tu inquilino.

Propiedad Value
Nombre para mostrar Agent 365 CLI
ID de aplicación (cliente) f54280f4-395e-4ea8-9e48-bf2d4952aa14

Para verificar la aplicación, ve al Centro de administración de Microsoft Entra, selecciona Aplicaciones empresariales>Todas las aplicaciones y busca el identificador de la aplicación. El ID de objeto del principal de servicio es único para tu inquilino. No uses el ID de objeto donde la CLI o la documentación piden un ID de aplicación (cliente).

La CLI comprueba el principal de servicio de la aplicación empresarial en tu inquilino y valida los ámbitos delegados requeridos en el token de acceso. No crea ni modifica el registro de la aplicación de Microsoft. La aplicación gestionada por Microsoft no eleva al usuario iniciado sesión, ni evita los valores predeterminados de acceso condicional o seguridad, ni elimina requisitos de consentimiento separados para los recursos del agente.

Si la aplicación empresarial administrada por Microsoft no está disponible, la configuración sin necesidad de configuración busca una aplicación del inquilino llamada CLI de Agent 365. Las configuraciones existentes que especifican un personalizado clientAppId siguen siendo soportadas. Para las instrucciones, consulta Registro personalizado de aplicación de cliente para la CLI del Agente 365.

La aplicación gestionada por Microsoft utiliza estos métodos de autenticación interactiva:

Medio ambiente Método de autenticación
Windows nativos Administrador de cuentas web (WAM)
Subsistema de Windows para Linux (WSL), macOS y Linux Código del dispositivo

Las aplicaciones personalizadas propiedad del inquilino usan el navegador del sistema cuando WAM no está disponible.

Instalar la CLI de Agent 365

Siga estos pasos para instalar la CLI de Agent 365 globalmente en el sistema operativo.

Prerequisites

Debe tener .NET instalado. (se recomienda .NET 8.0).

Usar dotnet tool install

Instale la CLI del Agente 365 mediante el comando siguiente:

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

Para obtener las instrucciones más recientes y las versiones disponibles, visite la página oficial de NuGet: Microsoft.Agents.A365.DevTools.Cli en NuGet.org

Comprobación de la instalación

Después de instalar la CLI de Agent 365, verifica que esté correctamente instalada ejecutando el --help comando:

a365 -h

Este comando muestra la información de ayuda y confirma que la CLI está lista para usarse.

Actualizar la CLI del Agente 365

Actualice la CLI de Agent 365 mediante el comando dotnet tool update:

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

Note

Para actualizar la CLI del Agente 365, necesitas una conexión a internet para acceder al último paquete NuGet: Microsoft.Agents.A365.DevTools.Cli.

Desinstala la CLI del Agente 365

Desinstale Agent 365 mediante el comando dotnet tool uninstall:

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

Ubicaciones de archivos CLI del Agente 365

La ubicación predeterminada del archivo ejecutable de una herramienta depende del sistema operativo:

Sistema operativo Camino
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

El SDK añade esta ubicación a tu ruta cuando la ejecutas por primera vez. Así que puedes invocar herramientas globales desde cualquier directorio sin especificar la ubicación de la herramienta.

El acceso a la herramienta es específico del usuario, no global de la máquina. Una herramienta global solo está disponible para el usuario que la instala.

Comandos CLI del Agente 365

Para la lista completa de comandos disponibles, utilice el --help comando o consulte la Referencia CLI del Agente 365.

Sugerencia

No es necesario ejecutar comandos de la CLI manualmente. Agent 365 Skills automatiza todo el flujo de trabajo: instalación, configuración, configuración de blueprints, despliegue y publicación, utilizando un agente de codificación con IA. Consulte la referencia de la CLI si va a crear la automatización de CI/CD, resolver problemas de un paso específico o trabajar sin un agente de programación de IA.

Para obtener instrucciones completas sobre cómo configurar un agente de Agente 365 mediante la CLI, consulte Introducción al desarrollo del Agente 365.

Troubleshooting

Esta sección proporciona información sobre cómo solucionar errores con la CLI del Agente 365.

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.

Cuestiones específicas de la CLI tratadas en esta sección:

La aplicación CLI Agent 365 gestionada por Microsoft no está disponible

Actualiza la CLI y vuelve a ejecutarlo a365 setup requirements . Para verificar si el despliegue por etapas llegó a tu inquilino, busca en aplicaciones empresariales en Microsoft Entra el ID f54280f4-395e-4ea8-9e48-bf2d4952aa14de la aplicación.

Si el principal de servicio no está presente, la configuración recurre a una aplicación propiedad del inquilino llamada Agent 365 CLI. Si aún no tienes esa aplicación, sigue Registro de una aplicación cliente personalizada para Agent 365 CLI.

La autenticación por código de dispositivo está bloqueada

La aplicación gestionada por Microsoft utiliza autenticación por código de dispositivo en WSL, macOS y Linux. Los valores predeterminados de seguridad o una política de acceso condicional pueden bloquear este flujo y devolver AADSTS530035.

No desactives la política de seguridad de tu organización para evitar este error. Ejecuta la CLI en Windows nativo para usar WAM, o trabaja con tu administrador de identidad para usar una aplicación personalizada propiedad del inquilino y un flujo de autenticación que permita tu política.

La autenticación falla con AADSTS70007

Las versiones antiguas de la CLI podían usar un modo de respuesta no soportado por el navegador con la aplicación gestionada por Microsoft y devolver AADSTS70007. Actualizar a la última versión de la CLI y volver a intentarlo:

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

Faltan los ámbitos delegados requeridos

La CLI valida los permisos delegados efectivos de la aplicación gestionada por Microsoft a partir de la reclamación del scp token de acceso. Actualiza la CLI y vuelve a ejecutar a365 setup requirements.

No añadas URIs de redirección, reclamaciones opcionales, permisos de API ni permisos locales de inquilino a la aplicación gestionada por Microsoft. Si la validación sigue indicando que faltan ámbitos, capture los identificadores de traza y de correlación del error y contacte con el soporte técnico de Microsoft. Si usas una aplicación propiedad del inquilino, sigue los pasos de validación en el registro de aplicación cliente personalizada para la CLI del Agente 365.

El agente no aparece en Teams

Resolución de problemas de instancias de agentes creados: El agente no aparece en Teams

No puedo crear una instancia de agente en Teams

Resolución de problemas de instancias de agentes: No se puede crear instancia de agente en Teams

  • Last updated on