Gatilhos HTTP no Agente SRE do Azure

Os gatilhos HTTP no Agente SRE do Azure são pontos de extremidade de webhook que os sistemas externos usam para invocar seu agente sob demanda. Quando um pipeline de CI/CD (integração contínua e entrega contínua) falha, uma ferramenta de alerta detecta uma anomalia ou qualquer cliente HTTP envia uma POST solicitação, o agente recebe o contexto do evento e começa a trabalhar imediatamente.

O problema: alertas e falhas em pipelines precisam de triagem manual

Sua equipe já tem ferramentas de alerta, observabilidade e fluxo de trabalho, como Datadog, Dynatrace, Jira, Splunk e Grafana, e pipelines de CI/CD que falham. Quando algo dá errado, a resposta é a mesma sempre:

Um engenheiro recebe uma notificação: Ele abre a ferramenta de monitoramento, lê o alerta e, em seguida, verifica manualmente logs, métricas e histórico de implantação em vários painéis para entender o que ocorreu.
Um pipeline falha: alguém precisa parar o que está fazendo, verificar a saída de compilação, correlacionar com as alterações recentes e decidir se deseja reverter ou corrigir para frente.
O contexto está disperso: o alerta do Datadog diz: "Pico de CPU na prod-api". A causa raiz requer a correlação de logs de três serviços, verificação de implantações recentes e revisão de rastreamentos do Dynatrace.

Como funcionam os gatilhos HTTP

Os gatilhos HTTP permitem que você conecte qualquer ferramenta que dê suporte a webhooks diretamente à sua instância do Agente SRE. Em vez de um engenheiro realizar a triagem manual, o sistema que detectou o problema, seja um alerta do Datadog, uma anomalia do Dynatrace, uma transição de fluxo de trabalho no Jira ou uma falha de pipeline, instrui o agente a investigar. O contexto é passado automaticamente.

Cada gatilho é um ponto de extremidade de webhook nomeado em seu agente com uma URL exclusiva. Quando um sistema externo chama essa URL via HTTP POST, o agente executa o prompt configurado do gatilho, que é enriquecido com quaisquer dados JSON no corpo da solicitação.

Conceitos principais

Conceito	Como funciona
Gatilho	Um ponto de extremidade nomeado com um prompt, um agente designado (padrão ou subagente) e um nível de autonomia (autônomo ou revisão).
URL do acionador	O URL exclusivo de webhook que é gerado quando você cria um gatilho. Esse URL do webhook é chamado pelas ferramentas externas.
Contexto JSON	Corpo JSON opcional enviado com a solicitação `POST` . Isso se torna parte do prompt do agente para fornecer contexto completo.
Histórico de execução	Cada invocação é registrada com um carimbo de data/hora, um link de thread e um status de êxito ou falha.
Habilitar/desabilitar	Ative ou desative gatilhos sem precisar excluir. Os gatilhos desabilitados disparam um erro 404.

Invocar um gatilho

Chame a URL do gatilho com uma solicitação 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	O que é
URL	O ponto de extremidade de webhook único do gatilho. Localize-o na exibição de detalhes do gatilho na URL do Gatilho.
Authorization	Um token de portador do Azure Resource Manager. Consulte Autenticação para invocação de gatilho.
Tipo de conteúdo	Deve ser `application/json` se você estiver enviando um corpo JSON.
Corpo JSON (opcional)	Todos os dados JSON que você deseja que o agente veja. Esses dados se tornam parte do prompt do agente. Inclua qualquer contexto que ajude o agente a investigar, como nome do alerta, gravidade e serviço afetado.

O corpo JSON é opcional. Se o gatilho for chamado sem um corpo, o agente executará apenas o prompt configurado do gatilho. Com um texto, o agente vê o prompt e os dados que você enviou.

Autenticação para invocação de gatilho

O ponto de extremidade do gatilho requer um token Portador do Azure Resource Manager no cabeçalho Authorization: Bearer <TOKEN>. O chamador precisa de permissão Microsoft.App/agents/threads/write no recurso do agente.

Maneiras de obter um token

Método	Mais adequado para	Detalhes
Service Principal	Pipelines de CI/CD, sistemas automatizados	Crie um registro de aplicativo, atribua a função no recurso do agente e use o fluxo de credenciais do cliente para obter um token.
Identidade gerenciada	Serviços hospedados no Azure (Azure Functions, Máquinas Virtuais do Azure, Aplicativos de Contêiner do Azure)	Nenhum segredo a ser gerenciado. O recurso do Azure é autenticado automaticamente.
CLI do Azure	Teste e desenvolvimento	Execute `az account get-access-token --resource https://management.azure.com --query accessToken -o tsv`.

Conectar ferramentas externas que não dão suporte à autenticação do Azure

