Onde colocar uma checagem de decisão num agente de IA (e onde ela só atrapalha)

Fala aí, beleza? Se o teu agente quebra, quase sempre é no mesmo lugar: na hora em que ele decide sozinho algo que não devia 🙂

Deixar o modelo improvisar a decisão final é pedir pra ver o agente mandando email errado, apagando o que não devia ou acionando gente à toa

O padrão que resolve isso é bem direto: o agente gera, a decisão filtra ou aprova

Porém tem um porém (haha): checagem em todo lugar também quebra o agente, só que de outro jeito

Então este post tem duas metades: onde a checagem paga a conta e onde ela só gera atrito

Bora ver na prática?

O que você precisa entender antes de desenhar os pontos de decisão:

Antes de sair colocando aprovação em agentes de IA, vale separar duas coisas que muita gente mistura

A Anthropic diferencia workflow de agente (o resumo do Simon Willison sobre o guia Building Effective Agents é ótimo pra isso):

• Workflow: LLMs e ferramentas orquestrados por um caminho predefinido em código
• Agente: o próprio LLM dirige o processo e decide quais ferramentas usar

E por que isso importa?

Porque no workflow a decisão pode morar no código, num if que você controla

Já no agente o caminho é decidido pelo modelo, então a checagem precisa ficar na fronteira das ações, no momento em que ele tenta fazer alguma coisa

O segundo conceito é o human-in-the-loop: o agente propõe uma ação e uma pessoa aprova, edita ou rejeita antes que ela aconteça

Nada irreversível acontece sem esse aval

É como ter um estagiário muito rápido que prepara tudo, mas só aperta o botão de enviar depois que você dá o ok 😀

Por fim: tenha um fluxo de agente já desenhado, nem que seja no papel, com a lista das ações que ele executa

Sem essa lista não tem como decidir onde a checagem entra

Como encaixar uma decisão no fluxo do agente, passo a passo:

1. Mapeie as ações e classifique cada uma por risco, reversibilidade e sensibilidade

A regra de ouro: a autoridade humana fica onde o erro sai caro, é irreversível, tem peso jurídico, envolve segurança ou é difícil de detectar

Ler um arquivo é reversível e barato, apagar uma tabela não é

O erro comum deste passo: classificar pelo "parece perigoso" em vez de perguntar "dá pra desfazer?". Muita ação que assusta é reversível e muita ação boba não é

2. Marque os três pontos clássicos de checagem

– Antes de enviar: tudo que chega ao usuário ou a terceiros (resposta, email, mensagem) – Antes de gravar: escrita, deleção ou alteração de dados – Antes de escalar: acionar outra pessoa, outro sistema ou um gasto

O erro comum deste passo: esquecer o "escalar". O agente que abre ticket, chama outra API ou dispara uma cobrança está tomando uma decisão tão séria quanto apagar dado

3. Escolha o tipo de decisão para cada ponto

Não é tudo aprovação humana, se liga nas opções:

– Regra fixa em código: quando dá pra escrever a condição (bloquear deleção em massa, por exemplo) – Avaliador automático (evaluator-optimizer): uma chamada de LLM gera, outra avalia e devolve feedback em loop. Funciona melhor quando há critério claro de avaliação – Guardrail em paralelo: um modelo processa a consulta enquanto outro filtra em busca de conteúdo inadequado – Aprovação humana: pro caro, irreversível e sensível

O erro comum deste passo: usar avaliador LLM sem critério claro. Aí tu tem dois modelos improvisando em vez de um xD

E quando o avaliador reprova, o agente tenta de novo ou para? Isso é assunto de failure recovery em agentes, e vale desenhar junto

4. Implemente no Claude Code com hook PreToolUse

Os hooks do Claude Code são configurados no settings.json, nos níveis de usuário, projeto ou local

O hook PreToolUse roda antes da chamada da ferramenta e tem dois jeitos de decidir

O primeiro é sair com exit code 2: isso bloqueia a chamada e devolve o stderr ao Claude, então ele sabe o motivo

#!/bin/bash
# hook PreToolUse: barra uma ação sensível antes de gravar
# ACAO_SENSIVEL é só um marcador: troque pela sua regra de detecção

if [ "$ACAO_SENSIVEL" = "sim" ]; then
  echo "Ação bloqueada: deleção em massa precisa de revisão humana" >&2
  exit 2
fi

exit 0

Exit 0 deixa seguir normalmente

O segundo jeito é devolver um JSON com permissionDecision dentro de hookSpecificOutput:

{
  "hookSpecificOutput": {
    "permissionDecision": "ask"
  }
}

Os valores possíveis:

– deny: impede a chamada e mostra o motivo ao Claude – ask: pede confirmação ao usuário na interface – allow: pula o sistema de permissão

Se o hook não devolver nada, vale o fluxo de permissão normal

O erro comum deste passo: usar allow no atacado pra "parar de encher o saco". Ele pula a permissão, então só use pra ação que tu já classificou como rotineira e reversível. Confira os demais campos do JSON na doc antes de colocar em produção

5. Implemente no Claude Agent SDK entendendo a ordem de avaliação

No SDK, as permissões são avaliadas nesta ordem:

hook PreToolUse, regras deny, regras allow, regras ask, modo de permissão, callback canUseTool e, depois da execução, hook PostToolUse

Os modos de permissão disponíveis são default, acceptEdits, bypassPermissions, plan, dontAsk e auto (no auto, um classificador avalia as ações, e mais abaixo te conto o que ele aprova e o que ele bloqueia)

