Comparteix a través de

Implementación del agente en Azure

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.

Has creado tu agente y lo has probado localmente—ahora es el momento de activarlo en la nube. Este paso es opcional y se puede omitir si ya ha implementado el agente en alguna nube (ni siquiera es necesario Azure).

Esta guía le guía a través de la implementación del código del agente para Azure y su publicación en el Centro de administración de Microsoft, donde se convierte en un recurso reconocible para su organización.

También hay recursos disponibles para mostrar cómo puede actualizar el punto de conexión de mensajería si, en lugar de Azure, ya ha implementado el agente en otros proveedores de nube, como Amazon Web Services o Google Cloud Platform:

Prerrequisitos

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

Cuentas y permisos requeridos

Herramientas necesarias

Implementación en Azure

El a365 deploy comando tiene dos subcomandos:

  • a365 deploy app: implementa el código del agente en la aplicación web de Azure creada durante la instalación.
  • a365 deploy mcp - Actualiza los permisos del servidor MCP en el esquema del agente.

Esta guía se centra en la implementación del código de aplicación del agente en Azure.

Implementar la aplicación del agente

Ejecuta el a365 deploy comando:

a365 deploy

Opciones de implementación

El comando desplegable soporta varias opciones útiles:

Opción Description Caso de uso
--dry-run Muestra qué se desplegaría sin ejecutar Previsualiza los pasos del despliegue antes de ejecutarlos
--inspect Pausa antes de la implementación para inspeccionar la carpeta de publicación y el contenido del ZIP Depurar problemas con los paquetes de despliegue
--restart Salta la compilación y comprime la carpeta de publicación existente Iteración rápida tras cambios manuales
-v, --verbose Permite un registro detallado Solución de problemas de implementación
-c, --config Especifica la ruta del archivo de configuración personalizada Uso de configuración no predeterminada

Nota:

Úsalo a365 deploy --help para ver todas las opciones y subcomandos disponibles.

Ejemplo de implementación

# Preview what will be deployed
a365 deploy --dry-run

# Deploy with verbose logging for troubleshooting
a365 deploy --verbose

# Inspect the deployment package before uploading
a365 deploy --inspect

Cómo funciona el despliegue

El despliegue funciona de forma diferente según el lenguaje de programación que utilices.

El comando de despliegue para agentes de .NET:

  • Detecta .NET archivos de proyecto (*.csproj, *.fsproj o *.vbproj)
  • Restaura paquetes NuGet utilizando dotnet restore
  • Publica la aplicación usando dotnet publish con configuración de Release
  • Crea un manifiesto Oryx con un comando DLL para el punto de entrada (por ejemplo, dotnet YourApp.dll)
  • Configura Azure tiempo de ejecución en función de la versión de .NET detectada (valor predeterminado: DOTNET|8.0)
  • Despliegue mediante archivo zip con progreso en tiempo real

Advertencia

Secrets management: Al implementar, almacene variables de entorno (incluidas las claves de API y los secretos) en Configuraciones de Aplicación de Azure. Aunque las variables de entorno se usan comúnmente para la configuración, se almacenan en texto plano. En entornos de producción, use Azure Key Vault para secretos confidenciales. Obtenga más información sobre el almacenamiento seguro de secretos de aplicaciones en desarrollo en ASP.NET Core y configuración del proveedor de Azure Key Vault. Nunca confirme archivos .env con información confidencial en el control de código fuente.

Comprobación de la implementación

Una vez finalizada la implantación, utilice esta lista y las instrucciones siguientes para verificar su despliegue

✅ Comando de despliegue completado sin errores
✅ La aplicación web está funcionando
✅ Los registros de aplicaciones muestran un arranque exitoso
✅ Las variables de entorno están configuradas
✅ El punto final de mensajería responde

Verificar el comando de despliegue completado sin errores

Cuando ejecutas el comando deploy deberías ver:

✓ Build completed successfully
✓ Deployment completed successfully

También deberías ver el éxito indicado en los registros de despliegue:

  1. Busque su webAppName configurado y acceda a su aplicación web en el portal de Azure.
  2. Ve a Configuración>Configuración para verificar los ajustes de la app.
  3. Consulta los registros de despliegue en el centro de despliegue.

