Hooks em agentes de IA: verificações automáticas antes e depois

Hooks em agentes de IA são verificações automáticas que rodam logo antes ou logo depois de o agente executar uma ação, como enviar uma mensagem, atualizar um registro ou chamar uma ferramenta. Ficam no sistema ao redor, e não no prompt, então rodam sempre, qualquer que seja a decisão do modelo. Use-os para qualquer regra que precise valer sem exceção, porque instruções só conseguem pedir ao modelo que cumpra.

Principais pontos

• Um hook é código ou configuração comum, ligado a um momento do trabalho do agente, e o agente não consegue pulá-lo.
• Instruções descrevem a intenção. Hooks impõem limites. Toda regra cara de quebrar pertence a um hook.
• Hooks de antes evitam danos por meio de permissões, validação e aprovação. Hooks de depois verificam resultados, limpam dados sensíveis e guardam registros.
• Comece pelas poucas ações que alteram algo fora do agente e escreva cada regra como uma pergunta que um programa responda com sim ou não.
• Registre cada decisão dos hooks com o motivo, para revisar bloqueios, exceções e lacunas ao longo do tempo.

O que é um hook em um agente de IA?

Um hook é um pequeno trecho de software ligado a um momento específico do trabalho do agente. Quando o agente está prestes a fazer algo, ou acabou de fazer, o sistema ao redor pausa, executa a verificação e decide o que acontece em seguida. O resultado costuma ser um de quatro: seguir, alterar a ação, bloqueá-la ou perguntar a uma pessoa.

O agente não escolhe se o hook roda. Esse é o ponto central. O modelo propõe uma ação, e o sistema ao redor do modelo a intercepta. Se a proposta passa, ela segue. Se não passa, o hook devolve um motivo claro, e o agente pode tentar outro caminho ou encaminhar o caso a uma pessoa.

Os hooks podem ser ligados a vários momentos. Os mais úteis são estes:

• Antes de uma chamada de ferramenta, quando o agente vai ler, gravar, enviar ou apagar algo.
• Depois de uma chamada de ferramenta, quando um resultado volta e o agente vai se apoiar nele.
• Antes de uma resposta sair da empresa, como um e-mail ou uma mensagem a um cliente.
• Ao fim de uma tarefa, quando o agente diz que o trabalho está concluído.
• Quando algo falha, para que a falha seja registrada e encaminhada, em vez de repetida em silêncio.

Se você quer entender como as ferramentas são acionadas, o que é tool calling em IA, em termos simples é uma boa leitura complementar. Os hooks ficam exatamente nessa fronteira entre uma decisão e o seu efeito.

Por que só instruções não garantem uma regra?

Uma instrução é um pedido escrito em linguagem natural. O modelo a lê, pesa contra tudo o que há no contexto e, em geral, a segue. Normalmente não é um controle. Para uma empresa, os casos em que a regra mais importa costumam ser aqueles em que o modelo mais tende a se desviar.

Há vários motivos comuns para uma regra escrita falhar:

• O contexto é longo, e uma instrução dada no início pesa menos do que um pedido feito no fim.
• Duas instruções entram em conflito, e o modelo resolve o conflito de um jeito que ninguém previu.
• Texto não confiável entra na conversa, como o e-mail de um cliente que manda o agente ignorar as regras. Injeção de prompt é uma categoria de risco reconhecida nas orientações da OWASP para aplicações com modelos de linguagem.
• O modelo acredita que cumpriu. Ele informa que uma verificação foi feita quando apenas pretendia fazê-la.

Nada disso significa que instruções são inúteis. Elas definem intenção, tom e critério, e um conjunto bem mantido delas deixa o agente muito melhor no trabalho. A pergunta sobre onde investir primeiro está em prompt engineering ou harness engineering: por onde começar. Resumindo: o prompt molda o comportamento, e o harness limita o que esse comportamento pode causar.

Uma regra prática: se quebrar a regra custaria dinheiro, confiança ou posição legal, não conte com o modelo para lembrar dela. Escreva a regra como um hook e mantenha a instrução apenas como explicação de por que a regra existe.

