Níveis de log para harness de agentes: o que registrar e o que omitir
Defina três níveis de log para o harness de agentes, padrão, depuração e incidente, para revisar decisões guardando o mínimo de dados pessoais possível.

Os níveis de log de um harness de agentes são um pequeno conjunto fixo de tipos de registro que define o que um agente de IA anota em cada etapa do trabalho. O nível padrão guarda o mínimo necessário para reconstruir decisões rotineiras, o nível de depuração acrescenta detalhes por uma janela de tempo limitada, enquanto alguém está construindo ou testando, e o nível de incidente captura um conjunto restrito e revisado de campos em torno de um problema. O objetivo é revisar o que o agente fez sem transformar o log em uma segunda cópia de cada mensagem de cliente.
Principais pontos
- Defina três níveis, padrão, depuração e incidente, e registre quem pode ativar cada um e por quanto tempo.
- Registre decisões, chamadas de ferramentas, aprovações e resultados por padrão, e deixe de fora o texto completo das mensagens, a menos que um nível exija.
- Oculte ou transforme em código (hash) os dados pessoais na fronteira do harness, antes que qualquer coisa chegue ao armazenamento.
- Defina uma regra de retenção para cada nível e apague a saída de depuração em um prazo que caiba em uma frase.
- Teste os logs com um exercício de reprodução antes que um incidente real force a pergunta.
Por que os logs de agentes precisam de níveis
Uma configuração única de log costuma falhar em um de dois sentidos. Se ela for silenciosa demais, ninguém consegue explicar por que um agente enviou uma cotação ao contato errado ou pulou a verificação de um reembolso. Se for barulhenta demais, o log se enche de nomes, telefones e reclamações em texto livre que ninguém precisava, e esses dados passam a viver em um lugar com regras de acesso, retenção e risco próprios. Os níveis resolvem isso ao transformar a quantidade de registro em uma decisão, e não em um padrão que ninguém revisita.
A pergunta útil não é «o que podemos registrar?», e sim «o que um revisor precisaria para responder sobre cada tipo de evento?». Um revisor que pergunta por que o agente escalou um caso precisa da decisão e das evidências em que ela se apoiou. Quem investiga um timeout precisa do tempo decorrido e da ferramenta que travou. Nenhum dos dois normalmente precisa do texto completo do e-mail do cliente. Escrever essa distinção é o trabalho real de uma política de logs.
O NIST AI Risk Management Framework trata a documentação e o monitoramento de sistemas de IA como parte da gestão de riscos, e o guia de conceitos do OpenTelemetry descreve a telemetria como dados coletados para entender o que um sistema está fazendo. Ambos apontam para uma escolha deliberada do que coletar, e não para o hábito de coletar tudo.
O que o nível padrão deve registrar
O nível padrão roda em toda tarefa, por isso precisa ser barato, estável e seguro para manter. Ele deve responder o que aconteceu, em que ordem, sob a autoridade de quem e com qual resultado. Para a maioria dos agentes de negócio, isso significa os campos a seguir.
- Um identificador da tarefa e a versão do prompt, dos esquemas de ferramentas e do modelo em uso no momento da execução.
- O gatilho: quem ou o que iniciou a execução, e o horário de início e de fim.
- Cada chamada de ferramenta pelo nome, com os parâmetros reduzidos a campos não pessoais, como identificadores de registro e categorias.
- Cada pedido de aprovação, quem aprovou e a decisão registrada, incluindo as recusas.
- O motivo da parada, como concluído, escalado, expirado por timeout ou cancelado por uma pessoa.
- Um resumo curto do resultado, escrito pelo próprio harness, e não um texto livre copiado da saída do modelo.
Repare no que não aparece. Corpo de mensagens, anexos, fichas completas de clientes e o raciocínio bruto do modelo ficam de fora. Esses itens costumam ser os mais sensíveis e os menos necessários para uma primeira revisão. Se o nível padrão já responde «o que o agente decidiu e por que foi autorizado a decidir», ele está cumprindo o seu papel.
Quando o log de depuração é permitido e como limitá-lo
O log de depuração existe para construir e corrigir agentes. Ele pode capturar entradas e saídas completas, rastros de raciocínio intermediário e respostas brutas de ferramentas. Como é o nível que mais expõe informações, precisa do interruptor mais rígido. Trate-o como uma permissão temporária, e não como um segundo modo que a equipe deixa ligado.
- Nomeie um responsável que possa ativar a depuração para um agente específico, e exija um motivo por escrito no registro da mudança.
- Restrinja-a a um ambiente de teste ou a um recorte filtrado do tráfego, nunca a todas as tarefas reais ao mesmo tempo.
- Defina uma expiração automática para que o nível se desligue sozinho, e deixe essa expiração visível no status do harness.
- Oculte os campos pessoais mesmo na depuração, mantendo a estrutura e as categorias de conteúdo para que o erro ainda possa ser reproduzido.
- Apague a saída de depuração no prazo declarado e registre que a exclusão aconteceu.
- Ao fim de cada janela de depuração, revise o que foi capturado e se a mesma pergunta poderia ter sido respondida no nível padrão.
Equipes costumam descobrir que a maior parte das dúvidas de depuração é resolvida por um nível padrão melhor, e não por mais dados. Se você se pega ativando a depuração toda semana, é provável que os campos do padrão estejam deixando de fora algo de que você precisa.
O que o registro de incidente captura
O registro de incidente é mais restrito e tem prazo. Ele começa quando uma pessoa declara um incidente e captura um conjunto definido de campos do agente afetado e das tarefas afetadas. Sua finalidade é preservar as evidências antes que elas mudem, para que a equipe consiga reconstruir a sequência de decisões e o estado de cada ferramenta naquele momento.
Cenário ilustrativo: uma pequena equipe de operações usa um agente que rascunha respostas a perguntas de fornecedores e propõe alterações em pedidos de compra. Certa manhã, um revisor percebe que várias alterações propostas usavam um preço unitário desatualizado. A equipe declara um incidente. O harness passa o agente afetado para o registro de incidente, que mantém as chamadas das ferramentas que leram a tabela de preços, a versão do esquema da ferramenta, os registros de aprovação e os motivos de parada, enquanto os contatos pessoais continuam ocultos. Assim, a equipe vê que a ferramenta de preços lia de uma fonte em cache e suspende a permissão de escrita do agente até que a fonte seja corrigida. Ninguém precisou dos e-mails completos dos fornecedores para encontrar a causa.
Os registros de incidente devem ter acesso restrito, porque são a evidência em que a equipe vai se apoiar depois. Registre quem os acessou e defina antecipadamente quando o nível de incidente será encerrado e quem assina esse encerramento.
Como manter dados pessoais fora dos logs
Dados pessoais em logs são, antes de tudo, um problema de projeto e só depois um problema jurídico. A forma mais segura é garantir que o harness nunca grave o campo em primeiro lugar. Use a lista a seguir ao definir cada nível.
- Liste todos os campos que o harness pode gravar e classifique cada um como estrutural, categórico, pessoal ou sensível.
- Grave campos estruturais e categóricos em todos os níveis. Transforme em código (hash) ou descarte os campos pessoais no nível padrão.
- Oculte na fronteira: o harness deve limpar as respostas das ferramentas antes que entrem no log, e não depender de alguém limpar o log depois.
- Use identificadores internos, como a referência de um registro, em vez de nomes ou contatos, desde que um revisor ainda consiga localizar o registro.
- Confirme que o acesso aos logs segue as mesmas regras de permissão dos sistemas de onde o agente lê, e revise essa lista quando os papéis mudarem.
- Inclua os logs no seu inventário de dados e nas regras de retenção que você já aplica aos registros operacionais.
As orientações da OWASP sobre autorização tocam em um ponto relacionado sobre controle de acesso: cada pessoa deve ver apenas o que o seu papel exige, e isso vale para as ferramentas de observabilidade tanto quanto para o próprio agente. Um log que qualquer pessoa da empresa pode abrir é uma cópia dos seus dados de negócio com proteção mais fraca.
Como a Be Human gerencia os níveis de log na operação gerenciada
A Be Human desenha os níveis de log como parte do harness de cada agente, junto com sua memória, ferramentas, permissões e limites de aprovação. Na operação gerenciada, a equipe define os três níveis para o papel específico, configura as regras de ocultação na fronteira, escreve o cronograma de retenção e a expiração da depuração, e testa a reprodução de uma execução ruim de amostra antes de entrar em produção. Revisões de monitoramento e de permissões verificam depois se os níveis ainda correspondem ao que o agente faz e se os interruptores de depuração não ficaram ligados. Mudanças nos níveis seguem o mesmo processo de versionamento e liberação usado para prompts e esquemas de ferramentas, para que o registro do que foi capturado também possa ser revisado.
Defina sua primeira política de logs neste mês
Comece com um agente e uma página. Escreva os campos do padrão, o responsável único pelos interruptores de depuração, a regra para declarar incidentes e a declaração de retenção. Depois, rode uma reprodução de uma tarefa passada para ver se o nível padrão responde às suas perguntas. Quando isso funcionar, estenda a mesma página para o próximo agente. Fazer o diagnóstico gratuito de IA da Be Human é uma forma prática de encontrar a primeira tarefa que vale entregar a um agente, e a política de logs dessa tarefa é um bom ponto de partida.
Perguntas frequentes
Quantos níveis de log um harness de agentes precisa? Três bastam para a maioria dos agentes de negócio: padrão, depuração e incidente. O padrão roda em toda tarefa e registra estrutura e decisões. A depuração é uma permissão com prazo para construir e testar, e o incidente é uma captura restrita e revisada em torno de um problema declarado.
Devemos registrar as mensagens completas dos clientes para poder investigar problemas? Normalmente não, por padrão. A maioria das investigações depende da decisão, das chamadas de ferramentas, das aprovações e do motivo de parada, que podem ser registrados sem o texto da mensagem. Se uma investigação específica precisar do conteúdo, ative-o no nível de depuração ou de incidente apenas para as tarefas afetadas, com ocultação de dados e prazo de expiração definido.
Por quanto tempo os logs de depuração e de incidente devem ser mantidos? Defina um período de retenção para cada nível na sua própria política, com base nas suas obrigações legais e nas necessidades de revisão interna, e apague os dados quando esse período terminar. A saída de depuração deve durar menos que os logs padrão, porque contém mais detalhes, e os registros de incidente devem ser encerrados com uma assinatura por escrito que informe quando serão removidos.
Quem pode alterar os níveis de log? Um responsável único deve aprovar as mudanças, e cada mudança deve ser registrada com motivo e, quando for o caso, com prazo de expiração. O acesso aos próprios logs deve seguir as mesmas regras de papel dos sistemas de origem, para que quem não poderia ler um registro de cliente diretamente também não consiga lê-lo pelos logs do agente.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


