Implementación del agente en Azure

Has compilado tu agente y lo has probado localmente. Ahora, dale vida en la nube. Este paso es opcional. Puede omitirlo si ya ha implementado el agente en alguna nube (ni siquiera necesita ser 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.

Para actualizar el punto de conexión de mensajería, consulte los siguientes recursos. Muestran cómo puede actualizar el punto de conexión de mensajería si 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 los siguientes elementos:

Cuentas y permisos requeridos

• Suscripción de Azure con acceso de colaborador.
• Código funcional de agente con un punto final de mensajería válido y accesible. Asegúrese de probar el agente localmente y, opcionalmente , probado 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.
• Modelo de agente válido completando el paso del modelo de configuración del agente.
• Archivos de configuración actualizados a365.config.json, y archivo de configuración a365.generated.config.json en el código (por ejemplo, archivo .env).

Herramientas necesarias

• Azure CLI instalado y autenticado (Install Azure CLI)

Implementación en Azure

Implemente el código de aplicación del agente en Azure mediante herramientas estándar de Azure, como la CLI de Azure, Azure Portal o Acciones de GitHub.

Implementar la aplicación del agente

Use el comando de la CLI az webapp deploy de Azure para implementar la aplicación:

# Build your project first (example for .NET)
dotnet publish -c Release -o ./publish

# Deploy to Azure Web App
az webapp deploy --name <your-web-app> --resource-group <your-resource-group> --src-path ./publish

En Acciones de GitHub, utilice la acción de Implementación de Azure Web Apps.

Comprobación de la implementación

Una vez finalizada la implementación, use esta lista y las instrucciones de las secciones siguientes para comprobar la implementación.

✅ 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 de conexión de mensajería responde

Verificar el comando de despliegue completado sin errores

Una vez finalizada la implementación, compruebe si la implementación se ha realizado correctamente en los registros de implementación:

1. Vaya a la aplicación web en Azure Portal.
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 > Su aplicación web
2. Despliegue>Centro de Despliegue
3. Consulta los registros de tu último despliegue

Si la compilación falla:

• Limpie y vuelva a compilar primero en el equipo local para comprobar que la compilació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.
• Consulte La aplicación se bloquea al iniciarse.

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, consulte La aplicación se bloquea al iniciarse.

Verificar que las variables del entorno están configuradas

En Azure portal:

1. Vaya a la aplicación web.
2. Ve a Configuración>Variables de entorno.
3. Compruebe que la configuración existe.

Si las variables de entorno no están activadas:

• Vuelva a ejecutar la implementación para sincronizar desde el .env archivo.
• O bien, establézcalos manualmente en Azure Portal.
• Ver Variables de entorno no establecidas o incorrectas.

Verificar que el endpoint de mensajería responde

Pruebe que el punto de conexión que encuentra en la página Información general de la aplicación web existe mediante PowerShell u otros medios. De lo contrario, consulte 404 en el punto de conexión 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: actualice el código del agente, vuelva a implementar y vuelva a publicar (recuerde 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: Se produce un error en la implementación en Azure.

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
  

• 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
  

• 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: La implementación se realiza correctamente, pero la aplicación web no se está ejecutando.

Solución: Use az webapp start e az webapp show inicie la aplicación web y compruebe que se está ejecutando.

# 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 se inicia pero se bloquea inmediatamente; los registros muestran errores.

Causas comunes:

• Dependencias que faltan : compruebe la salida de compilación para asegurarse de que incluye todos los paquetes necesarios.
• Variables de entorno que faltan : compruebe que se han configurado todas las opciones necesarias.
• Coincidencia incorrecta de la versión de tiempo de ejecución: asegúrese de que el runtime de Azure coincida con su entorno de desarrollo.
• Errores de código : compruebe los registros de aplicación para ver 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

Error 404 en el punto final 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

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.

Para obtener ayuda adicional, consulte: Solución de problemas de puntos de conexión de mensajería.