Para ver el historial detallado de despliegues:

  1. Vaya al Portal de Azure > tu aplicación web.
  2. Despliegue>Centro de Despliegue
  3. Consulta los registros de tu último despliegue

Si la compilación falla:

  • Limpia y reconstruye localmente primero para confirmar que la construcción funciona.
  • Comprueba si faltan dependencias o errores de sintaxis.
  • Ver falla el comando Desplega.

Si la app se cierra tras el despliegue:

  • Revisa los registros para detectar mensajes de error específicos.
  • Verifica que todas las variables de entorno requeridas estén activadas.
  • Consulta la aplicación cuelga al iniciar.

Verificar que la aplicación web esté funcionando

Usa el az webapp show comando para verificar que la aplicación web está en funcionamiento.

az webapp show --name <your-web-app> --resource-group <your-resource-group> --query state

La salida esperada de este comando es Running.

Verifica los registros de aplicaciones que muestran un arranque exitoso

Para ver los registros de aplicaciones web en el portal de Azure:

  1. Busque la aplicación web por nombre en el portal de Azure.
  2. Ve a Resumen>Registros>Flujo de Registros.

Alternativamente, puedes usar el comando PowerShell az webapp log tail para leer los registros de la aplicación web:

az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

Si hay mensajes de fallo o error en los registros, consulta Caídas de la aplicación al arrancar.

Verificar que las variables del entorno están configuradas

En Azure portal:

  1. Accede a tu aplicación web.
  2. Ve a Configuración>Variables de entorno.
  3. Verifica que existan tus ajustes

Si las variables de entorno no están activadas:

Verificar que el endpoint de mensajería responde

Prueba que el punto final que encuentres en la página de Resumen de tu aplicación web existe mediante Powershell u otros medios. Si no, consulta el 404 en el endpoint de mensajería.

Pasos siguientes

Después, publica tu aplicación de agente en el centro de administración de Microsoft para poder crear instancias y usuarios de agentes desde ella.

Publicar su agente

Tu agente está ahora en la nube y listo para responder a las solicitudes del agente. Mientras tu agente gestiona solicitudes reales, considera estos siguientes pasos para tu código:

  • Monitorizar el rendimiento: Utilizar características de observabilidad para seguir el comportamiento del agente y optimizar las respuestas.
  • Añadir más herramientas: Explora el catálogo de herramientas para ampliar las capacidades de tu agente.
  • Iterar y mejorar: Actualiza el código de tu agente, vuelve a desplegar y vuelve a publicar (¡recuerda incrementar el número de versión!).
  • Escala en toda tu organización: Comparte las historias de éxito de tu agente para impulsar la adopción.

Solución de problemas

En esta sección se describen problemas comunes al implementar agentes en Azure.

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.

Falla el comando de despliegue

Síntoma: Error durante la a365 deploy ejecución del comando.

Causas habituales y sus soluciones:

  • Errores de compilación

    Reconstruye el proyecto localmente para ver errores detallados de compilación:

    # .NET
dotnet clean
dotnet build --verbosity detailed

# Python
uv build

# Node.js
npm install
npm run build

  • Falta de configuración

    Asegúrate de que ambos archivos de configuración existen y son correctos:

    # Verify configuration files exist
Test-Path a365.config.json
Test-Path a365.generated.config.json

# Display configuration file contents
a365 config display

# Display generated configuration file contents
a365 config display -g

  • Azure ha expirado la autenticación

    Vuelva a iniciar sesión en Azure:

    az login
az account show  # Verify correct subscription

  • Aplicación web no creada

    Enumera Web Apps para confirmar que el destino existe:

    # List Web Apps in resource group
az webapp list --resource-group <your-resource-group> --output table

    Si la aplicación web no existe, vuelve a hacer la configuración:

    # Verify setup was completed
a365 config display -g
# Check for: webAppName

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

  • Consulta los registros de despliegue

    Utiliza el az webapp log tail comando para ver registros detallados de despliegue:

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group>

  • Comprobación:

    # Web App should be running
