Ir para conteúdo
be-human.ai
← Voltar ao blog

Fundamentos de harness

Checklist de harness para agentes de IA: loops, ferramentas e paradas

Checklist de harness para agentes de IA com revisão de loops, acesso a ferramentas e condições de parada, para quem aprova um agente antes do lançamento.

Capa tipográfica do Be Human com o título: Checklist de harness para agentes de IA: loops, ferramentas e paradas
Ilustração conceitual criada com IA · Be Human

Um checklist de harness para agentes de IA é uma lista curta de revisão do código e da configuração que envolvem um modelo: o loop que permite ao modelo dar passos repetidos, as ferramentas que ele pode chamar, as permissões ligadas a cada ferramenta e as condições de parada que devolvem o trabalho para uma pessoa. A empresa pode usar essa lista antes do lançamento para decidir se um agente está pronto para trabalho real. O modelo importa, mas a maior parte do risco operacional está no invólucro, então revise o invólucro diretamente.

Principais pontos

  • Revise o harness em volta do modelo: loop, ferramentas, permissões, regras de parada e registros.
  • Todo loop precisa de limites rígidos de passos e de tempo, além de um caminho de saída limpo.
  • Dê a cada ferramenta a menor permissão que basta para concluir a tarefa, com nome claro e esquema de entrada definido.
  • As condições de parada devem cobrir erros, baixa confiança, casos de política e orçamentos esgotados, e não só o sucesso.
  • Aceite um agente somente quando alguém conseguir reproduzir uma execução e ver por que ele agiu daquele jeito.

O que o harness faz e por que revisá-lo separadamente

O modelo lê texto e propõe uma ação. O harness decide o que acontece em seguida: se a ação é executada, quais dados o modelo vê no passo seguinte, quantas tentativas são permitidas e quem é avisado quando algo falha. Muitas equipes revisam o prompt e a escolha do modelo, mas pulam o harness, embora ele determine a maior parte do comportamento que toca clientes e registros. Para uma definição simples dessa camada, veja O que é harness de IA? Um guia prático para negócios.

A revisão separada importa porque cada parte falha de um jeito diferente. Um modelo capaz dentro de um loop sem teto pode continuar chamando uma ferramenta de busca muito depois de a resposta já estar clara. Um loop bem comportado com uma ferramenta que tem acesso de escrita a um sistema em produção pode alterar registros que ninguém pretendia mudar. Revise as partes uma de cada vez e depois verifique como elas interagem, porque um loop seguro e uma ferramenta segura ainda podem produzir uma combinação insegura.

Um teste útil é perguntar se uma pessoa conseguiria interromper o agente no meio de uma tarefa, explicar o que ele já tinha feito e retomar ou desfazer esse trabalho sem adivinhar. Se a resposta depende de ler o prompt, o harness ainda não é revisável.

Parte um do checklist: o loop

O loop é o ciclo de ler o contexto, escolher uma ação, executá-la e ler o resultado. O checklist abaixo pergunta se cada loop tem limites claros.

  • O objetivo está escrito em uma frase, com um critério de sucesso que alguém não técnico consiga ler.
  • Cada execução tem um número máximo de passos e um tempo máximo decorrido, ambos definidos antes do lançamento.
  • O modelo recebe apenas o contexto necessário para o passo atual, e não o histórico completo por padrão.
  • Cada passo registra a entrada, a ação escolhida e o resultado devolvido.
  • Chamadas de ferramenta com falha são repetidas um número fixo de vezes e, depois disso, a execução vai para uma condição de parada.
  • Uma tarefa em andamento pode ser cancelada, e o trabalho parcial fica marcado como parcial, não como concluído.

Os orçamentos são a lacuna mais comum. As equipes costumam definir um limite de gasto no nível da conta e nenhum limite no nível da execução, então uma tarefa travada pode consumir a cota destinada a muitas tarefas. Os limites de passos e de tempo devem ficar dentro do harness, perto do próprio loop, para valer mesmo quando ninguém está olhando. Os detalhes estão em Loop infinito em agentes de IA: limites de passos, tokens e tempo.