Quais verificações ficam antes da ação e quais ficam depois?

A divisão é simples. Verificações que evitam um resultado ruim rodam antes da ação. Verificações que confirmam o que aconteceu, limpam ou deixam evidência rodam depois. Algumas regras precisam dos dois momentos.

Hooks de antes são ideais para ações difíceis de desfazer, como enviar, pagar, publicar, apagar ou compartilhar fora da empresa:

• Verificação de permissão: este agente pode usar esta ferramenta, neste registro, em nome desta pessoa?
• Validação de entrada: os campos obrigatórios estão preenchidos, os formatos estão corretos, o destinatário consta em uma lista aprovada?
• Verificação de política: o conteúdo evita promessas, conselhos ou compromissos que a empresa descartou?
• Ponto de aprovação: esta ação passa de um limite de risco que exige o sim de uma pessoa nomeada?
• Verificação de duplicidade: esta mesma ação já aconteceu, por exemplo a mesma mensagem para a mesma pessoa?

Hooks de depois são ideais para confirmar, proteger e registrar:

• Validação do resultado: o sistema confirmou de fato a gravação, e os dados devolvidos têm o formato esperado?
• Limpeza de dados: segredos e dados pessoais foram removidos antes de o resultado ser registrado ou passado a outra etapa?
• Registro de auditoria: quem ou o que agiu, em qual registro, quando e por quê. Em ambientes regulados, esse registro costuma ter exigências próprias.
• Captura de evidência: a prova de conclusão está anexada à tarefa, para que pronto signifique algo?
• Alertas: um padrão incomum, como bloqueios ou falhas repetidas, chega a uma pessoa?

Um guia de decisão útil é fazer uma pergunta sobre cada ação: se isso der errado, conseguimos desfazer? Se não, coloque a verificação antes. Se sim, uma verificação depois, com um alerta claro, muitas vezes basta.

Como isso aparece na prática? Um cenário ilustrativo

Este cenário é ilustrativo e não descreve uma empresa real. Imagine um agente que envia confirmações de agendamento para um pequeno negócio de serviços. As instruções dizem para confirmar apenas horários livres e mandar mensagem somente para o telefone que consta no cadastro do cliente.

Sem hooks, o agente depende de lembrar das duas regras. Um cliente encaminha a mensagem de um familiar com outro número e pede que a confirmação seja enviada para lá. O agente, tentando ajudar, atende. Mais tarde, duas reservas caem no mesmo horário porque a agenda mudou enquanto o agente redigia a mensagem.

Com hooks, o mesmo dia é diferente. Um hook de antes compara o número de destino com o cadastro do cliente e confere o horário na agenda atualizada no momento do envio, e não no momento da redação. As duas verificações falham, a mensagem é bloqueada e uma nota curta vai para um funcionário: número diferente do cadastro e horário não mais disponível. Um hook de depois registra o resultado e, nas mensagens que saem, confirma o status de entrega e o grava na ficha do cliente.

O agente não fez nada diferente. O sistema ao redor tornou as regras reais. O funcionário vê um motivo claro, resolve em um minuto e o agente continua. Para uma visão mais ampla de quais proteções colocar primeiro, veja guardrails para agentes de IA nas empresas: por quais começar.

Como adicionar hooks, passo a passo?

Você não precisa colocar hook em tudo. Comece pelas ações que alteram algo fora do agente e avance de dentro para fora.

• Liste toda ação do agente que envia, grava, apaga, paga, publica ou compartilha.
• Ordene essas ações pela dificuldade de reverter e por quem seria afetado se dessem errado.
• Para cada ação de prioridade alta, escreva a regra como uma pergunta de sim ou não que um programa consiga responder, sem margem para interpretação.
• Decida o que acontece diante de um não: bloquear, corrigir automaticamente, escalar para uma pessoa nomeada ou apenas registrar.
• Construa a verificação fora do modelo, em código ou configuração que o agente não consiga editar nem desligar.
• Teste com casos que devem passar e casos que devem falhar, incluindo textos escritos para enganar o agente.
• Registre cada decisão com o motivo, a regra acionada e a ação envolvida.
• Revise bloqueios, exceções e quase-erros com regularidade e ajuste as regras.

