HTTP triggers no Azure SRE Agent

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

O problema: Alertas e falhas de oleodutos precisam de triagem manual

A sua equipa já dispõe de ferramentas de alerta, observabilidade e fluxos de trabalho como Datadog, Dynatrace, Jira, Splunk e Grafana, além de pipelines CI/CD que falham. Quando algo corre mal, a resposta é sempre a mesma:

Um engenheiro é chamado: O engenheiro abre a ferramenta de monitorização, lê o alerta e depois abre manualmente registos, métricas e histórico de implementação em vários dashboards para perceber o que aconteceu.
Um pipeline falha: Alguém tem de parar o que está a fazer, verificar a saída da build, correlacionar com as alterações recentes e decidir se reverte ou corrige para avançar.
O contexto é disperso: O alerta do Datadog diz: "Pico de CPU na prod-api." A causa raiz requer correlacionar registos de três serviços, verificar implementações recentes e rever os traces do Dynatrace.

Como funcionam os gatilhos HTTP

Os gatilhos HTTP permitem-te ligar qualquer ferramenta que suporte webhooks diretamente à tua instância do SRE Agent. Em vez de um engenheiro fazer triagem manual, o sistema responsável pela deteção do problema, seja um alerta Datadog, uma anomalia Dynatrace, uma transição de fluxo de trabalho Jira ou uma falha no pipeline, indica ao agente para investigar. O contexto é transmitido automaticamente.

Cada trigger é um endpoint webhook nomeado no seu agente com uma URL única. Quando um sistema externo chama essa URL via HTTP POST, o agente executa o prompt configurado do trigger, que é enriquecido com quaisquer dados JSON no corpo do pedido.

Conceitos-chave

Conceito	Como funciona
Trigger	Um endpoint designado com um prompt, um agente atribuído (predefinido ou subagente) e um nível de autonomia (autónomo ou de revisão).
URL do gatilho	O URL único do webhook que é gerado quando crias um gatilho. Este URL do webhook é o que as ferramentas externas utilizam.
Contexto JSON	Corpo JSON opcional enviado com a `POST` requisição. Torna-se parte do enunciado do agente para ter todo o contexto.
Histórico de execuções	Cada invocação é registada com um carimbo temporal, ligação à thread e estado de sucesso ou falha.
Ativar/desativar	Alternar os gatilhos entre ativado e desativado sem os eliminar. Os gatilhos desativados devolvem o 404.

Invocar um gatilho

Chame o URL do gatilho com uma requisiçã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 endpoint exclusivo do webhook associado ao gatilho. Encontre-o na vista de detalhe do gatilho, na rubrica URL do gatilho.
Authorization	Um token portador Azure Resource Manager. Veja Autenticação para invocação de gatilho.
Tipo de conteúdo	Deve ser `application/json` se estiveres a enviar um corpo JSON.
Corpo JSON (opcional)	Quaisquer dados JSON que queiras que o agente veja. Estes dados tornam-se parte do prompt do agente. Inclua qualquer contexto que ajude o agente a investigar, como o nome do alerta, gravidade e serviço afetado.

O corpo JSON é opcional. Se chamares o trigger sem um corpo, o agente executa apenas com o prompt configurado do trigger. Ao ter um corpo, o agente vê tanto o prompt como os dados que enviaste.

Autenticação para invocação de gatilho

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

Formas de obter um token

Método	Melhor para	Detalhes
Serviço principal	Pipelines de CI/CD, sistemas automatizados	Crie um registo de aplicação, atribua o papel ao recurso do agente e use o fluxo de credenciais do cliente para obter um token.
Identidade gerenciada	Serviços hospedados em Azure (Azure Functions, Azure Virtual Machines, Azure Container Apps)	Sem segredos para gerir. O recurso Azure autentica-se automaticamente.
Azure CLI (Interface de Linha de Comando da Azure)	Testes e desenvolvimento	Execute `az account get-access-token --resource https://management.azure.com --query accessToken -o tsv`.

Ligue ferramentas externas que não suportem autenticação Azure

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

Intermédio	Como funciona
Funções do Azure	Recebe o webhook, adquire um token Azure Resource Manager usando a sua identidade gerida e encaminha a chamada para o URL do trigger.
Aplicativos Lógicos do Azure	Fluxo de trabalho sem código que recebe webhooks de qualquer fonte e chama APIs do Azure com autenticação incorporada do Azure Resource Manager.
Gestão de API do Azure	Coloca-se à frente do URL de gatilho e realiza a validação e transformação de tokens através de políticas.

