Engenharia de contexto para agentes de IA de longo horizonte

Em conjunto, a análise da Arize, o artigo arXiv sobre transbordo da janela de contexto, o explicador de produção da Redis e a comparação de engenharia de camadas de orquestração da Atlan apontam para uma mudança prática no desenho de agentes. Agentes de longa duração estão a ser avaliados menos pelo tamanho da janela de contexto do modelo e mais pela camada de controlo à sua volta. A Arize torna essa mudança concreta. Nomeia ferramentas de agentes e sistemas de memória/camada de orquestração já lançados, incluindo Pi, OpenClaw, Claude Code e Letta, como exemplos de engenharia de contexto ao nível da camada de orquestração, e descreve um simulador interativo que mostra uma janela de 200K tokens a encher.

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

A notícia importante não é que as janelas de contexto sejam demasiado pequenas. Os construtores já sabem isso. O ponto mais útil é que os sistemas de agentes citados estão a convergir em quatro mecanismos de camada de orquestração que mantêm o trabalho vivo depois de a transcrição deixar de ser uma fonte de verdade segura.

Um agente superficial lê ficheiros, chama ferramentas, acrescenta o resultado e espera que o modelo aguente. Um agente orientado primeiro pela camada de orquestração bloqueia ou reformata inputs grandes antes de chegarem ao modelo.

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

• Pi: as leituras de ficheiros param nas 2.000 linhas ou nos 50KB, o que ocorrer primeiro. O conteúdo devolvido inclui uma indicação de continuação que diz ao modelo que intervalo de linhas foi mostrado e como continuar com offset e limit. O OpenClaw herda esse comportamento e depois acrescenta limites separados: ficheiros de bootstrap estão limitados a 12.000 caracteres por ficheiro e 60.000 caracteres no total. Os resultados de ferramentas recebem outro orçamento de 16.000 caracteres ou 30% da janela de contexto, o que for menor.

O Claude Code usa um desenho com duas portas. Segundo a Arize, verifica um limite de 256KB em bytes antes de abrir um ficheiro e, depois da leitura, conta os tokens do resultado face a um orçamento de 25.000 tokens. Mesmo para ficheiros abaixo do limite, por predefinição devolve 2.000 linhas a partir do início e trunca linhas com mais de 2.000 caracteres. Se o modelo reler o mesmo intervalo de ficheiro e o ficheiro não tiver mudado, o Claude Code pode devolver um stub em vez de repetir o conteúdo completo.

Isto não é apenas otimização. Muda o modo de falha. Em vez de deixar que uma leitura grande afaste a tarefa, a camada de orquestração transforma «ler tudo» em «ler uma fatia controlada». Se o modelo precisar de mais, pode pedi-lo. Para construtores a desenhar camadas de orquestração de agentes do zero, esta é a primeira linha de defesa: nunca deixar que dados externos em bruto se tornem a transcrição por predefinição.

O padrão seguinte é tratar o contexto como uma janela de visualização, não como armazenamento.

Pi e Claude Code expõem paginação através de offset e limit. O OpenClaw acrescenta truncagem head/tail em alguns pontos, mantendo o início e o fim quando é menos provável que o meio seja relevante. A Arize diz que o OpenClaw usa uma divisão de 75% head / 25% tail para ficheiros de bootstrap demasiado grandes, e pode manter tanto o head como o tail para resultados de ferramentas quando o tail parece importante, como erros, chavetas de fecho de JSON ou palavras-chave que parecem resumos.

A Letta vai mais longe ao fazer com que os ficheiros vivam fora do prompt. Ficheiros carregados são analisados, divididos em chunks e embebidos numa base vetorial, dando ao agente visualização direta, pesquisa exata e pesquisa semântica. Quando um ficheiro está aberto no contexto, a Letta mostra uma vista gerida 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 ficheiros abertos em simultâneo também escala, de 3 para modelos pequenos até 15 para modelos muito grandes, com uma política LRU a expulsar os ficheiros acedidos há mais tempo.

Esta é a mesma ideia de desenho por trás do RAG em produção: não meter todo o corpus no prompt; recuperar a parte que interessa. A diferença é que as camadas de orquestração de agentes têm de o fazer continuamente, entre ficheiros, outputs de ferramentas, memória e planos intermédios. A mesma restrição aplica-se a sistemas RAG: a recuperação não é apenas sobre relevância, mas também sobre preservar orçamento de contexto suficiente para o passo de raciocínio propriamente dito.

