Engenharia de contexto para agentes de IA de longo horizonte

Em conjunto, a análise da Arize, o artigo da arXiv sobre transbordamento da janela de contexto, o explicador de produção da Redis e a comparação de engenharia de harness da Atlan apontam para uma mudança prática no design de agentes. Agentes de longa duração estão sendo avaliados menos pelo tamanho da janela de contexto do modelo e mais pela camada de controle ao redor dela. A Arize torna essa mudança concreta. Ela cita ferramentas de agentes e sistemas de memória/harness já lançados, incluindo Pi, OpenClaw, Claude Code e Letta, como exemplos de engenharia de contexto no nível do harness, e descreve um simulador interativo que mostra uma janela de 200K tokens sendo preenchida.

Os detalhes públicos disponíveis nas fontes citadas são irregulares. A Arize fornece números concretos de implementação para Pi, OpenClaw, Claude Code e Letta. Um artigo de pesquisa sobre como resolver o transbordamento da janela de contexto em agentes de IA apresenta um mecanismo mais geral para lidar com saídas de ferramentas que podem exceder qualquer janela prática. O explicador da Redis sobre transbordamento da janela de contexto resume os sintomas em produção: erros rígidos de API, degradação silenciosa da qualidade, acúmulo de saídas de ferramentas e maior latência à medida que os prompts crescem. A comparação da Atlan entre engenharia de prompt, contexto e harness oferece a metáfora útil de pilha: a engenharia de prompt molda a mensagem, a engenharia de contexto molda o que o modelo vê, e a engenharia de harness molda todo o ambiente do agente.

A notícia importante não é que as janelas de contexto são pequenas demais. Builders já sabem disso. O ponto mais útil é que os sistemas de agentes citados estão convergindo para quatro mecanismos de harness que mantêm o trabalho vivo depois que a transcrição deixa de ser uma fonte segura da verdade.

Um agente superficial lê arquivos, chama ferramentas, anexa o resultado e espera que o modelo dê conta. Um agente orientado por harness bloqueia ou remodela entradas grandes antes que elas cheguem ao modelo.

Uma forma mais clara de ler o primeiro conjunto de limites é:

• Pi: leituras de arquivos param em 2.000 linhas ou 50KB, o que vier primeiro. O conteúdo retornado inclui uma dica de continuação informando ao modelo qual intervalo de linhas foi mostrado e como continuar com offset e limit. O OpenClaw herda esse comportamento e depois adiciona limites separados: arquivos de bootstrap são limitados a 12.000 caracteres por arquivo e 60.000 caracteres no total. Resultados de ferramentas recebem outro orçamento de 16.000 caracteres ou 30% da janela de contexto, o que for menor.

Claude Code usa um design de duas portas. Segundo a Arize, ele verifica um limite de 256KB em bytes antes de abrir um arquivo e depois conta tokens do resultado contra um orçamento de 25.000 tokens após a leitura. Mesmo para arquivos abaixo do limite, o padrão é retornar 2.000 linhas a partir do início e truncar linhas com mais de 2.000 caracteres. Se o modelo relê o mesmo intervalo de arquivo e o arquivo não mudou, o Claude Code pode retornar um stub em vez de repetir o conteúdo completo.

Isso não é apenas otimização. Muda o modo de falha. Em vez de permitir que uma leitura grande expulse a tarefa, o harness transforma “ler tudo” em “ler uma fatia controlada”. Se o modelo precisar de mais, pode pedir. Para builders que projetam harnesses de agentes do zero, esta é a primeira linha de defesa: nunca deixe dados externos brutos virarem a transcrição por padrão.

O próximo padrão é tratar o contexto como uma viewport, não como armazenamento.

Pi e Claude Code expõem paginação por meio de offset e limit. O OpenClaw adiciona truncamento de cabeça/cauda em alguns lugares, mantendo o início e o fim quando o meio tem menor probabilidade de importar. A Arize diz que o OpenClaw usa uma divisão de 75% cabeça / 25% cauda para arquivos de bootstrap grandes demais, e pode manter tanto a cabeça quanto a cauda para resultados de ferramentas quando a cauda parece importante, como erros, chaves de fechamento de JSON ou palavras-chave com cara de resumo.

Letta vai além ao fazer os arquivos viverem fora do prompt. Arquivos enviados são analisados, divididos em chunks e incorporados a um vector store, dando ao agente visualização direta, busca exata e busca semântica. Quando um arquivo está aberto em contexto, o Letta mostra uma visualização gerenciada cujo tamanho escala com o contexto do modelo: 5.000 caracteres para contexto de 8K, 15.000 para 32K, 25.000 para 128K e 40.000 para 200K+. O número de arquivos simultaneamente abertos também escala, de 3 para modelos pequenos até 15 para modelos muito grandes, com uma política LRU expulsando os arquivos acessados há mais tempo.