Resposta

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

O gatilho devolve imediatamente HTTP 202 (Aceite). O agente processa o pedido de forma assíncrona.

O que torna esta abordagem diferente

Os gatilhos HTTP ligam as suas ferramentas de alertas e CI/CD existentes diretamente ao seu agente, sem um engenheiro envolvido. O sistema que detetou o problema diz ao agente para investigar e transmite automaticamente todo o contexto. Não há paginação, nem troca de dashboard, nem recolha manual de contexto.

Antes e depois

Antes (triagem manual)	Depois (Gatilhos HTTP)
Alerta do Datadog é acionado. O engenheiro é chamado, abre três dashboards e começa a investigar.	As chamadas de webhook do Datadog disparam. O agente investiga e publica automaticamente as conclusões.
A tubagem rompe-se. O engenheiro verifica os logs de construção, revê PRs e decide o próximo passo.	O handler de falha do pipeline chama o acionador. O agente analisa a falha e publica a causa raiz.
Dynatrace deteta anomalia. O engenheiro faz a correlação manualmente entre serviços.	As chamadas de webhook do Dynatrace são acionadas com o contexto da anomalia. O agente correlaciona logs, métricas e implementações.

Tarefas agendadas vs. gatilhos HTTP

Tarefas agendadas	Gatilhos HTTP
Baseado no tempo (calendário cronológico).	Orientado a eventos (sob demanda).
Corre independentemente de algo ter acontecido ou não.	Só funciona quando é chamado.
Sem entrada externa por execução.	Dados da carga útil injetados em cada invocação.
É ideal para verificações recorrentes.	Ideal para reações orientadas por eventos.

Usa ambos juntos. Use tarefas agendadas para monitorização proativa e gatilhos HTTP para gestão reativa de eventos.

Casos de uso

Integração de pipelines CI/CD

Quando um pipeline de implementação falha, invoque o agente para efetuar a análise da 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 o seu sistema de alertas para desencadear uma investigação automática quando um alerta crítico for emitido:

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

Verificações de conformidade de implementação

Após a conclusão de uma implementação, desencadeie 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 da API

Ponto final	Método	Descrição
`/api/v1/httptriggers`	`GET`	Lista todos os gatilhos.
`/api/v1/httptriggers/create`	`POST`	Cria um novo gatilho.
`/api/v1/httptriggers/{id}`	`GET`	Obtenha detalhes do gatilho.
`/api/v1/httptriggers/{id}`	`PUT`	Atualizar as propriedades dos gatilhos.
`/api/v1/httptriggers/{id}`	`DELETE`	Exclua um gatilho.
`/api/v1/httptriggers/{id}/enable`	`POST`	Ativar um gatilho.
`/api/v1/httptriggers/{id}/disable`	`POST`	Desative um gatilho.
`/api/v1/httptriggers/{id}/execute`	`POST`	Usa um gatilho manualmente.
`/api/v1/httptriggers/{id}/executions`	`GET`	Obtenha o histórico de execuções.
`/api/v1/httptriggers/trigger/{id}`	`POST`	Endpoint de webhook externo.

Troubleshooting

O acionador retorna 404

Verifica se o disparador está habilitado. Os gatilhos desativados devolvem o 404.
Verifica se o ID do acionador na URL está correto.

401 Não autorizado

A audiência do token deve corresponder ao ID da aplicação SRE Agent, não https://management.azure.com.
Para obter um token para testar, use az account get-access-token --resource 59f0a04a-b322-4310-adc9-39ac41e9631e --query accessToken -o tsv.

O gatilho executa, mas o agente não age

Verifica o prompt do agente. Um prompt vazio pode não produzir resultados úteis.
Verifique se o subagente escolhido tem as ferramentas necessárias para a tarefa.
Verifique o histórico de execução para detalhes de erros.

Limits

Recurso	Limit
Gatilhos por agente	Sem limite rígido.
Turnos máximos por execução	250 voltas.
Authentication	É necessário um token portador para cada URL de gatilho.

Comentários

Esta página foi útil?

Last updated on 2026-04-22