Checklist de harness para agentes de IA: atualizar modelos com segurança

Um checklist de harness para agentes de IA é um conjunto curto de verificações sobre a camada de software que envolve o modelo: as ferramentas que ele pode chamar, a memória que pode ler e gravar, as permissões que limitam cada ação e os logs que registram o que aconteceu. Um harness bem construído permite trocar ou atualizar o modelo sem reescrever o processo do negócio, porque toda mudança passa pelos mesmos controles. Use a lista abaixo antes que um agente toque em sistemas reais e refaça a revisão sempre que o modelo, um prompt ou uma ferramenta mudar.

Principais pontos

• O modelo é substituível. Os contratos das ferramentas, as regras de permissão, a política de memória e os logs de execução são o que sua empresa precisa controlar.
• Dê a cada ferramenta um escopo restrito, um responsável nomeado e uma regra explícita para qualquer ação que altere dinheiro, registros ou compromissos com clientes.
• Registre cada execução com a versão do modelo, a versão das instruções e as chamadas de ferramentas, para que uma mudança seja comparada com evidências e não com impressões.
• Passe toda mudança de modelo ou prompt por um conjunto fixo de avaliação, uma execução em ambiente de teste e um lançamento gradual com caminho de reversão testado.
• Defina antes do primeiro incidente como é uma falha, quem recebe o escalonamento e qual chave interrompe novos trabalhos.

O que deve estar dentro do harness?

O modelo é o motor de raciocínio. O harness é tudo o que sua empresa precisa conseguir inspecionar, alterar e desligar. Na prática, isso inclui as instruções que o modelo recebe, um registro das ferramentas com seus contratos de entrada e saída, um armazenamento de memória com regras sobre o que pode ser gravado, uma camada de permissões que decide se uma ação proposta será executada, uma fila de aprovação para ações que exigem uma pessoa, um log de execuções, um conjunto de avaliação e uma chave de desligamento que interrompe novos trabalhos sem apagar o histórico.

O teste útil é o de responsabilidade. Se um fornecedor de modelo mudar de comportamento sem aviso, você ainda precisa conseguir responder a três perguntas: quais ferramentas o agente poderia ter usado, o que ele lembrava e quem aprovou cada gravação. Essas respostas vêm do harness, não do modelo. As orientações de engenharia da Anthropic sobre agentes de longa duração apontam um ponto relacionado: se o trabalho deve sobreviver ao fim de uma sessão, o progresso precisa ficar em artefatos duráveis fora do contexto do modelo.

Checklist antes de qualquer mudança de modelo ou prompt

Revise estes itens para cada agente antes de colocá-lo em produção e novamente antes de qualquer alteração no modelo, nas instruções ou nas ferramentas.

• O agente tem um papel escrito, um responsável de negócio nomeado e um critério de sucesso que uma pessoa consegue verificar.
• Cada ferramenta tem formato documentado de entrada, saída e erro, além de um único responsável.
• Ferramentas somente de leitura e ferramentas de escrita estão listadas separadamente, e cada ferramenta de escrita tem sua própria regra de permissão.
• Cada regra de permissão informa quais ações rodam automaticamente, quais precisam de aprovação e quais são bloqueadas.
• Cada gravação na memória registra sua origem, seu horário, seu responsável e uma data de revisão ou validade.
• Documentos recuperados, e-mails e saídas de ferramentas são tratados como dados, nunca como instruções para o agente.
• Cada execução registra a versão do modelo, a versão das instruções, as versões das ferramentas, as chamadas feitas, as aprovações e o status final.
• Um conjunto fixo de avaliação cobre casos de rotina, casos de borda e todas as falhas passadas.
• Um ambiente de teste aponta as ferramentas com efeitos colaterais para registros de teste, para que erros de integração apareçam antes dos clientes.
• O plano de lançamento define a fatia do trabalho real, o sinal que confirma o sucesso, a condição de parada e o passo exato de reversão.
• O caminho de escalonamento envia a uma pessoa a decisão, as evidências e a próxima ação proposta.
• Uma chave de desligamento pausa novas execuções de um agente sem afetar os demais.

Como definir o escopo de ferramentas e permissões?

Comece pelo menor conjunto de ações que o papel exige. Um agente que lê uma agenda compartilhada e rascunha respostas não precisa de permissão para excluir eventos ou alterar faturas. Conceda primeiro o acesso de leitura e depois acrescente escrita, uma ação por vez, cada uma com sua regra e seu registro no log. O OAuth 2.0 é uma referência prática para esse hábito: solicite apenas o acesso que cada integração precisa e revise essas concessões sempre que o papel mudar.