Parte dois do checklist: ferramentas e permissões

Ferramentas são as ações que o agente pode executar fora do modelo, como consultar um pedido, redigir uma resposta ou atualizar um chamado. O modelo só pode solicitá-las; o harness decide se a solicitação é executada. As orientações de engenharia da Anthropic sobre como construir agentes eficazes preferem padrões simples e bem definidos a estruturas elaboradas, e a lista OWASP Top 10 para aplicações com LLM aponta a agência excessiva, ou seja, um agente com mais capacidade do que sua tarefa exige, como uma categoria de risco contra a qual se deve projetar.

  • Cada ferramenta tem um nome simples, uma descrição de uma frase e um esquema de entrada definido.
  • Ferramentas de leitura e de escrita são separadas, e as de escrita ficam desligadas até que um revisor as habilite.
  • Cada ferramenta tem um responsável nomeado que aprova mudanças no seu escopo.
  • Ações que movimentam dinheiro, enviam mensagem a um cliente ou apagam dados exigem uma etapa de aprovação humana.
  • As credenciais são restritas a uma única ferramenta e podem ser revogadas sem afetar as demais.
  • As saídas das ferramentas são checadas quanto aos campos esperados antes de o modelo lê-las.

O desenho de permissões fica mais fácil de avaliar quando você consegue ver quais ferramentas uma execução podia usar e quais ela de fato chamou. Onde colocar as etapas de aprovação no fluxo é tratado em Aprovação humana em agentes de IA: onde colocar cada etapa no harness.

Parte três do checklist: condições de parada

Uma condição de parada é uma regra que encerra o loop e entrega o trabalho a uma pessoa ou a um estado seguro. Um harness sem condições de parada depende de o modelo decidir quando terminou, o que funciona em tarefas simples e falha quando o modelo está em dúvida ou quando a entrada é incomum. A lista abaixo cobre os casos que mais costumam exigir uma regra explícita.

  • O teste de sucesso passa, e a execução registra qual evidência o satisfez.
  • O mesmo erro de ferramenta se repete em sequência além de um limite definido, o que dispara um escalonamento.
  • O modelo sinaliza baixa confiança antes de uma ação que altera um registro.
  • A solicitação cai em uma categoria restrita, como um reembolso acima do limite aprovado ou uma questão jurídica.
  • O orçamento de passos ou de tempo se esgota, e o responsável recebe um alerta com o resumo da execução.
  • Conteúdo recuperado contém texto que pede ao agente para ignorar suas regras, e a execução para para revisão.

O último item trata de injeção de prompt. Instruções escondidas dentro de um documento, de um e-mail ou de uma página web podem parecer comandos para um modelo, então o harness deve tratar o conteúdo recuperado como dado e nunca como fonte de novas permissões. As condições de parada funcionam como a última barreira prática quando um modelo é manipulado, porque limitam o que uma execução manipulada consegue fazer antes que uma pessoa a veja. Mais sobre como escrever essas regras está em Condições de parada para agentes de IA: quando parar e escalar.

Parte quatro do checklist: registros e evidências

O harness deve produzir um registro que uma pessoa consiga ler depois. A introdução do OpenTelemetry sobre observabilidade descreve traces, métricas e logs como sinais complementares. Isso se encaixa bem nas execuções de agentes: um trace mostra a sequência de passos, as métricas mostram o uso de orçamento e os motivos de parada em muitas execuções, e os logs guardam os detalhes de uma falha específica.

  • Cada execução tem um identificador, horários de início e fim e um motivo de parada tirado de uma lista fixa.
  • Cada chamada de ferramenta é registrada com suas entradas, seu status e um resultado resumido.
  • A versão do prompt, a versão do esquema de ferramentas e o nome do modelo são anexados a cada execução.
  • Dados pessoais nos logs são reduzidos ou anonimizados de acordo com as regras de dados da empresa.
  • Os motivos de parada são revisados em uma agenda, para que uma categoria que comece a crescer receba atenção cedo.

