Configuração de Alertas do Agente

O que Configuração de Alertas do Agente faz?

Projete a automação, configure o webhook hospedado e entregue as execuções de runtime para $agent-alerts-execution. Não envie durante a configuração, a menos que o usuário solicite um teste de fumaça.

Comece Aqui

Abra ou direcione o usuário para:

https://www.andreas.ink/agent

Siga o fluxo de conexão atual da página com o Agent Alerts no iPhone. Ele cria um token exclusivo de publicação para o runtime. Não peça ao usuário para colar esse token no chat.

Configure o Webhook

1. Nomeie o runtime e conclua o fluxo de conexão na página pública de configuração.
2. Escolha o local do token para o runtime:
   • Runtime hospedado: armazene o token único no gerenciador de segredos desse runtime como AGENTALERTS_AGENT_TOKEN.
   • Mac local: armazene exatamente uma linha, AGENTALERTS_AGENT_TOKEN=<token>, no arquivo ~/.config/agent-alerts/token.env aprovado pelo usuário e defina seu modo como 0600.
3. Faça o usuário inserir o token diretamente no armazenamento de segredos selecionado, fora da conversa com o agente. Nunca peça para ele colar no chat do agente.
4. Use o endpoint integrado em ../agent-alerts-execution/scripts/send_webhook.sh. Defina AGENTALERTS_WEBHOOK_URL apenas quando a página de configuração fornecer um endpoint HTTPS diferente.
5. Permita HTTPS de saída apenas para esse endpoint.
6. Autorize o caminho absoluto exato para send_webhook.sh para execuções não supervisionadas. Não conceda acesso amplo ao shell.

Nunca coloque o token em um prompt, URL, string de consulta, log, arquivo fonte, arquivo de configuração rastreado, histórico do shell ou argumento de comando.

Prepare e Valide um Teste

Copie ../agent-alerts-execution/assets/compact-webhook-payload.json para um arquivo de payload gravável e substitua seus valores de exemplo. Use uma chave de idempotência estável e única para o evento.

Valide o payload:

../agent-alerts-execution/scripts/send_webhook.sh --check payload.json

Valide o payload, a origem do token, as permissões e o endpoint sem enviar:

../agent-alerts-execution/scripts/send_webhook.sh --check-config payload.json

Em seguida, envie um teste de fumaça não sensível:

../agent-alerts-execution/scripts/send_webhook.sh payload.json

Para uma automação não supervisionada, repita --check-config e o envio de fumaça a partir do runner real salvo. Ambos devem ser concluídos sem um prompt de aprovação. Se o runner não puder executar o helper exato ou alcançar o endpoint, pare com AGENTALERTS_SCRIPT_NOT_AUTHORIZED.

Projete o Alerta

Defina:

1. Sinal, fonte de dados e gatilho.
2. Mapeamentos de good, warning e critical.
3. Condições de pulo, horários de silêncio e exclusões.
4. Um activity_id estável ou identificador de notificação.
5. Superfícies: live_activity, widget e/ou notification.
6. Texto da ação e uma URL de destino segura ou deep link do aplicativo.
7. Um agendador durável quando o alerta for executado mais tarde ou repetidamente.

O Agent Alerts entrega atualizações; ele não mantém uma sessão de agente ativa. Uma execução futura ou recorrente está incompleta até que o agendador permaneça registrado após o fechamento da sessão atual. Caso contrário, retorne AGENTALERTS_SCHEDULER_NOT_DURABLE.

Contrato do Payload

Use o corpo do webhook compacto para alertas comuns:

{
  "title": "Build finalizado",
  "summary": "Todos os testes passaram.",
  "status": "good",
  "activity_id": "build-monitor",
  "source_name": "Codex",
  "surfaces": ["live_activity", "notification"],
  "idempotency_key": "build-monitor-2026-07-29T18-30-00Z"
}

O webhook requer:

Authorization: Bearer <AGENTALERTS_AGENT_TOKEN>
Content-Type: application/json
Idempotency-Key: <mesmo valor que idempotency_key>

O helper fornece esses cabeçalhos sem expor o token nos argumentos do processo. Sempre use o helper; não recrie a requisição manualmente.

Envios compactos padrão criam uma atividade upsert nomeada webhook, entrega em produção e live_activity mais notification quando esses campos são omitidos. Defina-os explicitamente quando a automação precisar de um resultado diferente.

Para widgets, estado do Widget de Controle, layouts de construtor ou outros campos avançados, use o contrato completo do webhook em snake_case com um objeto payload aninhado. Não misture um objeto payload completo com campos compactos title, summary, status, source_name ou deep_link.

Regras de Cópia e Entrega

Mantenha o texto visível completo e dentro destes limites:

Campo	Caracteres máximos
source_name	14
title	32
summary	96

Não confie em truncamento ou adicione reticências.

• live_activity atualiza a Dynamic Island ou a Tela de Bloqueio.
• widget precisa do seu identificador de widget, um pequeno snapshot não secreto e recarregamento ativado.
• notification precisa de um identificador de thread estável para agrupamento.
• O estado do Widget de Controle deve ser verdadeiro para estados ativos de aviso ou crítico e falso para estados limpos ou resolvidos.

Handoff do Runtime

Escreva uma instrução de runtime exata:

Use $agent-alerts-execution. Avalie primeiro a condição de pulo configurada.
Se um envio for necessário, escreva o JSON preparado do Agent Alerts no caminho
do payload aprovado, então invoque o caminho autorizado do send_webhook.sh com
esse arquivo. Leia o token apenas de AGENTALERTS_AGENT_TOKEN ou do arquivo
token.env aprovado. Relate o status retornado e o alvo, sucesso e falha
sem imprimir segredos.

A configuração está completa apenas quando o runner real valida a configuração e envia sem interação, o agendador é durável quando necessário, e o resultado é relatado sem exagerar a entrega visível no dispositivo.