Essa é a mesma ideia de design por trás de RAG em produção: não colocar o corpus inteiro no prompt; recuperar a parte que importa. A diferença é que harnesses de agentes precisam fazer isso continuamente, entre arquivos, saídas de ferramentas, memória e planos intermediários. A mesma restrição se aplica a sistemas RAG: recuperação não trata apenas de relevância, mas também de preservar orçamento de contexto suficiente para a etapa real de raciocínio.

A Redis faz um ponto relacionado: janelas de contexto maiores não eliminam a necessidade de gerenciamento de contexto. Prompts de sistema, documentos recuperados, histórico de conversa e saídas de ferramentas competem todos pelo mesmo espaço. Mesmo antes de atingir um limite rígido, os modelos podem degradar quando informações relevantes ficam enterradas em entradas longas.

Transbordamento é a falha óbvia. Perda de objetivo é mais silenciosa. O agente ainda tem espaço para responder, mas esquece o objetivo original, perde uma restrição ou começa a otimizar uma subtarefa local.

É aí que a compactação importa. Mal feita, a sumarização substitui um histórico bagunçado, mas fiel, por uma história organizada, porém com perdas. Bem feita, ela preserva o estado da tarefa, o trabalho recente, itens pendentes e a integridade das chamadas de ferramentas.

A Arize relata que o Pi aciona compactação quando os tokens de contexto estimados excedem a janela de contexto menos tokens de reserva, com uma reserva padrão de 16.384 tokens. Ele mantém aproximadamente os 20.000 tokens mais recentes e resume o conteúdo mais antigo em uma mensagem sintética de usuário prefixada à cauda mantida. Ele também evita cortar pares de chamada de ferramenta/resultado de ferramenta.

O OpenClaw adiciona uma política de histórico mais agressiva. Quando o histórico excede 50% da janela de contexto, ele divide mensagens em chunks de tokens de massa igual, descarta o chunk mais antigo, resume o conteúdo descartado por meio de sumarização multi-pass em etapas e repara o pareamento entre chamada de ferramenta e resultado. Ele também executa um flush pré-compactação: um turno agêntico silencioso dá ao agente a chance de persistir estado em arquivos de memória antes que o histórico desapareça. Separadamente, ele poda resultados de ferramentas na memória com comportamento de soft-trim e hard-clear em um TTL de cache de 5 minutos.

Claude Code compacta perto do fim da janela. A Arize diz que o gatilho é a janela de contexto efetiva menos um buffer de 13.000 tokens, o que coloca a compactação por volta de 167K tokens para um modelo com contexto de 200K. Seu prompt de sumarização pede seções estruturadas cobrindo a solicitação principal, conceitos técnicos, arquivos e código, erros e correções, resolução de problemas, mensagens do usuário, tarefas pendentes, trabalho atual e próximo passo. Após a compactação, ele pode reanexar até 5 arquivos lidos recentemente dentro de um orçamento de tokens.

O padrão é claro: compactação não é “resumir o chat”. É checkpointing. Um agente de longa duração precisa do equivalente a um arquivo de salvamento: objetivo, restrições, decisões, handles abertos, evidências recentes e próxima ação.

Algumas saídas nunca deveriam ser colocadas na janela de contexto.

O artigo da arXiv torna isso concreto com um fluxo de trabalho de ciência dos materiais. Uma ferramenta gera uma estrutura de grade eletrônica para uma molécula: uma matriz 3D de dimensões 128 × 128 × 128, totalizando 2.097.152 elementos float32. Essa saída excede em muito a janela de contexto de LLMs amplamente usados. Mas a próxima ferramenta precisa da grade como entrada.

A solução proposta é armazenar valores grandes fora do contexto do modelo e retornar identificadores curtos, ou ponteiros. Wrappers de ferramentas inspecionam entradas para ver se são valores brutos ou caminhos de memória. Saídas grandes demais são armazenadas na memória de execução sob um caminho, e ferramentas posteriores podem receber o ponteiro e resolvê-lo internamente. O modelo manipula referências, enquanto o harness preserva os dados completos. Em um experimento comparativo em que ambos os métodos tiveram sucesso, a abordagem baseada em ponteiros usou aproximadamente sete vezes menos tokens que o fluxo de trabalho tradicional, segundo o artigo.

Essa é a separação mais limpa entre raciocínio e transporte de dados. O modelo não precisa “ver” uma matriz de 2 milhões de elementos para passá-la a outra ferramenta. Ele precisa saber que a matriz existe, o que ela representa e qual operação deve consumi-la em seguida.

A mesma lógica se aplica além de arrays científicos. Grandes respostas JSON, PDFs, logs, embeddings, arquivos de mídia e exportações de bancos de dados frequentemente pertencem ao armazenamento, não ao prompt. Para sistemas construídos em torno de ferramentas MCP ou conectores de API personalizados, passar ponteiros deve ser uma escolha de design de primeira classe, não um remendo depois do primeiro transbordamento.