Sem esses campos, uma execução ruim vira uma discussão sobre o que aconteceu. Com eles, a revisão leva minutos e a correção pode atacar a causa. Registrar pouco esconde falhas, enquanto registrar tudo cria problemas de privacidade e de custo, então defina os campos com intenção.

Cenário ilustrativo: um agente de pedidos de devolução

O cenário a seguir é ilustrativo e não descreve um cliente real. Um agente de devolução lê a mensagem de um cliente, consulta o pedido e redige uma resposta para um atendente enviar. O loop dele tem limite de passos, e a ferramenta de consulta é somente leitura. Em uma execução, a consulta ao pedido devolve o mesmo erro de serviço várias vezes seguidas. A condição de parada por erro repetido dispara, a execução termina sem resposta, e o caso vai para a fila da equipe com a referência do pedido, o texto do erro e os passos já executados.

O revisor percebe depois que o serviço de consulta estava indisponível, e não que o pedido do cliente estava errado. O agente também nunca teve permissão para emitir reembolso, então seu rascunho não podia prometer um. O harness funcionou como planejado, e o registro explicou o resultado sem depender de o modelo explicar a si mesmo.

Como a Be Human trabalha isso em uma operação gerenciada

A Be Human projeta, implementa e opera infraestrutura de IA personalizada, incluindo o harness em volta de cada agente. Um primeiro projeto define um papel útil, a memória e as ferramentas que esse papel precisa, os limites de aprovação e um critério de sucesso observável, para que o checklist acima seja aplicado a um agente específico e não a uma ideia genérica. A operação gerenciada cobre então o acompanhamento de motivos de parada e de orçamentos, avaliações recorrentes, revisão de permissões quando ferramentas ou funções da equipe mudam, resposta a incidentes e melhorias controladas que são publicadas com uma versão registrada. O trabalho é remoto e disponível em inglês e português.

Faça o diagnóstico gratuito de IA da Be Human para descobrir a primeira tarefa que vale a pena entregar a um agente.

Perguntas frequentes

O que é um harness de agente? Um harness de agente é a camada de software em volta de um modelo que executa o loop, entrega o contexto, expõe as ferramentas, aplica as permissões e registra o que acontece. O modelo propõe ações, e o harness decide se elas são executadas. Para uma empresa, é no harness que a maior parte do risco operacional é controlada, então ele merece uma revisão própria.

Qual condição de parada a equipe deve adicionar primeiro? Comece pela regra que protege contra o erro mais caro, normalmente uma regra que entrega o trabalho a uma pessoa quando uma ação alteraria um registro, enviaria uma mensagem ou gastaria dinheiro. Em seguida, adicione uma regra de erro repetido e um teto de orçamento. Essas três cobrem boa parte do comportamento descontrolado que as equipes observam sem exigir lógica elaborada.

A empresa deve construir o próprio harness ou usar um fornecedor? A resposta depende de quem vai manter o invólucro quando modelos e ferramentas mudarem. Construir dá controle total, mas cria trabalho contínuo, enquanto um serviço gerenciado pode assumir parte dessa carga operacional. Compare as opções perguntando quem cuida do monitoramento, da revisão de permissões e da resposta a incidentes, e quem registra cada mudança.

Como saber se o harness está funcionando? Revise os registros de execução em um período fixo: com que frequência as execuções têm sucesso, com que frequência param e por quê, e se os escalonamentos chegam a uma pessoa com detalhes suficientes para agir. Um harness funciona quando um revisor consegue explicar qualquer execução apenas com o seu registro. Avaliações regulares com um conjunto fixo de tarefas de teste também mostram se uma mudança melhorou o agente ou piorou.

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.

Menos tarefas. Mais espaço para você.

Traga o trabalho para o qual falta tempo.

Agende uma conversa e teste 7 dias grátis um agente de IA personalizado ↗Ou faça o diagnóstico gratuito de IA →