A Redis faz um ponto relacionado: janelas de contexto maiores não eliminam a necessidade de gestão de contexto. Prompts de sistema, documentos recuperados, histórico de conversa e outputs de ferramentas competem todos pelo mesmo espaço. Mesmo antes de se atingir um limite rígido, os modelos podem degradar-se quando a informação relevante fica enterrada em inputs longos.

O transbordo é a falha óbvia. A perda do objetivo é mais silenciosa. O agente ainda tem espaço para responder, mas esquece o objetivo original, falha 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 confuso mas fiel por uma história arrumada mas com perdas. Bem feita, preserva o estado da tarefa, trabalho recente, itens pendentes e integridade das chamadas de ferramentas.

A Arize relata que o Pi aciona a compactação quando os tokens de contexto estimados excedem a janela de contexto menos os tokens de reserva, com uma reserva predefinida de 16.384 tokens. Mantém aproximadamente os 20.000 tokens mais recentes e resume o conteúdo mais antigo numa mensagem de utilizador sintética acrescentada antes da cauda mantida. Também evita cortar pares chamada de ferramenta/resultado de ferramenta.

O OpenClaw acrescenta uma política de histórico mais agressiva. Quando o histórico excede 50% da janela de contexto, divide as mensagens em chunks de massa de tokens equivalente, elimina o chunk mais antigo, resume o conteúdo eliminado através de sumarização faseada em várias passagens e repara o emparelhamento chamada de ferramenta/resultado. Também executa um flush pré-compactação: uma ronda agêntica silenciosa dá ao agente uma oportunidade de persistir estado em ficheiros de memória antes de o histórico desaparecer. Separadamente, poda resultados de ferramentas em memória com comportamento de soft-trim e hard-clear num TTL de cache de 5 minutos.

O Claude Code compacta perto do fim da janela. A Arize diz que o seu gatilho é a janela de contexto efetiva menos um buffer de 13.000 tokens, o que coloca a compactação perto dos 167K tokens para um modelo com contexto de 200K. O seu prompt de sumarização pede secções estruturadas que cubram o pedido principal, conceitos técnicos, ficheiros e código, erros e correções, resolução de problemas, mensagens do utilizador, tarefas pendentes, trabalho atual e próximo passo. Depois da compactação, pode voltar a anexar até 5 ficheiros 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 ficheiro de gravação: objetivo, restrições, decisões, handles abertos, evidência recente e próxima ação.

Alguns outputs nunca devem ser colocados na janela de contexto.

O artigo arXiv torna isto concreto com um workflow de ciência dos materiais. Uma ferramenta gera uma estrutura de grelha eletrónica para uma molécula: uma matriz 3D de dimensões 128 × 128 × 128, totalizando 2.097.152 elementos float32. Esse output excede em muito a janela de contexto de LLMs amplamente usados. Mas a ferramenta seguinte precisa da grelha como input.

A solução proposta é armazenar valores grandes fora do contexto do modelo e devolver identificadores curtos, ou apontadores. Wrappers de ferramentas inspecionam inputs para ver se são valores em bruto ou caminhos de memória. Outputs demasiado grandes são guardados na memória de runtime sob um caminho, e ferramentas posteriores podem receber o apontador e resolvê-lo internamente. O modelo manipula referências, enquanto a camada de orquestração preserva os dados completos. Numa experiência comparativa em que ambos os métodos tiveram sucesso, a abordagem baseada em apontadores usou aproximadamente sete vezes menos tokens do que o workflow tradicional, segundo o artigo.

Esta é a separação mais limpa entre raciocínio e transporte de dados. O modelo não precisa de «ver» uma matriz com 2 milhões de elementos para a passar a outra ferramenta. Precisa de saber que a matriz existe, o que representa e que operação deve consumi-la a seguir.

A mesma lógica aplica-se para lá de arrays científicos. Grandes respostas JSON, PDFs, logs, embeddings, ficheiros multimédia e exportações de bases de dados pertencem muitas vezes ao armazenamento, não ao prompt. Para sistemas construídos em torno de ferramentas MCP ou conectores API personalizados, a passagem por apontadores deve ser uma escolha de desenho de primeira classe, não um remendo depois do primeiro transbordo.

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 ficheiros, logs, traces de erro e resumos podem consumi-la mais depressa do que se espera. O enquadramento prático não é quão grande a janela parece no papel, mas quão rapidamente os agentes a gastam em runtime. As orientações da Redis sobre memória de agentes apontam para memória externa e durável para estado que deve sobreviver entre chamadas, enquanto o enquadramento de engenharia de contexto da Atlan separa prompts melhores de melhor montagem de contexto. Juntos, tratam a janela de contexto menos como um armazém e mais como um conjunto de trabalho limitado.

