Desencadenadores HTTP en el agente de SRE de Azure

Los desencadenadores HTTP en el agente de Azure SRE son puntos de conexión webhook que los sistemas externos utilizan para invocar a tu agente según sea necesario. Cuando se produce un error en una canalización de integración continua y entrega continua (CI/CD), una herramienta de alerta detecta una anomalía o cualquier cliente HTTP envía una POST solicitud, el agente recibe el contexto del evento y comienza a funcionar inmediatamente.

El problema: Las alertas y los errores de canalización necesitan una evaluación manual.

El equipo ya cuenta con herramientas de alertas, observabilidad y flujo de trabajos como Datadog, Dynatrace, Jira, Splunk y Grafana, además de canalizaciones CI/CD que dan fallos. Cuando algo va mal, la respuesta es la misma cada vez:

  • Un ingeniero recibe una alerta: El ingeniero abre la herramienta de supervisión, lee la alerta y, a continuación, abre manualmente registros, métricas e historial de implementación en varios paneles para entender lo que ha ocurrido.
  • Se produce un error en una canalización: Alguien tiene que detener lo que está haciendo, comprobar la salida de la compilación, correlacionar estos con los cambios recientes y decidir si revertir o corregir hacia adelante.
  • El contexto está disperso: La alerta de Datadog dice: "Pico de CPU en prod-api". La causa principal requiere la correlación de registros de tres servicios, la comprobación de implementaciones recientes y la revisión de seguimientos de Dynatrace.

Funcionamiento de los desencadenadores HTTP

Los desencadenadores HTTP permiten conectar cualquier herramienta que admita webhooks directamente a la instancia del agente de SRE. En lugar de que un ingeniero realice una evaluación manual de prioridades, el sistema que detectó el problema, ya sea una alerta de Datadog, una anomalía de Dynatrace, una transición de flujo de trabajo de Jira o un fallo de canalización, notifica al agente para investigar. El contexto se pasa automáticamente.

Cada desencadenador es un punto de conexión del webhook con nombre en el agente con una dirección URL única. Cuando un sistema externo llama a esa dirección URL a través de HTTP POST, el agente ejecuta la indicación configurada del desencadenador, que se enriquece con cualquier dato JSON dentro del cuerpo de la solicitud.

Conceptos clave

Concepto Cómo funciona
Trigger Un extremo nombrado con una indicación, un agente asignado (predeterminado o subagente) y un nivel de autonomía (autónomo o revisión).
Dirección URL del desencadenador La URL única de webhook que se genera cuando creas un desencadenador. Esta URL de webhook es la que utilizan las herramientas externas para realizar llamadas.
Contexto JSON Cuerpo JSON opcional enviado con la POST solicitud. Se convierte en parte de las instrucciones del agente para que tenga un contexto completo.
Historial de ejecuciones Cada invocación se registra con una marca de tiempo, un enlace al hilo del proceso y un estado de éxito o fallo.
Habilitar o deshabilitar Active o desactive desencadenadores sin eliminar. Los desencadenadores deshabilitados devuelven un 404.

Invocación de un desencadenador

Llame a la dirección URL del desencadenador con una solicitud HTTP POST :

curl -X POST \
  https://your-agent.sre.azure.com/api/v1/httptriggers/trigger/<TRIGGER_ID> \
  -H "Authorization: Bearer <ARM_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "datadog",
    "alert_title": "High error rate on checkout-api",
    "severity": "critical",
    "service": "checkout-api",
    "region": "eastus2",
    "metric": "error_rate",
    "value": "8.2%",
    "threshold": "5%"
  }'
Parte ¿Qué es?
URL El punto de conexión único del webhook del desencadenador. Encuéntralo en la vista detallada del desencadenador en Dirección URL del desencadenador.
Authorization Un token de portador de Azure Resource Manager. Consulte Autenticación para la invocación del desencadenador.
Tipo de contenido Debe ser application/json cuando va a enviar un cuerpo de JSON.
Cuerpo JSON (opcional) Cualquier dato JSON que desee que vea el agente. Estos datos forman parte del mensaje del agente. Incluya cualquier contexto que ayude al agente a investigar, como el nombre de la alerta, la gravedad y el servicio afectado.

El cuerpo JSON es opcional. Si invoca el activador sin contenido en el cuerpo, el agente solo usará la instrucción predefinida del activador. Con un cuerpo, el agente ve tanto la solicitud como los datos que ha enviado.

Autenticación para la invocación de desencadenador

El punto de conexión del desencadenador requiere un token de portador de Azure Resource Manager en el encabezado Authorization: Bearer <TOKEN>. El autor de la llamada necesita permiso Microsoft.App/agents/threads/write para el recurso del agente.

Formas de obtener un token

Método Más adecuado para Detalles
Entidad de servicio Flujos de trabajo de CI/CD, sistemas automatizados Cree un registro de aplicación, asigne el rol en el recurso del agente y use el flujo de credenciales de cliente para obtener un token.
Identidad administrada Servicios hospedados en Azure (Azure Functions, Azure Virtual Machines, Azure Container Apps) No hay secretos que administrar. El recurso de Azure se autentica automáticamente.
CLI de Azure Pruebas y desarrollo Ejecute az account get-access-token --resource https://management.azure.com --query accessToken -o tsv.

Conexión de herramientas externas que no admiten la autenticación de Azure

Herramientas como Datadog, Dynatrace, Jira y Splunk envían webhooks con sus propios formatos de autenticación, no tokens de Azure Resource Manager. Para salvar la brecha, utilice uno de los siguientes intermediarios.

