Hooks de agentes de IA: a campainha que evita erros

Um agente de IA pode trabalhar rápido. Mas quem toca a campainha quando ele está prestes a levar um segredo para fora de casa? Essa pergunta ficou mais importante agora que agentes como Codex e Claude Code usam arquivos, comandos e ferramentas de verdade.

A OpenAI anunciou que os hooks do Codex estão disponíveis de forma geral. Eles podem procurar segredos, rodar validadores, registrar conversas, criar memórias e adaptar o agente a cada projeto. Parece coisa de programador.

Não precisa ser. Hook é apenas uma regra que acorda na hora certa. Como uma campainha: alguém chega, ela toca e uma ação acontece.

TL;DR Hook é uma regra automática disparada antes ou depois de uma ação do agente. Eu usaria hooks para proteger segredos, testar entregas, guardar um registro e avisar quando uma pessoa precisa decidir. Hook não pensa no lugar do agente.

Ele coloca uma cerca simples em volta do trabalho. O problema Quando um agente ganha ferramentas, ele também ganha novas maneiras de errar. Ele pode tentar enviar uma senha junto com um texto.

Pode mudar um arquivo e esquecer de rodar o teste. Pode terminar uma tarefa sem deixar registro. Pode chegar a uma decisão importante e seguir sozinho quando deveria chamar uma pessoa.

Escrever “tenha cuidado” no pedido ajuda, mas não é uma trava. É como colocar uma placa “não entre com o pé sujo” e esperar que toda criança se lembre dela para sempre. Um hook transforma o aviso em ação.

O que são hooks de agentes de IA Hook é um pequeno gatilho ligado a um momento do trabalho. Imagine uma escola: quando o aluno entra, a chamada registra sua presença; antes da prova começar, a professora confere se a mesa está limpa; depois da prova, alguém verifica se o nome foi preenchido; se houver um problema, a coordenação recebe um aviso. Cada uma dessas regras é parecida com um hook.

No agente, o gatilho pode acontecer antes de uma ferramenta ser usada, depois que um arquivo muda ou quando a tarefa termina. O hook recebe o sinal e executa uma regra conhecida. Ele não precisa ser inteligente.

Na verdade, muitas vezes é melhor que seja simples e previsível. Quatro usos que fazem sentido hoje 1. Procurar segredos antes de enviar Imagine que o agente vai copiar um trecho de configuração para uma ferramenta externa.

Um hook pode procurar padrões de senha, token ou chave de API antes do envio. Se encontrar algo suspeito, ele bloqueia a ação e pede revisão. É o segurança olhando a mochila antes de ela sair do prédio.

2. Rodar testes depois de uma mudança O agente alterou uma página do site. Um hook pode rodar automaticamente o teste daquela página logo depois.

Se o teste falhar, o trabalho não recebe um “pronto” falso. Isso é importante porque arquivo salvo não significa entrega funcionando. O hook cria o hábito de conferir.

3. Guardar um recibo do trabalho Quando a tarefa termina, um hook pode registrar o que mudou, quais testes passaram e onde está a entrega. Esse recibo ajuda outra pessoa — ou outro agente — a continuar sem começar do zero.

Não é guardar cada pensamento da IA. É guardar os fatos úteis, como fazemos numa nota de serviço. 4.

Chamar uma pessoa na decisão certa Nem tudo deve ser automático. Se o agente estiver prestes a publicar, apagar dados, gastar dinheiro ou mandar uma mensagem, um hook pode pausar o fluxo e pedir aprovação humana. Esse é o uso que eu mais gosto.

Automação boa não elimina a pessoa. Ela chama a pessoa apenas quando a decisão realmente importa. Um exemplo prático Vamos imaginar um agente que escreve e publica artigos.

Sem hooks, o fluxo pode ser assim: Escrever → gerar imagem → publicar Com hooks, eu montaria assim: Escrever → hook confere título e links → gerar imagem → hook confere tamanho e formato → pedir aprovação para publicar → hook testa a URL pública → hook registra o recibo final Perceba a diferença. O agente continua fazendo o trabalho. Os hooks só aparecem nos pontos em que um erro custaria mais caro.

Como começar sem complicar Eu não criaria vinte hooks no primeiro dia. Começaria por um erro que já aconteceu. 1.

escolheria uma tarefa repetida; 2. marcaria o momento em que ela costuma falhar; 3. criaria uma regra curta e verificável; 4.

testaria a regra com um caso bom e um caso ruim; 5. guardaria um registro quando ela bloquear algo. Um bom hook cabe numa frase: Antes de enviar conteúdo para fora, bloqueie qualquer texto que pareça conter uma chave secreta.

Um hook ruim tenta resolver o mundo: Garanta que tudo esteja perfeito e seguro. Se a regra não consegue dizer claramente “passou” ou “falhou”, ela provavelmente ainda está grande demais. Hook, skill e prompt são a mesma coisa?

Não. Eu explico assim: prompt é o pedido que você faz; skill é o manual que ensina um jeito de trabalhar; hook é a campainha que dispara uma regra num momento específico; MCP é o adaptador que conecta ferramentas e dados. Eles podem trabalhar juntos.

Uma skill ensina o agente a publicar um artigo, um MCP conecta o blog e um hook impede a publicação se o teste falhar. O erro mais comum O erro é usar hook para vigiar tudo. Cada hook adiciona tempo e pode bloquear trabalho bom.

Se a empresa cria regras demais, o agente passa mais tempo atravessando catracas do que entregando. Eu priorizaria três lugares: segredo, ação irreversível e prova final. O resto entra quando existe um erro real para corrigir.

Perguntas rápidas Hooks deixam o agente mais inteligente? Não. Eles deixam o processo mais previsível.

A inteligência continua no modelo; o hook garante que uma regra seja aplicada na hora combinada. Preciso saber programar para criar um hook? Hoje, muitas configurações ainda pedem algum conhecimento técnico.

Mas a ideia pode ser desenhada por qualquer pessoa: escolha o momento, a regra, o resultado esperado e quem recebe o aviso. Hooks funcionam só no Codex? Não.

O nome e a configuração mudam, mas vários agentes e sistemas de automação oferecem gatilhos antes ou depois de ações. Codex e Claude Code são exemplos conhecidos. Um hook pode impedir uma publicação?

Sim. Ele pode bloquear o fluxo quando uma validação falha ou pedir aprovação humana antes da publicação. Qual hook devo criar primeiro?

Comece pelo erro repetido que causa mais risco ou retrabalho. Se você nunca teve o problema, talvez ainda não precise da regra. Conclusão Hooks de agentes são campainhas com uma tarefa clara.

Eles tocam antes de um segredo sair, depois de um arquivo mudar, na hora de pedir aprovação ou quando chega o momento de provar que a entrega funciona. Eu não usaria hooks para encher o agente de burocracia. Usaria para transformar os cuidados mais importantes em hábitos automáticos.

Se você quer começar hoje, faça uma pergunta: em qual parte do trabalho eu sempre digo “não esqueça de conferir isso”? Esse é um ótimo candidato para o primeiro hook. Para continuar, leia também [o que são skills de IA](/blog/o-que-sao-skills-de-ia), [o que é MCP na IA](/blog/o-que-e-mcp-na-ia) e [o que é sandbox de agentes](/blog/o-que-e-sandbox-de-agentes-de-ia).

Fontes que eu li OpenAI: Work with Codex from anywhere OpenAI: Codex for every role, tool, and workflow Anthropic: Claude Code hooks guide