Ferramentas como Datadog, Dynatrace, Jira e Splunk enviam webhooks com seus próprios formatos de autenticação, não tokens do Azure Resource Manager. Para preencher a lacuna, use um dos seguintes intermediários.

Intermediário	Como funciona
Azure Functions	Recebe o webhook, adquire um token do Azure Resource Manager usando sua identidade gerenciada e encaminha a chamada para a URL do gatilho.
Aplicativos Lógicos do Azure	Fluxo de trabalho sem necessidade de codificação que recebe webhooks de qualquer origem e chama APIs do Azure com autenticação nativa do Azure Resource Manager.
Gerenciamento de API do Azure	Posiciona-se na frente da URL de gatilho e trata a validação e a transformação de token por meio de políticas.

Resposta

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

O gatilho retorna HTTP 202 (Aceito) imediatamente. O agente processa a solicitação de forma assíncrona.

O que torna essa abordagem diferente

Os gatilhos HTTP conectam seus alertas e ferramentas de CI/CD existentes diretamente ao seu agente sem a intervenção de um engenheiro. O sistema que detectou o problema informa ao agente para investigar o problema e fornece automaticamente o contexto completo. Não há necessidade de paginação, troca de painéis ou coleta manual de contexto.

Antes e depois

Antes (triagem manual)	Após (gatilhos HTTP)
Alertas do Datadog são acionados. O engenheiro é acionado, abre três painéis e começa a investigar.	O webhook do Datadog chama o gatilho. O agente investiga e posta descobertas automaticamente.
Interrupções no pipeline. O engenheiro verifica os logs de build, revisa PRs e decide a próxima etapa.	O manipulador de falhas do pipeline chama o gatilho. O agente analisa a falha e posta a causa raiz.
O Dynatrace detecta anomalias. O engenheiro correlaciona manualmente os serviços.	O webhook do Dynatrace chama o gatilho com contexto de anomalia. O agente correlaciona logs, métricas e implantações.

Tarefas agendadas versus gatilhos HTTP

Tarefas agendadas	Gatilhos HTTP
Baseado em tempo (agendamento cronológico).	Baseado em eventos (sob demanda).
Executa de forma independente aconteça ou não algo.	É executado somente quando chamado.
Nenhuma entrada externa por execução.	Dados de payload injetados em cada invocação.
Melhor para verificações recorrentes.	Melhor para reações controladas por eventos.

Use ambos juntos. Use tarefas agendadas para monitoramento proativo e gatilhos HTTP para tratamento de eventos reativos.

Casos de uso

Integração de pipeline de CI/CD

Quando ocorrer falha em um pipeline de entrega, invoque o agente para analisar a falha:

# 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\"}"

Investigação orientada por alertas

Conecte seu sistema de alertas para disparar uma investigação automatizada quando alertas críticos forem acionados:

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

Verificações de conformidade de implantação

Após a conclusão de uma implantação, dispare uma revisão de conformidade:

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

Referência de API

Ponto final	Método	Descrição
`/api/v1/httptriggers`	`GET`	Listar todos os gatilhos.
`/api/v1/httptriggers/create`	`POST`	Crie um novo gatilho.
`/api/v1/httptriggers/{id}`	`GET`	Obter detalhes do gatilho.
`/api/v1/httptriggers/{id}`	`PUT`	Atualize as propriedades do gatilho.
`/api/v1/httptriggers/{id}`	`DELETE`	Exclua um gatilho.
`/api/v1/httptriggers/{id}/enable`	`POST`	Habilitar um gatilho.
`/api/v1/httptriggers/{id}/disable`	`POST`	Desabilite um gatilho.
`/api/v1/httptriggers/{id}/execute`	`POST`	Execute um gatilho manualmente.
`/api/v1/httptriggers/{id}/executions`	`GET`	Obter o histórico de execução.
`/api/v1/httptriggers/trigger/{id}`	`POST`	Ponto de extremidade de webhook externo.

Solução de problemas

Acionador retorna 404

Verifique se o gatilho está definido como habilitado. Os gatilhos desabilitados disparam um erro 404.
Verifique se a ID do gatilho na URL está correta.

401 Não autorizado

O público-alvo do token deve corresponder à ID do aplicativo do Agente SRE, e não a https://management.azure.com.
Para obter um token para teste, use az account get-access-token --resource 59f0a04a-b322-4310-adc9-39ac41e9631e --query accessToken -o tsv.

O gatilho é executado, mas o agente não age

Verifique o prompt do agente. Um prompt vazio pode não produzir uma saída útil.
Verifique se o subagente escolhido tem as ferramentas necessárias para a tarefa.
Verifique o histórico de execução para obter detalhes de erro.

Limits

Recurso	Limit
Gatilhos por agente	Sem limite rígido.
Máximo de turnos por execução	250 voltas.
Authentication	O token Portador é necessário para cada URL de gatilho.

Comentários

Esta página foi útil?

Last updated on 2026-05-01