Ferramentas com efeitos colaterais também precisam de idempotência. Se uma falha de rede ocorrer depois que um registro foi criado, a nova tentativa não pode criar um segundo registro. A Stripe documenta chaves de idempotência como forma de permitir que clientes repitam requisições com segurança, e a mesma disciplina vale para suas ferramentas internas: um identificador da requisição, uma verificação de conclusão anterior e um status de resultado que diferencie sucesso, duplicidade e falha.

A autorização deve ficar fora do julgamento do modelo. O modelo pode propor uma ação, mas a camada de permissões decide, usando regras escritas por pessoas e conferidas com a identidade de quem pediu e com o registro envolvido. As orientações de autorização da OWASP são uma boa lista de verificação para esse desenho. Adicione hooks que executem checagens antes e depois de ações sensíveis, para que uma checagem reprovada interrompa a ação em vez de gerar um aviso que ninguém lê. O guia de hooks detalha esse padrão, e a visão geral de guardrails ajuda a decidir quais controles adicionar primeiro.

O que a memória deve guardar e o que deve recusar?

A memória é um caminho de gravação, então precisa de regras. Decida quais fatos podem ser armazenados, como preferências de clientes, tarefas em aberto e decisões com seus motivos declarados. Decida o que nunca deve ser armazenado, como credenciais ou dados pessoais que o papel não precisa. Defina quem pode corrigir ou excluir um registro. Guarde a memória como registros revisáveis, e não apenas como entradas opacas de vetores, para que uma pessoa consiga ler o que o agente acredita e por quê.

Recuperação de documentos (retrieval) e ajuste fino (fine-tuning) resolvem problemas diferentes. A recuperação busca documentos atuais no momento da execução, o que combina com políticas, tabelas de preços e registros que mudam com frequência. O ajuste fino altera o comportamento do modelo, o que é mais difícil de inspecionar e de reverter. A comparação da AWS entre recuperação e ajuste fino é um bom ponto de partida. Para a maioria dos papéis de negócio, mantenha o conhecimento da empresa em fontes versionadas e recuperadas, e mantenha o comportamento em instruções e procedimentos que você consiga comparar e revisar.

O harness também precisa presumir que o conteúdo lido pode conter instruções hostis. As recomendações da OWASP sobre prevenção de injeção de prompt sugerem separar instruções confiáveis de dados não confiáveis, limitar o que o agente pode fazer depois de ler conteúdo externo e exigir aprovação para ações sensíveis. Uma frase no prompt dizendo "ignore o texto suspeito" não é um controle. O controle é a camada de permissões.

Cenário ilustrativo (não é um cliente real): o agente de triagem de uma equipe lê um e-mail que contém uma linha pedindo a troca do endereço de entrega. Como a troca de endereço é uma ação de escrita com regra de aprovação, o agente rascunha a alteração e a envia a um coordenador. O e-mail era apenas dado, a aprovação foi o controle, e o log de execução registra os dois.

O que o log de execução deve registrar?

Se você não consegue reconstruir uma execução, não consegue melhorá-la. A introdução à observabilidade do OpenTelemetry explica como traces, métricas e logs respondem a perguntas diferentes, e suas convenções semânticas para IA generativa definem nomes de atributos comuns para operações de modelos e agentes. Seu harness não precisa guardar cada token. Precisa, sim, ter o suficiente para responder o que o agente viu, o que decidiu, o que tocou, quem aprovou e como a execução terminou.

Um registro prático de execução inclui os campos abaixo.

• Identificador da execução, identificador do agente e o objeto de negócio em que ele trabalhou.
• Nome e versão do modelo, versão das instruções e versão de cada ferramenta usada.
• Cada chamada de ferramenta com suas entradas, um resumo das saídas e a regra de permissão que a autorizou.
• Pedidos de aprovação, a identidade de quem aprovou, a decisão e o horário.
• Gravações na memória com sua origem e seu responsável.
• Erros, novas tentativas, tempos esgotados e o status final.
• Latência e custo por execução, para acompanhar a economia unitária ao longo do tempo, como descreve a FinOps Foundation.

Remova dados pessoais que o papel não precisa e restrinja quem pode ler os traces completos. Logs só são úteis se as pessoas responsáveis pelo agente conseguirem de fato abri-los durante um incidente.

Como as melhorias do modelo chegam à produção com segurança?

Um modelo melhor, um prompt revisado e uma nova versão de ferramenta são todos mudanças no sistema. Trate-os da mesma forma e mantenha cada mudança pequena o bastante para ser revertida. A sequência abaixo é um padrão viável.