E o canUseTool? Ele é a aprovação em runtime: só é chamado quando a avaliação termina num prompt, e pausa a execução até a sua aplicação responder

Ferramenta já aprovada por allowedTools, por regra allow ou pelo modo de permissão nem passa por ele

O erro comum deste passo: colocar a lógica crítica só no canUseTool e depois liberar a ferramenta numa regra allow. Ela nunca chega no callback, e tua checagem vira enfeite. Tome cuidado!

6. Implemente no OpenAI Agents SDK com needsApproval e guardrails

No OpenAI Agents SDK, a ferramenta sensível recebe needsApproval: true

Quando o agente chama essa ferramenta, ela não executa: o SDK registra uma interrupção e devolve o controle à aplicação até alguém aprovar ou rejeitar

Junto disso tem três camadas de guardrail:

– Input guardrails: validam o que chega ao modelo – Output guardrails: validam o que chega ao usuário – Tool guardrails: envolvem as chamadas de função pra validar ou bloquear antes e depois da execução

O erro comum deste passo: marcar needsApproval: true em toda ferramenta. O run pausa a cada passo e o agente vira um formulário com etapas haha

Qual mecanismo usar em cada ponto do fluxo?

O custo de decidir em excesso (e como calibrar):

Aqui é onde muita gente se ferra

Segundo a Anthropic, usuários aprovam 93% dos prompts de permissão do Claude Code

O problema é a fadiga de aprovação: as pessoas deixam de prestar atenção no que aprovam

Ou seja, a checagem existe, mas ninguém está checando nada 😛

A saída da própria Anthropic foi o auto mode: um classificador aprova as ações rotineiras e bloqueia as sensíveis (grandes deleções, scripts suspeitos, possível exfiltração de dados), em vez de pedir aprovação manual a cada passo

E desde 14 de agosto de 2026 o auto mode é o modo de permissão padrão em sessões novas do Claude Code nos planos Pro, Max e Team

Pra calibrar o teu agente:

1. Corte aprovações em ações reversíveis

Se dá pra desfazer em um passo, não precisa parar o fluxo

O erro comum deste passo: manter o ask "por garantia". Garantia que todo mundo aprova sem ler não garante nada

2. Automatize o rotineiro com regra ou classificador

Regra fixa quando a condição é escrevível, classificador quando não é

O erro comum deste passo: jogar tudo pro classificador e esquecer as regras deny explícitas pro que tu já sabe que é proibido

3. Mantenha o humano só no caro e irreversível

Enviar pra cliente, apagar dado, gastar dinheiro, acionar gente

O erro comum deste passo: colocar o humano como aprovador de tudo e depois reclamar que o agente é lento. Agente lento por excesso de aprovação é problema de arquitetura, não de modelo

Na prática: tirar do modelo a escolha que ele improvisaria

Vou te contar um caso meu que mostra esse padrão por outro ângulo

No vídeo abaixo eu mostro um agente no n8n que escolhe o melhor modelo pra cada pergunta

E a decisão "qual modelo usar" é exatamente o tipo de coisa que o LLM adora improvisar

Quando testei o agente seletor sem uma instrução explícita dizendo que a única função dele era escolher o modelo, às vezes ele simplesmente passava direto, sem selecionar modelo nenhum

Aí eu reforcei no prompt frases como "você sempre deve selecionar o modelo" e "esta é sua única função"

A escolha virou uma decisão isolada e obrigatória, antes de qualquer outra coisa

Outra coisa que fiz: tirei a lista de modelos de dentro do prompt e coloquei numa planilha no Google Sheets, com 11 modelos cadastrados manualmente

Assim fica muiiito mais fácil adicionar modelo novo depois, e o agente escolhe dentro desse conjunto em vez de inventar

Se liga nisso: limitar o espaço de decisão também é uma forma de checagem

Não tem aprovação humana ali, mas o modelo não tem como escolher algo fora da lista

Também separei as responsabilidades:

• Um agente só decide qual modelo usar, e a saída dele deve ser apenas o nome do modelo
• Um segundo agente resolve o problema com o modelo escolhido e, se precisar, usa tools como Wikipedia ou clima

Num teste perguntando "quem foi o terceiro papa", o seletor buscou na planilha, fez as chamadas à LLM, escolheu um modelo e registrou a escolha num log antes de passar pro segundo agente

Mas nem tudo foi lindo, né? Num teste sobre quantidade de pessoas na China, o agente devolveu um nome de modelo sem bater na etapa do Google Sheets, e numa tentativa anterior nem chegou a selecionar nada

Ou seja: mesmo com a decisão isolada, vale ter um ponto que confere se ela aconteceu de verdade

E uma dica de bastidor: depois de adicionar um nó novo ao fluxo, às vezes precisei salvar e recarregar o workflow porque o agente não reconhecia a mudança na hora

Se for reproduzir, use tuas próprias tools (a minha de clima usa uma API própria) pra testar de verdade essa lógica de escolher modelo dentro de um agente

Próximo passo: audite um agente seu com esta régua

Recapitulando a regra:

• Checagem proporcional ao risco e à reversibilidade
• Pontos clássicos: antes de enviar, antes de gravar e antes de escalar
• O resto automatizado com regra ou classificador, porque aprovação demais vira fadiga

Agora faça o teste: pega um agente que tu já tem rodando e lista todas as ações que ele executa

Do lado de cada uma, marca: deny, ask, aprovação humana ou roda livre

Se a coluna "roda livre" ficou vazia, tem checagem demais, e se a coluna deny ficou vazia, provavelmente tem de menos…

Até o próximo post! 🙂