Truncar e resumir resultados de ferramentas para caber no orçamento de contexto

Objetivo

Evitar que a saída das ferramentas ocupe o espaço da tarefa no contexto de um agente, sem perder nada de que o agente ainda precise para decidir corretamente.

Pré-requisitos

Uma camada de ferramentas controlada pelo host do agente (o código que executa a ferramenta e monta a mensagem de resultado), um lugar para gravar as saídas completas (um diretório temporário) e uma noção, para cada ferramenta, do que importa na saída: em um executor de testes, as falhas; em uma leitura de arquivo, o intervalo pedido; em uma busca, as ocorrências com suas localizações.

Passos

1. Defina um limite por ferramenta, em bytes, e um limite menor para as ferramentas cuja saída raramente é lida por inteiro (listagens de diretório, logs). Registre o limite na descrição da ferramenta, para que o modelo saiba que os resultados podem ser cortados.
2. Filtre na origem antes de devolver o resultado: grep com um padrão em vez de cat, jq em JSON, LIMIT em SQL, flags --quiet, tail em logs.
3. Se o resultado ainda ultrapassar o limite, mantenha o início e o fim e substitua o meio por uma única linha de marcação que diga o que foi removido e onde está a saída completa: [... 61,204 of 74,880 bytes omitted; full output in /tmp/run/out-17.txt ...]. O fim é importante porque os resumos de erro e os códigos de saída aparecem por último.
4. Nunca corte no meio de um registro: em JSON, devolva o esquema, a contagem e os primeiros registros como JSON válido; em tabelas, mantenha linhas inteiras; em diffs, mantenha hunks inteiros.
5. Mantenha os erros inteiros; limite o stderr separadamente e com folga. Um stack trace truncado custa mais chamadas do que economiza em bytes.
6. Depois que um resultado foi usado, limpe-o ou substitua-o por um resumo de uma linha que preserve os identificadores. O post de engenharia da Anthropic citado chama a limpeza de resultados de ferramentas de uma das formas de compactação mais seguras e menos intrusivas, e a documentação do fornecedor sobre edição de contexto descreve a estratégia clear_tool_uses_20250919, que limpa automaticamente os resultados de ferramentas mais antigos quando o contexto ultrapassa um limiar configurado e substitui cada um por um texto provisório.
7. Para tarefas que por natureza inundam o contexto (ler muitos arquivos, buscas longas), delegue a um subagente que, nas palavras da documentação do agente de programação, faz o trabalho no seu próprio contexto e devolve apenas o resumo.

Resultado esperado

Resultados de ferramentas que ocupam uma parcela previsível do contexto, com todo corte sinalizado e recuperável a partir do disco, e nenhuma decisão tomada sobre uma parte invisível de uma saída.

Limites e base de verificação

Os limites são definidos por julgamento, não por um ótimo medido; a pergunta em aberto desta wiki sobre a parcela da saída de ferramentas em execuções reais pede os dados que faltam. Um resumo escrito pelo modelo pode omitir o que importava; mantenha o ponteiro para a saída completa até a tarefa terminar.