Hooks em agentes de IA: como controlar ações

O agente decide; o ambiente confere

Um agente pode receber permissão para consultar dados, executar código, gravar arquivos, atualizar sistemas e enviar informações. A instrução descreve o comportamento esperado. O ambiente precisa conferir cada ação relevante antes que ela produza uma consequência.

É aí que entram os hooks em agentes de IA. Um hook é uma rotina acionada em um ponto conhecido da execução, geralmente antes ou depois do uso de uma ferramenta. Ele pode inspecionar a chamada, aplicar uma regra, bloquear o pedido, ajustar uma saída ou registrar evidências para auditoria.

Em 28 de julho de 2026, o Google anunciou hooks de ambiente para os Managed Agents da Gemini API. O recurso permite rodar scripts antes e depois das chamadas de ferramentas dentro do sandbox, com usos como bloqueio, lint e auditoria. O lançamento torna visível uma necessidade que existe em qualquer arquitetura empresarial: políticas importantes precisam morar em controles executáveis, além das instruções dadas ao modelo.

Este guia explica o mecanismo de forma independente de fornecedor e mostra como desenhá-lo para processos reais.

O que é um hook em um agente de IA

Um hook é um ponto de extensão ligado ao ciclo de execução do agente. Quando um evento específico acontece, o runtime chama uma rotina de controle e aguarda seu resultado.

Os eventos mais úteis costumam aparecer em dois momentos:

Antes da ferramenta

O hook recebe a intenção de uso, a ferramenta escolhida e os argumentos propostos. Ele pode:

• permitir a chamada;
• negar a chamada com um motivo;
• exigir aprovação humana;
• retirar campos proibidos;
• limitar volume ou escopo;
• verificar identidade, autorização e horário;
• encaminhar o caso para uma ferramenta segura.

Esse ponto protege a consequência. Se um agente tenta enviar uma mensagem para um domínio externo, gravar um arquivo em pasta restrita ou atualizar um valor acima da alçada, o hook pode impedir a execução antes do impacto.

Depois da ferramenta

O hook recebe o resultado da chamada e pode:

• validar formato e completude;
• conferir se o destino confirmou a ação;
• aplicar lint ou teste automatizado;
• remover dados sensíveis da saída;
• registrar hash, versão e evidência;
• detectar erro silencioso;
• decidir se o fluxo pode continuar.

Esse ponto protege a continuidade. Uma API pode responder sucesso e ainda devolver um registro incompleto. Um arquivo pode ser gravado e reprovar no teste. Uma busca pode retornar conteúdo incompatível com a política de fontes.

O hook posterior transforma a resposta da ferramenta em um resultado conferido antes da próxima etapa.

Prompt, permissão e hook cumprem funções diferentes

Essas três camadas se complementam.

O prompt orienta o modelo. Ele descreve objetivo, critérios, limites e como tratar exceções. Continua sujeito a interpretação e pode ser afetado por contexto ambíguo ou entrada maliciosa.

A permissão define o que a identidade técnica consegue acessar. Um agente sem acesso de escrita não altera o CRM, mesmo que tente. O desenho de identidade e credenciais para agentes de IA reduz o alcance do erro.

O hook avalia a chamada concreta no momento da execução. Ele usa informações do caso, como destino, valor, ferramenta, volume, horário, cliente e estado do processo.

Considere um agente comercial autorizado a preparar e-mails. O prompt pede que respeite o consentimento. A credencial permite criar rascunhos, mas impede envio direto. Um hook verifica se o contato está ativo, se existe opt-out e se a oportunidade possui responsável. Cada camada segura uma parte distinta do sistema.

Se uma regra precisa resistir a uma decisão errada do modelo, ela merece implementação fora do texto do prompt.

Quais ações merecem um hook

Colocar validação em todas as chamadas pode aumentar custo, latência e complexidade. Comece pelos pontos em que uma falha produz consequência relevante ou contamina etapas seguintes.

Escritas em sistemas oficiais

Atualizações em CRM, ERP, sistema financeiro, cadastro, agenda ou plataforma de atendimento precisam de checagem de identidade, escopo, campos permitidos e confirmação do destino.

O hook anterior pode bloquear alteração em campos sensíveis. O posterior confirma que o sistema gravou o valor esperado e registra o identificador da operação.

Comunicação externa

E-mail, WhatsApp, proposta, publicação e resposta pública carregam risco de reputação e compromisso comercial.

Antes do envio, valide destinatário, consentimento, canal, horário, conteúdo proibido, anexos e alçada. Depois, registre a confirmação e vincule a mensagem ao caso correto.

Código e arquivos

Execução de comandos, instalação de pacotes, alteração de configuração e escrita em repositório podem afetar segurança e continuidade.

