Notificações push com aprovação humana: aprove um agente de IA pelo celular

Um agente que pode fazer deploy, reembolsar, apagar ou enviar e-mails sozinho é útil até o momento em que faz uma dessas coisas de forma errada. A solução não é impedi-lo de agir. É fazer com que ele pergunte antes, e tornar a pergunta simples o bastante para que você realmente responda.
Human-in-the-loop significa exatamente isso: o agente para em um checkpoint, uma pessoa aprova ou recusa, e o agente segue com a resposta. A parte difícil não é a lógica. É fazer a pergunta chegar até você quando você não está na mesa, e receber sua resposta sem precisar de um notebook.
Este guia faz isso com uma notificação push que traz um botão Aprovar. O agente envia a notificação, aguarda e lê a sua decisão em um pequeno endpoint que o botão chama.
Como funciona o ciclo
Quatro partes, todas pequenas:
- O agente chega a uma etapa arriscada e cria uma solicitação com um ID aleatório.
- Ele envia uma notificação push do Pocket Alert com dois botões de ação. Cada botão é uma requisição HTTP para o seu endpoint de aprovação, levando esse ID.
- Você toca na notificação, lê o que o agente quer fazer e toca em Aprovar ou Recusar. O seu celular chama o endpoint diretamente.
- O agente consulta o endpoint, vê a decisão e segue em frente ou para.
Se ninguém responder antes do tempo limite, o agente trata a resposta como não. Uma etapa de aprovação que assume "sim" por padrão é apenas uma notificação, não uma proteção.
O que você precisa
- Uma conta no Pocket Alert com um plano pago. Os botões de ação são removidos das mensagens no plano gratuito, então a notificação chegaria sem eles. O plano Starter custa US$ 6 por mês.
- Uma chave de API em Chaves de API, de preferência uma separada para o agente.
- Um lugar para rodar um pequeno endpoint HTTPS que o seu celular consiga acessar. O exemplo usa um Cloudflare Worker, que é gratuito nesse volume; qualquer servidor funciona.
Passo 1. O endpoint de aprovação
O endpoint faz duas coisas: registra uma decisão quando o celular o chama e informa essa decisão quando o agente pergunta. Este Worker mantém as decisões no Workers KV por uma hora:
export default {
async fetch(request, env) {
if (request.headers.get('X-Approval-Secret') !== env.SECRET) {
return new Response('forbidden', { status: 403 });
}
const [, action, id] = new URL(request.url).pathname.split('/');
if (!/^[a-f0-9]{32}$/.test(id ?? '')) {
return new Response('bad id', { status: 400 });
}
if (request.method === 'POST' && (action === 'approve' || action === 'decline')) {
const existing = await env.DECISIONS.get(id);
if (!existing) await env.DECISIONS.put(id, action, { expirationTtl: 3600 });
return new Response(existing ?? action);
}
if (request.method === 'GET' && action === 'status') {
return new Response((await env.DECISIONS.get(id)) ?? 'pending');
}
return new Response('not found', { status: 404 });
},
};
Vincule um namespace KV como DECISIONS, adicione um SECRET longo e aleatório como secret do Worker e faça o deploy. Três detalhes são intencionais:
- A primeira resposta vale. Um segundo toque, ou um toque no outro botão, não consegue reverter uma decisão já registrada. O Pocket Alert não bloqueia toques repetidos em um botão
http, então o endpoint precisa fazer isso. - O segredo viaja em um header, configurado dentro do próprio botão. O celular envia, o agente envia, e mais ninguém tem acesso a ele.
- As decisões expiram. Uma aprovação de ontem não deve liberar nada hoje.
O Workers KV é eventualmente consistente, então o agente pode não ver uma decisão até 60 segundos ou mais depois do seu toque. Para uma etapa de aprovação isso está ok; se você precisar de resposta instantânea, qualquer servidor com banco de dados ou um Durable Object faz o mesmo trabalho.
Passo 2. Pergunte a partir do agente
O auxiliar abaixo envia a notificação, consulta uma decisão e retorna True somente com uma aprovação explícita. Ele funciona em qualquer agente Python: uma ferramenta do LangChain, uma função do OpenAI Agents SDK ou um loop simples.
import json
import os
import time
import uuid
import requests
PUSH_API = "https://api.pocketalert.app/v1/messages"
APPROVALS = "https://approvals.YOUR_SUBDOMAIN.workers.dev"
SECRET = os.environ["APPROVAL_SECRET"]
def ask_human(title: str, details: str, timeout: int = 900) -> bool:
request_id = uuid.uuid4().hex
def button(label: str, action: str) -> dict:
return {
"type": "http",
"label": label,
"value": json.dumps({
"url": f"{APPROVALS}/{action}/{request_id}",
"method": "POST",
"headers": {"X-Approval-Secret": SECRET},
}),
}
requests.post(
PUSH_API,
headers={"Token": os.environ["POCKETALERT_API_KEY"]},
json={
"title": title,
"message": details,
"level": "high",
"actions": [button("Approve", "approve"), button("Decline", "decline")],
},
timeout=10,
).raise_for_status()
deadline = time.time() + timeout
while time.time() < deadline:
status = requests.get(
f"{APPROVALS}/status/{request_id}",
headers={"X-Approval-Secret": SECRET},
timeout=10,
).text
if status in ("approve", "decline"):
return status == "approve"
time.sleep(5)
return False
Depois, coloque isso antes de qualquer ação que você não gostaria que o agente fizesse sem supervisão:
if ask_human("Deploy to production?", "build #482 · 14 files · all checks green"):
deploy()
else:
report("Deploy skipped: not approved")
level: "high" envia a notificação como sensível ao tempo, então ela atravessa o Foco no iPhone e aparece como notificação flutuante no Android. Uma aprovação que você vê uma hora depois é uma aprovação pela qual o agente esperou uma hora.
O que você vê no celular
A notificação chega com o título e os detalhes escritos pelo agente, e Aprovar e Recusar diretamente na notificação. Mantenha pressionado no iPhone ou expanda no Android e toque em um deles: a requisição é enviada em segundo plano, sem abrir o app, mesmo que o Pocket Alert esteja fechado. Os mesmos botões também aparecem dentro da mensagem no app, onde um aviso mostra o código de status que o seu endpoint retornou.
Dois detalhes de plataforma valem a pena conhecer antes de depender disso:
- Se a requisição falhar, porque o seu endpoint retornou um erro ou o celular estava sem rede, uma nova notificação aparece com um botão Tentar novamente. Uma requisição que pode ter chegado ao seu endpoint nunca é repetida automaticamente, então um toque não consegue aprovar duas vezes pelas suas costas.
- Botões nas notificações do sistema exigem o app Pocket Alert 2.0.1 ou posterior. Em versões antigas, o banner não tem botões e eles ficam esperando dentro da mensagem. Os seus rótulos são exibidos como escritos nas duas plataformas; se o iOS não conseguir preparar botões personalizados a tempo, ele usa o rótulo genérico Executar para
http, e o botão continua funcionando.
Onde colocar os checkpoints
Perguntar com muita frequência faz você começar a aprovar sem ler. Bons checkpoints são as ações difíceis de desfazer ou que custam dinheiro de verdade:
- Deploys e migrações de banco de dados em produção
- Envio de e-mails, publicação pública ou mensagens para clientes
- Reembolsos, compras e qualquer coisa que chame uma API de pagamento
- Exclusão de dados, rotação de chaves, alteração de DNS ou de permissões
- Execuções que vão gastar mais que um limite definido de tokens ou de orçamento na nuvem
Todo o resto funciona melhor como uma notificação simples depois do fato. A página alertas de agentes de IA cobre esse lado: concluído, falhou, travado.
Fazendo isso pelo MCP
Se o agente roda em um cliente MCP, ele pode enviar a mesma notificação sem o auxiliar em Python. O servidor MCP do Pocket Alert expõe create_message com um parâmetro actions, então você pode instruir o agente a chamá-lo com os dois botões e depois consultar a URL de status antes de continuar.
Isso funciona, com uma ressalva: agora o agente é responsável por esperar, e um modelo instruído a aguardar aprovação ainda pode decidir não esperar. Para o que importa, imponha o checkpoint em código que o modelo não consiga pular, como o auxiliar acima ou um hook de permissão no Claude Code ou no Codex. Use a rota MCP para a pergunta e o código para o portão.
Variações
- Botão único. Envie apenas Aprovar e deixe o silêncio significar não. Assim não há nada para tocar errado no banner, e recusar não custa nada.
- Ferramentas de workflow. No n8n, um nó Wait configurado para retomar com uma chamada de webhook fornece uma URL de retomada; coloque-a no botão Aprovar e o workflow continua quando você tocar.
- Contexto na notificação. Coloque os números na mensagem: o valor, o ambiente, a quantidade de linhas. Você deve conseguir decidir somente com o texto.
- Um botão de visualização. Substitua Recusar por um botão
viewque abre o diff, a fatura ou a execução, e recuse simplesmente não aprovando.
FAQ
A aprovação funciona pela tela de bloqueio?
Sim. Os botões http executam pela tela de bloqueio sem desbloquear o celular, esteja o Pocket Alert aberto, em segundo plano ou fechado. No Android isso exige uma tela de bloqueio configurada para mostrar o conteúdo das notificações; se ela ocultar o conteúdo, os botões aparecem depois que você desbloquear. Se isso for fácil demais para uma ação arriscada, coloque a decisão atrás de um botão view que abre uma página na qual você precisa entrar; abrir uma página pede o desbloqueio antes.
É seguro?
A requisição do botão vai do seu celular direto para o seu endpoint; o Pocket Alert não faz proxy dela nem vê a resposta. Proteja o endpoint com um header secreto, use um ID aleatório por requisição, aceite somente a primeira resposta e faça as decisões expirarem. As mensagens, incluindo a configuração dos botões, são criptografadas em repouso.
O que acontece se eu nunca responder?
O auxiliar retorna False após o tempo limite, 15 minutos por padrão, e o agente deve tratar isso como recusa. Escolha um tempo limite compatível com o quanto a tarefa pode razoavelmente esperar.
Mais de uma pessoa pode aprovar?
Todos os dispositivos da conta recebem a notificação, e o primeiro toque vale. Para aprovações individuais, envie a cada pessoa a sua própria notificação com um ID de requisição separado e decida no endpoint quantas aprovações são necessárias.
Funciona no Android e no iPhone?
Sim, nas duas plataformas, com os seus próprios rótulos na notificação e dentro da mensagem. Botões nas notificações do sistema exigem a versão 2.0.1 do app ou posterior.
Obtenha uma chave de API, faça o deploy do endpoint e dê ao seu agente um jeito de perguntar antes de agir.