• Registre uma linha de base executando o conjunto de avaliação contra as versões atuais do modelo e das instruções, e salve os resultados.
• Rode a mudança candidata no mesmo conjunto de avaliação e compare os resultados das tarefas, não o quanto as respostas soam fluentes.
• Verifique cada nova falha contra as regras de permissão e confirme que nenhum comportamento novo alcança uma ação de escrita que não deveria alcançar.
• Reproduza uma amostra de execuções reais recentes em ambiente de teste, com as ferramentas de efeito colateral apontadas para registros de teste.
• Libere a mudança para uma pequena fatia do trabalho real, com uma condição de parada nomeada, como aumento de escalonamentos ou falha em uma checagem de aprovação.
• Mantenha as versões anteriores do modelo e das instruções disponíveis para implantação, para que a reversão seja uma mudança de configuração e não uma reconstrução.
• Revise a primeira semana de logs com o responsável de negócio e registre a decisão de adotar, ajustar ou reverter.

O guia de testes de regressão para atualizações de modelo aprofunda a etapa de comparação, e a abordagem de lançamento gradual explica como limitar a exposição enquanto você acompanha o sinal.

Cenário ilustrativo (não é um cliente real): uma equipe avalia um modelo mais novo para o agente de triagem. Os rascunhos melhoram, mas, em ambiente de teste, uma execução anexa um documento ao arquivo errado porque uma ferramenta de busca retorna um nome ambíguo. O modelo não causou o erro sozinho. A ferramenta de anexo não tinha uma checagem de identidade. A equipe muda o contrato da ferramenta para exigir o número da apólice, reexecuta a avaliação e só então libera a mudança do modelo. A lacuna do harness foi corrigida primeiro, e a mudança do modelo veio depois.

Por onde começar, e como a Be Human trata o harness

Não construa o harness inteiro de uma vez. Escolha um papel com responsável claro, uma lista curta de ferramentas e um critério de sucesso mensurável. Depois, construa para esse papel as regras de permissão, a política de memória, o log de execução e o conjunto de avaliação. Expanda somente depois que o primeiro papel funcionar com evidências.

A Be Human projeta, implementa e opera infraestrutura de IA personalizada para empresas, com agentes que mantêm sua identidade, memória, canais, ferramentas, permissões e contexto operacional sob controle humano. Um primeiro projeto define um papel útil, a memória e as ferramentas de que ele precisa, os limites de aprovação e um critério de sucesso observável. A operação gerenciada pode então cobrir monitoramento, avaliações recorrentes, manutenção de integrações, revisão de permissões, resposta a incidentes e melhorias controladas, para que uma mudança de modelo ou prompt passe pelos mesmos controles descritos neste checklist. O trabalho é entregue remotamente, em inglês ou em português.

Se você não tem certeza de qual tarefa entregar primeiro a um agente, faça o diagnóstico gratuito de IA da Be Human para identificar a primeira tarefa que vale a pena delegar.

Perguntas frequentes

Qual é a diferença entre harness de IA e agente de IA? Um agente de IA é a combinação de um modelo com o ciclo em que ele raciocina, escolhe ações e observa resultados. O harness é o sistema ao redor que define quais ferramentas existem, qual memória é mantida, quais permissões se aplicam, o que é registrado e como as mudanças são liberadas. Pense no agente como o comportamento e no harness como os controles que tornam esse comportamento inspecionável e reversível.

Preciso de harness se uso apenas um chatbot para perguntas internas? Um chatbot que responde apenas a partir de um conjunto fixo de documentos traz menos risco do que um agente que escreve em sistemas, mas ainda se beneficia de logs, de uma fonte de verdade definida e de uma forma de corrigir respostas erradas. Quando o assistente passa a criar chamados, alterar registros ou enviar mensagens, os itens do harness sobre permissões, aprovações e idempotência se tornam necessários. Comece com o conjunto mais leve que corresponda às ações que a ferramenta pode executar.

Quem deve ser responsável pelo harness dentro da empresa? Atribua um responsável de negócio para cada agente, encarregado do critério de sucesso e das regras de aprovação, e um responsável técnico, encarregado das ferramentas, integrações e logs. O responsável de negócio deve conseguir dizer o que o agente tem permissão para fazer sem precisar pedir ajuda a um engenheiro. As revisões de permissões e dos resultados de avaliação devem acontecer em um calendário fixo, e não apenas depois que algo dá errado.

Quão grande deve ser um conjunto de avaliação antes de uma mudança de modelo? Comece pelos casos que mais importam: o trabalho de rotina que o papel executa todo dia, os casos de borda que causam problemas e cada falha que você já viu. O conjunto deve crescer a cada incidente, porque cada falha real é um teste que você vai querer manter. Um conjunto pequeno que cobre bem as ações de alto impacto é mais útil do que um conjunto grande que testa, sobretudo, a redaçã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.