Uma janela de contexto de 200K tokens parece grande até um agente começar a agir. Um prompt de sistema, definições de ferramentas, alguns documentos recuperados, leituras de arquivos, logs, rastros de erro e resumos podem consumi-la mais rápido do que o esperado. O enquadramento prático não é quão grande a janela parece no papel, mas quão rapidamente os agentes a gastam em runtime. A orientação da Redis sobre memória de agentes aponta para memória externa e durável para estados que devem sobreviver entre chamadas, enquanto o enquadramento de engenharia de contexto da Atlan separa prompts melhores de melhor montagem de contexto. Juntos, eles tratam a janela de contexto menos como um depósito e mais como um conjunto de trabalho restrito.

A lição mais profunda é que uma janela de contexto é um recurso escasso em runtime. Tratá-la como “memória” é útil, mas só se o harness se comportar como um sistema operacional: alocar, expulsar, paginar, compactar, deduplicar e persistir. A distinção de camadas da Atlan é útil aqui. Engenharia de prompt não corrige um leitor de arquivos que despeja 80.000 tokens irrelevantes na próxima chamada. Engenharia de contexto pode melhorar o conjunto de trabalho. Engenharia de harness decide se esse conjunto de trabalho está protegido em primeiro lugar.

Isso também muda como equipes devem avaliar agentes. Um prompt de demonstração não basta. A avaliação de longo horizonte deve incluir transcrições crescentes, leituras repetidas de arquivos, grandes saídas de ferramentas, chamadas de ferramentas com falha, retomadas após compactação e tarefas em que o próximo passo correto depende de uma restrição inicial. Nosso guia de engenharia de contexto para agentes cobre a versão do problema no lado do modelo; a camada de harness é onde ele se torna operacional.

Primeiro, coloque orçamentos em cada fonte de contexto. Arquivos, saídas de ferramentas, chunks recuperados, inserções de memória e histórico de conversa devem ter limites explícitos. Uma única contagem global máxima de tokens é grosseira demais.

Segundo, torne o truncamento acionável. Se o harness corta conteúdo, o modelo deve saber qual intervalo viu e como solicitar mais. Truncamento silencioso é pior que rejeição porque cria trabalho confiante sobre dados ausentes.

Terceiro, compacte em torno do estado, não da prosa. Resumos devem preservar o objetivo do usuário, restrições, decisões, tarefas pendentes, arquivos tocados, resultados de ferramentas que importam e o próximo passo imediato. Pares de chamadas de ferramentas devem permanecer intactos.

Quarto, mova valores grandes para fora do prompt. Armazene-os, nomeie-os e passe ponteiros pelas ferramentas. Isso é especialmente importante para agentes que chamam APIs, processam documentos ou coordenam sistemas multiagente.

Por fim, teste perda de objetivo separadamente de transbordamento. Um agente pode ficar abaixo da janela rígida e ainda assim se desviar. A pergunta certa não é apenas “a API aceitou o prompt?”. É “a próxima ação ainda serve à tarefa original?”.

O resumo abaixo transforma esses padrões em um checklist rápido antes do FAQ.

• Agentes de longo horizonte falham tanto por transbordamento de contexto quanto por perda de objetivo, então o harness precisa gerenciar mais que o tamanho do prompt.
• Sistemas de agentes em produção usam orçamentos rígidos para arquivos, saídas de ferramentas e histórico antes que dados brutos cheguem ao modelo.
• Paginação, busca e visualizações gerenciadas tratam o contexto como uma viewport limitada, não como armazenamento permanente.
• Compactação funciona melhor como checkpointing: ela preserva objetivos, restrições, decisões, trabalho pendente e a integridade das chamadas de ferramentas.
• Saídas grandes de ferramentas muitas vezes pertencem a armazenamento externo, com ponteiros curtos passados entre ferramentas em vez de valores completos no prompt.

Esta seção responde às perguntas práticas por trás da engenharia de contexto para agentes de longo horizonte: o que transborda, como objetivos se perdem e quais padrões de harness mantêm o trabalho no caminho certo.

Transbordamento de contexto acontece quando o prompt acumulado, o histórico, os dados recuperados, os arquivos e as saídas de ferramentas de um agente excedem a janela de contexto utilizável do modelo ou degradam a qualidade antes que o limite rígido seja atingido.

Perda de objetivo acontece quando a tarefa original ainda está presente em algum lugar da transcrição, mas já não guia a próxima ação do agente, muitas vezes após históricos longos ou sumarização ruim.

Eles definem orçamentos por fonte, paginam leituras de arquivos, recuperam apenas visualizações relevantes, compactam o histórico em torno do estado, deduplicam leituras repetidas e armazenam grandes saídas fora do prompt.

Ponteiros permitem que o modelo se refira a valores grandes armazenados na memória de execução, como matrizes, logs ou PDFs, enquanto ferramentas downstream resolvem os dados completos sem colocá-los na janela de contexto.

Não. Janelas maiores ajudam, mas prompts de sistema, definições de ferramentas, documentos recuperados, logs e histórico ainda competem por espaço, e informações relevantes podem ficar enterradas antes que um limite rígido seja atingido.