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

> Deixe o agente pausar antes de qualquer ação irreversível, envie um botão Aprovar no seu celular e aguarde o toque. Um endpoint de aprovação de 25 linhas, um auxiliar em Python e os limites que vale conhecer.

*13.10.2026*

<!-- source: https://pocketalert.app/pt/blog/human-in-the-loop-notifications -->

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:

1. O agente chega a uma etapa arriscada e cria uma solicitação com um ID aleatório.
2. Ele envia uma notificação push do Pocket Alert com dois [botões de ação](https://info.pocketalert.app/features/action-buttons.html). Cada botão é uma requisição HTTP para o seu endpoint de aprovação, levando esse ID.
3. 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.
4. 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](/account/apikeys), 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:

```js
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.

```python
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:

```python
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](/use-cases/ai-agent-alerts) 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](/tools/mcp) 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](/blog/claude-code-push-notifications) ou no [Codex](/blog/codex-notifications). 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 `view` que 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](/signup), faça o deploy do endpoint e dê ao seu agente um jeito de perguntar antes de agir.
