Implementar un agente en Azure

Ha compilado su agente y lo ha probado localmente. Ahora, dale vida en la nube. Este paso es opcional. Puedes omitir este paso si ya has implementado tu agente en alguna nube (no necesariamente en Azure).

Esta guía te indica cómo realizar la implementación del código del agente en Azure y su publicación en el Centro de administración de Microsoft, donde se convierte en un activo registrado para tu organización.

Para actualizar el punto de conexión de mensajería, consulta los siguientes recursos. Te muestran cómo puedes actualizar el punto de conexión de mensajería si implementaste tu agente en otros proveedores de nube como Amazon Web Services o Google Cloud Platform:

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

Requisitos previos

Antes de comenzar, asegúrate de que dispongas de lo siguiente:

Cuentas y permisos requeridos

• Suscripción de Azure con acceso de colaborador.
• Código de agente funcional con un punto de conexión de mensajería válido y accesible. Asegúrate de haber probado tu agente localmente y, opcionalmente, de haberlo probado con Microsoft 365 usando túneles dev para verificar que el código del agente pueda compilarse y ejecutarse como se espera.
• Proyecto de agente válido tras completar el paso de configuración del proyecto 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

• CLI de Azure instalada y autenticada (Instalar CLI de Azure)

Implementación en Azure

Implementa el código de la aplicación de agente en Azure utilizando herramientas estándares de Azure como la CLI de Azure, Azure Portal o Acciones de GitHub.

Implementación de la aplicación de agente

Utiliza el comando de la CLI de Azure az webapp deploy para implementar tu 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

Para Acciones de GitHub, utiliza la acción Azure Web Apps Deploy.

Advertencia

Administración de secretos: se almacenan las variables de entorno, incluidas las claves de API y los secreto, como configuración de aplicación de Azure, en lugar de en el código o los archivos de configuración. Para entornos de producción, usa Azure Key Vault para secretos confidenciales. Más información sobre Almacenamiento seguro de secretos de aplicaciones en desarrollo en ASP.NET Core y Proveedor de configuración 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 implementación, utiliza esta lista y las instrucciones de las siguientes secciones para verificarla.

✅ Comando de implementación completado sin errores
✅ La aplicación web se está ejecutando
✅ Los registros de la aplicación muestran un inicio exitoso
✅ Las variables de entorno están configuradas
✅ El punto de conexión de mensajería responde

Verificar que el comando de implementación se haya completado sin errores

Una vez finalizada la implementación, verifica el éxito en los registros de implementación:

1. Vaya a la aplicación web en Azure Portal.
2. Ve a Ajustes>Configuración para verificar la configuración de la aplicación.
3. Comprueba los registros de implementación en el centro de implementación.

Para ver el historial detallado de implementación:

1. Ve a Azure Portal > Tu aplicación web
2. Implementación>Centro de implementación
3. Consulta los registros de tu última implementación

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 hay errores de sintaxis.
• Consulta Falla el comando de implementación.

Si la aplicación falla después de la implementación:

• Revisa los registros en busca de mensajes de error específicos.
• Verifica que todas las variables de entorno requeridas estén configuradas.
• Consulte La aplicación se bloquea al iniciarse.

Verificar que la aplicación web esté en ejecución

Utiliza el comando az webapp show para verificar que la aplicación web esté en ejecutándose.

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

La salida esperada de este comando es Running.

Verifica que los registros de la aplicación muestren un inicio exitoso

Para ver los registros de la aplicación web en Azure Portal:

1. Busca la aplicación web por su nombre en Azure Portal.
2. Ve a Información general>Registros>Flujo de registros.

Alternativamente, puedes usar el comando de 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 de entorno estén configuradas

En Azure Portal:

1. Ve a tu aplicación web.
2. Ve a Ajustes>Variables de entorno.
3. Verifica que existan las configuraciones.

Si las variables de entorno no están configuradas:

• Vuelve a ejecutar la implementación para sincronizar desde el archivo .env.
• O configúralos manualmente en Azure Portal.
• Consulta Variables de entorno no configuradas o incorrectas.

Verificar que el punto de conexión de mensajería responda

Comprueba que el punto de conexión que encuentres en la página Información general de tu aplicación web exista usando PowerShell u otros medios. Si no, consulte Error 404 en el punto de conexión de mensajería.

Pasos siguientes

A continuación, 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 el agente

Tu agente ya está activo en la nube y listo para responder a solicitudes dirigidas al agente. A medida que el agente gestiona las solicitudes reales, ten en cuenta estos pasos siguientes para tu código:

• Supervisar el rendimiento: usa características de observabilidad para realizar un seguimiento del comportamiento del agente y optimizar las respuestas.
• Agregar más herramientas: explora el catálogo de herramientas para expandir las funcionalidades del 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).
• Escalar en toda la organización: comparte las historias de éxito del 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 solución de problemas de Agent 365 contiene recomendaciones generales, procedimientos recomendados y vínculos a recursos de solución de problemas para cada parte del ciclo de vida del desarrollo de Agent 365.

Falla el comando de implementación

Síntoma: error al implementar en Azure.

Causas comunes y soluciones:

• Errores de compilación

  Vuelve a compilar 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
  

• Autenticación en Azure expirada

  Vuelve a iniciar sesión en Azure:

  az login
  az account show  # Verify correct subscription
  

• Aplicación web no creada

  Enumera las aplicaciones web para confirmar que la aplicación objetivo exista:

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

• Comprobación de los registros de implementación

  Usa el comando az webapp log tail para consultar los registros detallados de implementación:

  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"
  

La aplicación web está detenida

Síntoma: la implementación tiene éxito pero la aplicación web no está ejecutándose.

Solución: usa az webapp start y az webapp show para iniciar la aplicación web y verificar 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 bloquea al iniciarse

Síntoma: la aplicación web se inicia pero se cierra inmediatamente; los registros muestran errores.

Causas comunes:

• Faltan dependencias: comprueba el resultado de la compilación para asegurarte de que incluya todos los paquetes obligatorios.
• Faltan variables de entorno: verifica que todos los ajustes obligatorios estén configurados.
• Incompatibilidad de versión de tiempo de ejecución - Asegúrese de que el tiempo de ejecución de Azure sea compatible con su entorno de desarrollo.
• Errores de código: verifica los registros de la aplicación en busca de excepciones específicas.

Solución: usa los comandos az webapp log tail, az webapp config appsettings list y az webapp config appsettings set para consultar los registros, revisar las variables de entorno y configurar las variables que falten.

# 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 el punto de conexión /api/messages devuelve 404.

Solución:

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

Prueba el punto de conexión enviando una solicitud GET a la URL. Usa el comando az webapp config show 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 configuradas o incorrectas

Síntoma: la implementación se realiza correctamente pero el agente no funciona; hay errores que indican configuración faltante en los registros.

Solución: verificar y actualizar las variables de entorno. Utiliza los comandos az webapp config appsettings list y az webapp config appsettings set para verificar las variables de entorno y configurar las variables que falten. Realiza de nuevo la implementación.

# 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 falla en Azure

Síntoma: el código se compila bien en tu máquina pero falla durante la implementación en Azure.

Soluciones:

• Comprueba las dependencias específicas de la plataforma

  • Algunos paquetes tienen compilaciones específicas para cada plataforma.
  • Asegúrate de que las dependencias sean compatibles con Linux (Azure Web Apps se ejecutan en Linux por defecto).

• 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
  

  Compara con el tiempo de ejecución de Azure en Portal: Ajustes>Configuración>Configuración general>Configuración de pila.

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