az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Expected: "Running"

Se detiene la aplicación web

Síntoma: El despliegue tiene éxito, pero la aplicación web no está en funcionamiento.

Solución: Usa az webapp start y az webapp show para iniciar la aplicación web y verifica que está funcionando.

# Start the Web App
az webapp start --name <your-app> --resource-group <your-resource-group>

# Verify it's running
az webapp show --name <your-app> --resource-group <your-resource-group> --query state

La aplicación se cierra al arrancar

Síntoma: La aplicación web arranca pero se cierra inmediatamente; Los registros muestran errores.

Causas comunes:

  • Dependencias faltantes - Comprueba la salida de compilación incluida de todos los paquetes requeridos
  • Variables de entorno faltantes - Verifica que todos los ajustes necesarios estén configurados
  • Incompatibilidad de versión de tiempo de ejecución - Asegúrese de que el entorno de ejecución de Azure coincide con el entorno de desarrollo.
  • Errores de código - Revisa los registros de aplicaciones para excepciones específicas

Solución: Utiliza los az webapp log tailcomandos , az webapp config appsettings list, y az webapp config appsettings set para ver los registros, comprobar variables de entorno y establecer variables que faltan.

# View application logs
az webapp log tail --name <your-app> --resource-group <your-resource-group>

# Check environment variables
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Manually set a missing variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings KEY=VALUE

404 en el endpoint de mensajería

Síntoma: La aplicación web está funcionando pero /api/messages el endpoint devuelve 404.

Solution:

  1. Verifica la configuración de la ruta en el código de tu agente.
  2. Comprueba que el gestor de endpoint esté correctamente registrado.
  3. Asegúrate de que se especifique el punto de entrada correcto en el despliegue.

Prueba el endpoint enviando una GET petición a la URL. Usa el az webapp config show comando para comprobar la configuración de la aplicación web.

curl https://<your-app-name>.azurewebsites.net/api/messages
az webapp config show --name <your-app> --resource-group <your-resource-group>

Variables de entorno no fijadas o incorrectas

Síntoma: El despliegue tiene éxito pero el agente no funciona; Errores de configuración ausentes en los registros.

Solución: Verifica y actualiza las variables del entorno. Usa los az webapp config appsettings listcomandos , y az webapp config appsettings set para comprobar las variables de entorno y establecer las variables que faltan. Luego, realice un nuevo despliegue.

# List all app settings
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Set a specific variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings API_KEY=your-value

# Re-run deployment (it will update app settings from .env)
a365 deploy

Problemas con los paquetes de despliegue

Síntoma: El despliegue se sube pero la aplicación no se inicia correctamente.

Solución: Utiliza la a365 deploy --inspect bandera para examinar el paquete de despliegue:

# Inspect what will be deployed
a365 deploy --inspect

Esta bandera se pausa antes de subir, permitiéndote:

  • Revisa el contenido de la carpeta de publicación
  • Verificar el contenido del archivo ZIP
  • Asegúrate de que todos los archivos estén incluidos

Problemas comunes que hay que comprobar:

  • Falta node_modules (Node.js)
  • Faltan archivos DLL compilados (.NET)
  • Faltan paquetes de Python

La compilación se realiza correctamente localmente, pero se produce un error en Azure

Symptom: Code se compila correctamente en la máquina, pero se produce un error durante la implementación de Azure.

Soluciones:

  • Comprueba dependencias específicas de la plataforma

    • Algunos paquetes tienen versiones específicas de la plataforma.
    • Asegúrese de que las dependencias admiten Linux (Azure Web Apps se ejecutan en Linux de forma predeterminada).

  • Verificar que las versiones en tiempo de ejecución coincidan

    Ejecute estos comandos:

    # Check your local version
dotnet --version  # .NET
node --version    # Node.js
python --version  # Python

    Compare con el entorno de ejecución de Azure en el portal: Ajustes>Configuración>Configuración general>Configuración de pila.

  • Prueba con registro detallado

    a365 deploy --verbose

Para ayuda adicional, consulta: Resolución de problemas en el punto final de mensajería

  • Last updated on