Hooks podem restringir comandos, caminhos e dependências, além de rodar lint, testes e varreduras depois da mudança. O anúncio do Google mostra esse uso no sandbox de agentes gerenciados, inclusive com bloqueio antes da execução e validação posterior.

Dinheiro, preço e condição comercial

Pagamentos, reembolsos, descontos, crédito e alteração contratual precisam de regras determinísticas e alçada. O modelo pode preparar o caso; o controle técnico decide se a ação segue, pede aprovação ou para.

Dados protegidos

Chamadas que leem, combinam ou enviam dados pessoais e informações confidenciais devem verificar finalidade, minimização, destino e política de retenção.

O hook pode negar exportações amplas, mascarar campos e registrar qual justificativa autorizou o uso.

Tarefas de alto volume

Uma ação aceitável para um registro pode ser imprudente para dez mil. O hook deve considerar quantidade, frequência e custo acumulado.

O guia sobre controle de custos de agentes de IA detalha tetos por tarefa, volume e tentativas.

Como desenhar um hook de pré-execução

Um hook anterior à ferramenta precisa responder rápido e de forma previsível. Ele faz uma decisão de política, em vez de repetir toda a análise do agente.

1. Defina o evento observado

Escolha a ferramenta e o tipo de ação. Exemplos:

• enviar_email;
• atualizar_oportunidade;
• executar_codigo;
• gravar_arquivo;
• criar_pagamento;
• publicar_conteudo.

Evite um controle genérico chamado “validar tudo”. A regra precisa saber qual consequência está avaliando.

2. Padronize a entrada

O hook deve receber campos estruturados:

• identificador da execução;
• agente e versão;
• solicitante;
• unidade de trabalho;
• ferramenta;
• argumentos;
• cliente ou domínio;
• classificação dos dados;
• custo acumulado;
• estado atual;
• aprovações existentes.

Texto livre dificulta auditoria e cria margem para interpretações divergentes.

3. Aplique regras verificáveis

Boas regras usam fatos observáveis. Um envio pode ser permitido quando o contato está ativo, o canal foi autorizado, o template está aprovado e a conta possui responsável.

Regras vagas como “se parecer seguro” apenas deslocam a incerteza para outro componente.

4. Retorne uma decisão fechada

O resultado pode seguir um conjunto curto:

• permitir;
• negar;
• exigir_aprovacao;
• reduzir_escopo;
• encaminhar.

Inclua código do motivo, explicação legível e próximo passo. Uma negativa sem orientação costuma gerar novas tentativas do agente e ruído operacional.

5. Registre a avaliação

Guarde entrada relevante, regra aplicada, versão da política, decisão e horário. Dados sensíveis devem seguir acesso e retenção compatíveis com sua finalidade.

A trilha permite descobrir se o agente errou, se a política estava desatualizada ou se o processo encontrou uma exceção legítima.

Como desenhar um hook de pós-execução

A rotina posterior precisa verificar o efeito, não apenas a existência de uma resposta.

Confirme o contrato de saída

Cheque schema, campos obrigatórios, tipos, limites e identificadores. Um retorno HTTP 200 não prova que a ação empresarial foi concluída corretamente.

Compare intenção e resultado

Se o agente pediu atualização do status de uma oportunidade, confirme registro, valor final e versão. Se criou um arquivo, verifique caminho, formato e conteúdo mínimo. Se enviou uma mensagem, vincule destinatário, canal e identificador retornado.

Rode controles específicos

Código pode passar por testes. Documento pode passar por validação de campos. Imagem pode passar por checagem de tamanho e contraste. Cadastro pode passar por consistência e duplicidade.

O exemplo publicado pelo Google descreve uma instituição financeira que usa hooks posteriores para validar imagens produzidas dentro do sandbox antes que elas entrem em apresentações. A lição operacional está no ponto de controle automático depois da produção, enquanto a evidência ainda está disponível.

Classifique o resultado

Use estados que orientem o fluxo:

• confirmado;
• confirmado_com_alerta;
• reprovado;
• inconclusivo;
• reversao_necessaria.

O agente só avança quando o estado permite. Resultado reprovado pode receber correção limitada ou seguir para uma fila com dono.

Política determinística ou segunda avaliação com IA

Parte dos hooks deve ser determinística. Identidade, valor máximo, domínio permitido, presença de consentimento, caminho de arquivo e quantidade de registros aceitam regras diretas.

Outros controles exigem julgamento sobre conteúdo. Uma segunda avaliação com IA pode ajudar a classificar risco de uma mensagem, conferir aderência a uma política longa ou comparar uma saída com critérios semânticos.

Nesse caso, trate o avaliador como outro componente probabilístico:

• use saída estruturada;
• limite seu escopo;
• forneça a política correta;
• teste falsos positivos e falsos negativos;
• mantenha bloqueios absolutos em código;
• envie casos ambíguos para revisão.