A lição mais profunda é que uma janela de contexto é um recurso escasso de runtime. Tratá-la como «memória» é útil, mas só se a camada de orquestração se comportar como um sistema operativo: alocar, expulsar, paginar, compactar, deduplicar e persistir. A distinção por camadas da Atlan é útil aqui. A engenharia de prompt não consegue corrigir um leitor de ficheiros que despeja 80.000 tokens irrelevantes na chamada seguinte. A engenharia de contexto pode melhorar o conjunto de trabalho. A engenharia da camada de orquestração decide se esse conjunto de trabalho está protegido logo à partida.

Isto também muda a forma como as equipas devem avaliar agentes. Um prompt de demonstração não chega. A avaliação de longo horizonte deve incluir transcrições crescentes, leituras repetidas de ficheiros, grandes outputs de ferramentas, chamadas de ferramentas falhadas, retomas depois de compactação e tarefas em que o próximo passo correto depende de uma restrição inicial. O nosso guia de engenharia de contexto para agentes cobre a versão desse problema do lado do modelo; a camada de orquestração é onde ele se torna operacional.

Primeiro, ponha orçamentos em todas as fontes de contexto. Ficheiros, outputs de ferramentas, chunks recuperados, inserções de memória e histórico de conversa devem ter limites explícitos. Um único máximo global de tokens é demasiado grosseiro.

Segundo, torne a truncagem acionável. Se a camada de orquestração cortar conteúdo, o modelo deve saber que intervalo viu e como pedir mais. A truncagem silenciosa é pior do que a rejeição porque cria trabalho confiante sobre dados em falta.

Terceiro, compacte em torno do estado, não da prosa. Os resumos devem preservar o objetivo do utilizador, restrições, decisões, tarefas pendentes, ficheiros tocados, resultados de ferramentas que importam e o próximo passo imediato. Os pares de chamadas de ferramentas devem manter-se intactos.

Quarto, tire valores grandes do prompt. Guarde-os, dê-lhes nomes e passe apontadores através de ferramentas. Isto é especialmente importante para agentes que chamam APIs, processam documentos ou coordenam sistemas multiagente.

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

O resumo abaixo transforma esses padrões numa checklist rápida antes da FAQ.

• Agentes de longo horizonte falham tanto por excesso de contexto como por perda do objetivo, por isso a camada de orquestração tem de gerir mais do que o comprimento do prompt.
• Sistemas de agentes em produção usam orçamentos rígidos em ficheiros, outputs de ferramentas e histórico antes de os dados em bruto chegarem ao modelo.
• Paginação, pesquisa e vistas geridas tratam o contexto como uma janela de visualização limitada, não como armazenamento permanente.
• A compactação funciona melhor como checkpointing: preserva objetivos, restrições, decisões, trabalho pendente e integridade das chamadas de ferramentas.
• Grandes outputs de ferramentas pertencem muitas vezes a armazenamento externo, com apontadores curtos passados entre ferramentas em vez de valores completos no prompt.

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

O excesso de contexto acontece quando o prompt acumulado, o histórico, os dados recuperados, os ficheiros e os outputs de ferramentas de um agente excedem a janela de contexto utilizável do modelo ou degradam a qualidade antes de o limite rígido ser atingido.

A perda do objetivo acontece quando a tarefa original ainda está presente algures na transcrição, mas já não orienta a próxima ação do agente, muitas vezes depois de históricos longos ou de uma má sumarização.

Definem orçamentos por fonte, paginam leituras de ficheiros, recuperam apenas vistas relevantes, compactam o histórico em torno do estado, deduplicam leituras repetidas e armazenam grandes outputs fora do prompt.

Os apontadores permitem que o modelo refira valores grandes armazenados em memória de runtime, como matrizes, logs ou PDFs, enquanto ferramentas a jusante resolvem os dados completos sem os colocar na janela de contexto.

Não. Janelas maiores ajudam, mas prompts de sistema, definições de ferramentas, documentos recuperados, logs e histórico continuam a competir por espaço, e a informação relevante pode ficar enterrada antes de se atingir um limite rígido.