Implementación del agente en Azure

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:

• Utiliza el código del agente desplegado en Amazon Web Services
• Utiliza el código del agente desplegado en Google Cloud Platform

Prerrequisitos

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

Cuentas y permisos requeridos

• Suscripción de Azure con acceso como colaborador.
• Código funcional de agente con un punto final de mensajería válido y accesible. Asegúrese de que ha testado el agente localmente y, opcionalmente, testado con Microsoft 365 mediante túneles de desarrollo para comprobar que el código del agente se puede compilar y ejecutar según lo previsto.
• Completa el paso de configuración del prototipo del agente para tener un prototipo de agente válido.
• Asegúrate de que los archivos de configuración y el archivo de configuración en el código (por ejemplo, el archivo .env) estén actualizados.

Herramientas necesarias

• CLI de Azure instalado y autenticado (Install CLI de Azure)
• CLI de A365 instalada (CLI de Agent 365)

Implementación en Azure

El 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.
• - Actualiza los permisos del servidor MCP en tu modelo de 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 comando:

a365 deploy

Opciones de implementación

El comando desplegable soporta varias opciones útiles:

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.

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 vaya a su aplicación web en el portal de Azure.
2. Ve a Configuración de Ajustes para verificar la configuración de la aplicación.
3. Consulta los registros de despliegue en el centro de despliegue.

Para ver el historial detallado de despliegues:

1. Vaya al Portal de Azure > a su aplicación web.
2. DespliegueCentro 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.
• Consulte el fallo del comando Despliegue.

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.
• Ver el fallo de la aplicación al iniciar.

Verificar que la aplicación web esté funcionando

Usa el 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 .

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 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 error o fallo en los registros, consulta Fallos de la aplicación al iniciarse.

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:

• Reejecuta el despliegue para sincronizar desde el archivo.
• O bien, establezca manualmente en Azure Portal.
• Ver Variables de entorno no establecidas o incorrectas.

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. De lo contrario, observarás el error 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.

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.

Falla el comando de despliegue

Síntoma: Error durante la 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
  

• Configuración faltante

  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 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 y 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 - Verifica que la salida de la compilación incluya 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 runtime de Azure sea compatible con su entorno de desarrollo.
• Errores de código - Revisa los registros de aplicaciones para excepciones específicas

Solución: Utiliza los comandos , , y 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 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 petición a la URL. Usa el 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 comandos , y 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 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:

• Desaparecido (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 tiempo de ejecución de Azure en Portal: Configuración>Configuración>Configuración general>Configuraciones de pila.

• Prueba con registro detallado

  a365 deploy --verbose
  

Para obtener ayuda adicional, consulte: Resolución de problemas en el punto de conexión de mensajería.