Intermediario Cómo funciona
Funciones de Azure Recibe el webhook, adquiere un token de Azure Resource Manager mediante su identidad administrada y reenvía la llamada a la dirección URL del desencadenador.
Azure Logic Apps Flujo de trabajo sin código que recibe webhooks de cualquier origen y llama a las API de Azure con autenticación integrada de Azure Resource Manager.
Azure API Management Se sitúa delante de la URL del desencadenador y se encarga de la validación y la transformación de los tokens mediante directrices.

Respuesta

{
  "message": "HTTP trigger execution initiated",
  "executionTime": "2026-03-13T10:30:00Z",
  "threadId": "thread-abc123",
  "success": true
}

El desencadenador devuelve HTTP 202 (aceptado) inmediatamente. El agente procesa la solicitud de forma asincrónica.

Lo que hace que este enfoque sea diferente

Los desencadenadores HTTP conectan directamente sus herramientas de alertas y CI/CD existentes al agente sin la intervención de un ingeniero. El sistema que detectó el problema le indica al agente que investigue y automáticamente transmite el contexto completo. No hay paginación, ningún cambio de panel ni recopilación de contexto manual.

Antes y después

Antes (evaluación manual) Después (activadores HTTP)
Se activa la alerta de Datadog. El ingeniero recibe una alerta, abre tres tableros de control y comienza a investigar. El webhook de Datadog llama al desencadenador. El agente investiga y publica los resultados automáticamente.
Rupturas de canalización. El ingeniero comprueba los registros de compilación, revisa las solicitudes de incorporación de cambios y decide el siguiente paso. El controlador de fallos de la canalización llama al desencadenador. El agente analiza el error y publica la causa raíz.
Dynatrace detecta anomalías. El ingeniero correlaciona manualmente entre servicios. El webhook de Dynatrace llama al desencadenador con el contexto de la anomalía. El agente correlaciona los registros, las métricas y las implementaciones.

Tareas programadas frente a desencadenadores HTTP

Tareas programadas Desencadenadores HTTP
Basado en el tiempo (programación cronológica). Controlado por eventos (a petición).
Se ejecuta independientemente de si ha ocurrido algo o no. Solo se ejecuta cuando se le llama.
No hay entrada externa por ejecución. Datos de carga insertados en cada invocación.
Ideal para comprobaciones periódicas. Ideal para reacciones controladas por eventos.

Use ambos juntos. Use tareas programadas para la supervisión proactiva y los desencadenadores HTTP para el control de eventos reactivos.

Casos de uso

Integración de canalizaciones de CI/CD

Cuando se produce un error en una canalización de implementación, invoque al agente para analizar el error:

# In your pipeline's failure handler
curl -X POST "$AGENT_TRIGGER_URL" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"pipeline\": \"$PIPELINE_NAME\", \"run_id\": \"$RUN_ID\", \"error\": \"$ERROR_MESSAGE\"}"

Investigación impulsada por alertas

Conecte el sistema de alertas para desencadenar una investigación automatizada cuando se activen alertas críticas:

{
  "alert_name": "Error rate > 5%",
  "severity": "P1",
  "service": "checkout-api",
  "region": "eastus2",
  "start_time": "2026-03-13T10:15:00Z"
}

Verificaciones de cumplimiento del despliegue

Una vez completada la implementación, desencadene una revisión de cumplimiento:

curl -X POST "$AGENT_TRIGGER_URL" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -d '{"deployment_id": "deploy-456", "environment": "production", "changes": ["config update", "image bump"]}'

Referencia de las API

Punto final Método Descripción
/api/v1/httptriggers GET Enumera todos los desencadenadores.
/api/v1/httptriggers/create POST Cree un nuevo desencadenador.
/api/v1/httptriggers/{id} GET Obtenga los detalles del desencadenador.
/api/v1/httptriggers/{id} PUT Actualizar las propiedades del desencadenador.
/api/v1/httptriggers/{id} DELETE Elimine un desencadenador.
/api/v1/httptriggers/{id}/enable POST Habilite un desencadenador.
/api/v1/httptriggers/{id}/disable POST Deshabilite un desencadenador.
/api/v1/httptriggers/{id}/execute POST Ejecute un desencadenador manualmente.
/api/v1/httptriggers/{id}/executions GET Obtiene el historial de ejecución.
/api/v1/httptriggers/trigger/{id} POST Punto de conexión de webhook externo.

Solución de problemas

El desencadenador devuelve 404

  • Compruebe que el desencadenador está establecido en habilitado. Los desencadenadores deshabilitados devuelven un 404.
  • Compruebe que el identificador del desencadenador en la dirección URL es correcto.

401 No autorizado

  • La audiencia del token debe coincidir con el identificador de la aplicación del agente de SRE, no https://management.azure.com.
  • Para obtener un token para las pruebas, use az account get-access-token --resource 59f0a04a-b322-4310-adc9-39ac41e9631e --query accessToken -o tsv.

El desencadenador se ejecuta, pero el agente no actúa

  • Compruebe el mensaje del agente. Es posible que un mensaje vacío no genere una salida útil.
  • Compruebe que el subagente elegido tiene las herramientas necesarias para la tarea.
  • Compruebe el historial de ejecución para ver los detalles del error.

Límites

Recurso Limit
Desencadenadores por agente No hay límites estrictos.
Número máximo de turnos por ejecución 250 vueltas.
Autenticación El token de portador es necesario para cada dirección URL del desencadenador.

Contenido relacionado

  • Last updated on