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

Fundamentos de harness

Truncamento de resultados em agentes de IA: mantenha os campos que decidem

Como encurtar saídas grandes de ferramentas em um harness de agente de IA sem perder status, identificadores e campos de erro que definem a próxima ação.

Capa tipográfica do Be Human com o título: Truncamento de resultados em agentes de IA: mantenha os campos que decidem
Ilustração conceitual criada com IA · Be Human

Truncamento de resultados de ferramentas é a etapa em que o harness encurta a saída de uma ferramenta antes que o modelo a leia, para que o contexto fique pequeno o bastante para o agente raciocinar bem. Uma regra sólida mantém os campos que decidem a próxima ação, como status, identificadores, mensagens de erro e pontos de continuação, e remove o volume em torno deles. O harness nunca deve descartar esses campos de decisão em silêncio, e cada corte deve deixar uma nota visível dizendo o que foi omitido e como buscar o restante.

Principais pontos

  • Trunque pelo papel de cada campo, e não pelo número bruto de caracteres.
  • Mantenha status, identificadores, erros e pontos de continuação em todo resultado, qualquer que seja o tamanho.
  • Marque cada corte com uma nota visível e um caminho de busca, para que o agente possa pedir mais.
  • Teste o truncamento contra as decisões que o agente precisa tomar, e não contra a aparência de saída curta.
  • Guarde o resultado bruto completo fora do contexto do agente, para que um revisor consiga verificar o que o agente viu e o que deixou de ver.

Por que saídas grandes quebram decisões do agente

Quando um agente chama uma ferramenta, o resultado entra no contexto de trabalho e disputa espaço com as instruções, com a tarefa e com o histórico do que o agente já fez. Uma busca em um sistema grande de registros pode devolver muito mais texto do que a próxima etapa precisa. À medida que o contexto enche, o custo e a latência sobem, e o modelo passa a pesar textos longos e repetitivos contra a linha curta que realmente importa, como uma flag de status no fim de um log. Um padrão comum em harnesses simples é cortar a saída pelo final, justamente onde costumam aparecer os status finais, os totais e os códigos de erro.

A falha é silenciosa. O agente não quebra. Ele segue com um quadro parcial e toma uma ação que parece razoável com base no que viu. Por isso o truncamento pertence ao desenho do harness, e não a um detalhe para resolver depois. O harness decide o que o modelo enxerga, então o harness também responde pelas consequências do que esconde.

Quais campos decidem a próxima ação?

Antes de escrever qualquer código de truncamento, liste as decisões que cada ferramenta sustenta e os campos das quais essas decisões dependem. A maioria dos resultados se encaixa em poucos grupos.

  • Campos de identidade: o ID do registro, a conta, o número do pedido ou a referência do documento que o agente vai reutilizar em chamadas seguintes.
  • Campos de estado: o status atual, a etapa, a hora da última mudança e qualquer flag que libere ou bloqueie o próximo passo.
  • Campos de erro: códigos de erro, motivos de falha e sugestões de nova tentativa, que nunca devem ser reduzidos a um resumo vago.
  • Campos de continuação: cursores, tokens de página e contagens totais, para que o agente saiba se viu tudo.
  • Campos de responsabilidade e permissão: a quem o registro pertence e se o agente pode agir sobre ele.
  • Conteúdo volumoso: descrições longas, corpos completos de mensagens, logs brutos e itens repetidos, que normalmente podem ser encurtados ou tirados do contexto.

Mantenha inteiros os cinco primeiros grupos. O conteúdo volumoso é onde o truncamento deve trabalhar mais. Um teste útil: se remover um campo mudaria qual ferramenta o agente chama em seguida, ou se ele chamaria alguma, esse campo é de decisão.

Quais métodos preservam os campos de decisão?

Vários métodos funcionam, e a maioria dos harnesses em produção combina alguns deles. A projeção de campos devolve apenas o que uma tarefa específica precisa, e costuma ser a abordagem mais simples e confiável, porque a regra fica visível na definição da ferramenta. A limitação de registros devolve a primeira página, a contagem total e um cursor, para que o agente saiba que existe mais. Para logs e textos longos, mantenha as primeiras linhas como contexto e as últimas como estado final, e fixe qualquer linha que combine com um padrão de erro, mesmo quando ela estiver no meio.

Resumir é tentador, mas exige cuidado. Um resumo produzido por um modelo é uma segunda etapa com perda, e pode eliminar um identificador ou suavizar um erro. Se você resumir, mantenha a saída bruta guardada, coloque identificadores e status em campos simples ao lado do resumo, e nunca deixe o resumo substituí-los. As orientações da Anthropic sobre como escrever ferramentas para agentes apontam uma ideia próxima: devolver menos resultados, com mais sinal, e deixar o agente pedir detalhes costuma funcionar melhor do que devolver tudo e esperar que o modelo encontre a parte certa.

Dê ao agente uma forma de pedir mais. Um resultado truncado que indica uma chamada de acompanhamento para o registro completo é muito mais seguro do que um resultado que simplesmente termina. Assim, o agente decide se o histórico antigo importa para a pergunta que tem em mãos.

Plano passo a passo para o seu harness