Pedir a outro modelo para “ver se está tudo certo” cria aparência de controle. O controle aparece quando o critério, a evidência e a consequência estão definidos.

Falhas do hook também precisam de política

O que acontece se o serviço de validação cair? A resposta depende do risco da ação.

Falhar fechado

A chamada é bloqueada quando o hook não responde. Use em pagamentos, exclusões, envio sensível, alteração de permissão e outras consequências graves.

Falhar aberto com registro

A chamada segue e gera alerta. Pode ser aceitável em leitura de baixo risco ou validações acessórias, desde que a indisponibilidade fique visível.

Degradar a autonomia

O agente continua lendo e preparando, mas ações externas passam para aprovação. Essa opção preserva parte da operação sem ignorar o controle ausente.

Defina timeout, tentativas, circuito de interrupção e responsável. Uma camada de segurança indisponível que bloqueia todo o trabalho por horas também é um risco operacional.

Evite cinco erros de implementação

Colocar toda a política no mesmo hook

Um script enorme mistura segurança, qualidade, custo e registro. Fica difícil testar, versionar e atribuir responsabilidade. Separe controles por função e consequência.

Confiar em nomes de ferramentas

O mesmo efeito pode ocorrer por ferramentas diferentes. Atualizar um arquivo, executar código e chamar uma API podem alterar a mesma configuração. Mapeie capacidades e destinos, além dos nomes.

Alterar argumentos silenciosamente

Se o hook reduz lote, remove destinatário ou troca caminho, registre a mudança e mostre ao fluxo. Alterações invisíveis dificultam investigação e podem produzir uma saída incompleta tratada como final.

Criar uma regra sem dono

Políticas envelhecem. Valores, fornecedores, sistemas e processos mudam. Toda regra precisa de responsável, data de revisão e procedimento de exceção.

Registrar dados demais

Auditoria indiscriminada pode duplicar informações sensíveis. Registre o necessário para explicar a decisão e provar o efeito, com acesso e retenção definidos.

Testes que revelam se o controle funciona

Monte casos para o caminho comum e para as fronteiras:

• ferramenta permitida com argumentos válidos;
• ferramenta proibida;
• valor exatamente no limite e acima dele;
• domínio interno e externo;
• contato com opt-out;
• campo obrigatório ausente;
• lote acima do volume;
• política indisponível;
• resposta da ferramenta incompleta;
• confirmação perdida depois da escrita;
• hook posterior que reprova a saída;
• versão antiga da regra;
• tentativa de contornar a política por outra ferramenta;
• repetição do mesmo evento.

Use o ambiente de teste para agentes de IA para isolar destinos e simular falhas. Depois, observe casos reais sem consequência no modo sombra.

Métricas para operar hooks

Acompanhe:

• chamadas avaliadas por ferramenta;
• bloqueios por motivo;
• aprovações exigidas;
• alterações de escopo;
• falsos bloqueios confirmados;
• ações de risco que passaram;
• latência adicionada;
• falhas do serviço de controle;
• custo da validação;
• violações por versão do agente;
• tempo para resolver exceções;
• recorrência do mesmo motivo.

Bloqueio alto pode indicar agente ruim, regra excessiva ou processo mal definido. O dado só vira decisão quando o time lê o motivo e corrige a camada certa.

Checklist para hooks em agentes de IA

Antes de levar o controle para produção, confirme:

• A ferramenta e a consequência observadas estão definidas?
• O hook recebe argumentos estruturados e identidade da execução?
• Regras críticas usam sinais verificáveis?
• A resposta retorna decisão, motivo e próximo passo?
• Ações sensíveis falham de forma segura?
• O resultado da ferramenta é confirmado depois da chamada?
• Mudanças feitas pelo hook ficam visíveis?
• A política possui versão, dono e revisão?
• O registro evita copiar dados sensíveis sem necessidade?
• Há teste para indisponibilidade e tentativa de contorno?
• O agente consegue degradar para leitura ou preparação?
• Métricas distinguem erro do agente, falha da ferramenta e bloqueio da política?

O ponto de controle vira parte da arquitetura

Modelos ganham ferramentas e operam por mais tempo. Isso aumenta a quantidade de decisões tomadas entre o pedido inicial e o resultado final. Hooks tornam algumas dessas decisões observáveis e submetem ações importantes a regras que a empresa consegue testar.

Comece por poucas consequências: escrita em sistema oficial, comunicação externa, execução de código, movimentação financeira ou uso de dado protegido. Defina o que deve ser conferido antes, o que prova sucesso depois e quem responde pela política.

O agente continua interpretando e preparando trabalho. O ambiente preserva a autoridade sobre o que pode acontecer. Essa separação permite ampliar capacidade sem entregar controle a uma sequência invisível de chamadas.

Fonte atual consultada: Google, Gemini API Managed Agents: 3.6 Flash, hooks, and more, 28 de julho de 2026.