O quinto passo é o que as equipes mais pulam. Uma verificação que o agente enxerga e consegue modificar é uma sugestão. Uma verificação em uma camada que o agente não alcança é um controle. A orientação da OWASP sobre autorização faz um ponto parecido: decisões de permissão devem ser aplicadas de forma consistente no servidor, e não deixadas a cargo de quem faz a chamada.

O que torna um hook confiável?

Bons hooks têm algumas propriedades em comum. São determinísticos, então a mesma entrada gera a mesma resposta. São rápidos o bastante para que ninguém tenha vontade de desativá-los. Explicam a si mesmos, de modo que um bloqueio diz qual regra foi acionada e o que tornaria a ação aceitável. E falham em uma direção deliberada: fechados nas ações de alto risco, abertos com alerta nas de baixo risco.

Vários erros aparecem repetidamente:

• Hooks demais. Se toda ação dispara uma pergunta, as pessoas aprendem a aprovar sem ler, e o controle vira teatro.
• Mensagens de bloqueio vagas. Um agente que recebe uma recusa seca pode tentar a mesma coisa com palavras ligeiramente diferentes. Um motivo específico permite que ele mude de rumo.
• Usar um modelo para impor uma regra rígida. Um segundo modelo pode servir como verificação consultiva em temas subjetivos, como tom, mas mantenha as regras inegociáveis em código simples.
• Bloqueios que deixam o trabalho em estado quebrado. Quando um hook interrompe uma ação no meio de uma tarefa, o trabalho deve ficar em uma condição que possa ser retomada. A preocupação é a mesma de checkpoints de agentes de IA: como retomar o trabalho.
• Falta de revisão. As regras envelhecem quando o negócio muda. Um hook que ninguém lê acabará bloqueando a coisa errada ou deixando passar a certa.

Fique atento também às novas tentativas. Se um hook de depois detecta uma falha e o agente tenta de novo, garanta que a ação não possa ser aplicada duas vezes. Provedores de pagamento resolvem isso com chaves de idempotência, e a mesma ideia funciona para mensagens e registros.

Como a Be Human trabalha com hooks?

A Be Human trata hooks como parte da infraestrutura ao redor do agente, e não como um complemento. Em um primeiro projeto, o papel útil do agente, a memória e as ferramentas de que ele precisa e os limites de aprovação são definidos juntos, com um critério de sucesso observável. Os hooks são então construídos para acompanhar esses limites: verificações de permissão nas ferramentas, pontos de aprovação onde uma pessoa precisa decidir e registros de cada decisão. Na operação gerenciada, as decisões dos hooks são monitoradas, as permissões são revisadas e as mudanças nas regras são feitas de forma controlada e testadas antes de chegar ao trabalho real.

Perguntas frequentes

Hooks de agentes de IA são o mesmo que guardrails? Hooks são uma forma de implementar guardrails. O guardrail é a regra ou o limite, como nunca enviar e-mail externo sem aprovação, enquanto o hook é a verificação automática que o impõe em um momento específico do trabalho do agente. Guardrails também podem incluir permissões, orçamentos e acessos restritos que não rodam como verificação.

Hooks deixam o agente mais lento? Verificações simples de permissão, formato e listas acrescentam muito pouco atraso, porque são código comum. O atraso que importa vem dos pontos de aprovação, em que uma pessoa precisa responder, então reserve esses pontos para ações difíceis de reverter. Todo o resto deve rodar sem que ninguém perceba.

O agente pode escrever ou alterar os próprios hooks? Não deveria. Se o agente pode editar a verificação que o limita, ela deixa de ser um controle. Mantenha as definições dos hooks em uma camada que só pessoas nomeadas possam alterar, e torne cada mudança revisável.

Por onde uma empresa pequena deve começar? Escolha a ação que mais prejudicaria se desse errado, como enviar uma mensagem a um cliente ou alterar um registro financeiro. Escreva a regra como uma pergunta de sim ou não, adicione um hook de antes e registre o resultado. Quando isso funcionar e a equipe confiar, estenda o mesmo padrão para a próxima ação.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.