Use esta sequência para cada ferramenta que o agente pode chamar.

  • Passo um: escreva as decisões que a ferramenta sustenta e os campos que cada decisão lê.
  • Passo dois: marque cada campo como decisão, identidade, erro, continuação ou volume.
  • Passo três: defina uma projeção que sempre devolva os campos de decisão, independentemente do tamanho da saída.
  • Passo quatro: defina um limite de tamanho para os campos volumosos, com uma ordem fixa do que é cortado primeiro.
  • Passo cinco: acrescente uma nota de truncamento visível, que informe o que foi omitido, a contagem total e a chamada de acompanhamento.
  • Passo seis: guarde o resultado bruto completo fora do contexto do agente, vinculado ao ID da execução.
  • Passo sete: escreva casos de teste com resultados grandes em que o campo decisivo aparece no fim, no meio e dentro de um objeto aninhado.
  • Passo oito: registre cada evento de truncamento com o nome da ferramenta, o tamanho original, o tamanho devolvido e se havia campo de erro, para que os revisores identifiquem padrões.

Mantenha esse plano sob controle de versão, junto da definição da ferramenta. Quando o formato de resposta de uma ferramenta mudar, a regra de truncamento deve mudar na mesma revisão, e não semanas depois, quando alguém perceber uma resposta errada.

Cenário ilustrativo: uma dúvida sobre reembolso

Cenário ilustrativo: um agente de suporte é questionado sobre se o reembolso de um cliente já foi compensado. A ferramenta de histórico de pedidos devolve muitas linhas, e o estado do reembolso está no último registro. Um harness ingênuo mantém apenas o começo da saída e corta o resto. O agente vê um pedido e um pagamento, conclui que o reembolso ainda está pendente, quando na verdade ele foi concluído. Em seguida, abre uma solicitação de reembolso duplicada.

Um harness com regras por campo se comporta de outra forma. Ele devolve o ID do pedido, o estado atual do reembolso, a data e hora da última mudança de estado, qualquer erro da etapa de pagamento e um cursor para o histórico mais antigo. Acrescenta uma nota dizendo que eventos anteriores foram omitidos e indica a chamada que os busca. O agente lê o estado concluído, responde corretamente e pede o histórico antigo apenas se a pergunta exigir. A diferença não está na quantidade de texto. Está em quais campos sobreviveram ao corte.

Onde entra a abordagem gerenciada da Be Human

A Be Human trata o formato dos resultados das ferramentas como parte do contexto operacional do agente, e não como um detalhe deixado a cada integração. Em um primeiro projeto, a equipe mapeia as decisões que cada papel de agente precisa tomar, identifica os campos de que essas decisões dependem e combina as regras de truncamento com o dono do negócio antes de qualquer coisa entrar em produção. A operação gerenciada então mantém essas regras atualizadas. As revisões de permissões e integrações detectam mudanças no formato das respostas, as avaliações recorrentes passam resultados grandes e casos de borda pelo agente, e a resposta a incidentes examina qualquer ação tomada com base em um resultado truncado. O objetivo é um agente que a equipe consegue inspecionar, e não um agente que trabalha em silêncio com informação incompleta.

Como testar o truncamento e por onde começar?

Teste o truncamento da mesma forma que testa o agente: com casos que contenham a decisão, e com a decisão posicionada onde um corte ingênuo a removeria. Mantenha um conjunto pequeno de resultados grandes vindos de chamadas reais de ferramentas, com dados pessoais removidos, e execute-os de novo sempre que a ferramenta ou as regras mudarem. A introdução à observabilidade do OpenTelemetry é uma referência útil para os sinais de que você precisa, como tamanhos de resultado, quantidade de cortes e presença de erro, registrados sem armazenar conteúdo sensível nos traces. Trate também a saída das ferramentas como texto não confiável. As orientações da OWASP sobre injeção de prompt lembram que o conteúdo devolvido ao modelo pode carregar instruções, por isso o truncamento nunca deve transformar uma linha do meio de um resultado em algo que o agente trate como instrução. Para controles relacionados, leia sobre limites de passos e tokens para agentes e sobre checkpoints para retomar o trabalho.

Se você não tem certeza de qual ferramenta da sua empresa merece esse trabalho primeiro, faça o diagnóstico gratuito de IA da Be Human para encontrar a primeira tarefa que vale entregar a um agente.

Perguntas frequentes

Quanto um harness deve truncar os resultados das ferramentas? Não existe um limite universal, e um teto fixo de tamanho é o ponto de partida errado. Defina limites por papel de campo, para que os campos de decisão sejam sempre devolvidos e apenas o conteúdo volumoso encolha. Ajuste os limites quando as avaliações mostrarem que o agente deixou de ver uma informação de que precisava.

O modelo deve resumir grandes resultados de ferramentas em vez de truncá-los? Resumos podem ajudar com textos narrativos longos, mas têm perda e podem eliminar identificadores ou suavizar erros. Mantenha o resultado bruto guardado, devolva os campos de decisão como valores simples ao lado de qualquer resumo e garanta que o resumo nunca os substitua. Use o resumo como apoio para a leitura, e não como fonte de registro.

O que deve acontecer quando o agente precisa da parte que foi cortada? O resultado truncado deve indicar a chamada de acompanhamento que devolve o registro completo ou a página seguinte, junto da contagem total. O agente então pede o que precisa, e o harness registra essa solicitação. Isso mantém o contexto padrão pequeno sem tornar os dados omitidos inacessíveis.

Quem deve ser dono das regras de truncamento em uma empresa? As pessoas que entendem as decisões do negócio devem definir quais campos importam, e a engenharia ou a equipe de operação gerenciada deve implementar e versionar as regras. Revise-as sempre que o formato de resposta de uma ferramenta mudar ou quando uma nova permissão for concedida. Trate as regras como qualquer outro controle operacional, com um responsável nomeado e um registro de cada mudança.

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 →