Engenharia de contexto para agentes de IA: o que realmente entra na janela de contexto

Índice

Publicado em agosto de 2026.

TL;DR: Engenharia de contexto é a disciplina de decidir quais tokens merecem um lugar na janela de contexto de um agente a cada etapa — instruções de sistema, definições de ferramentas, dados recuperados e histórico de conversa competem todos pelo mesmo espaço limitado. A engenharia de prompt pergunta como formulo isto; a engenharia de contexto pergunta o que o modelo realmente precisa saber agora. O modo de falha geralmente não é contexto de menos — é de mais: histórico obsoleto, esquemas de ferramentas irrelevantes e documentos recuperados que ninguém pediu, tudo diluindo o sinal e elevando o custo. Aplico um orçamento fixo por categoria, corto o histórico antes da identidade, e resumo antes de truncar.

Leitura do operador: Os agentes mais difíceis de depurar não falhavam porque o modelo era fraco. Falhavam porque eu tinha deixado a janela de contexto virar uma gaveta de bagunça: seis esquemas de ferramentas que a tarefa não precisava, um histórico de conversa que tinha desviado 40 turnos do pedido original, um documento recuperado que era tecnicamente relevante e praticamente inútil. Corrigir o prompt não ajudava. Corrigir o que estava na frente do prompt, sim.

A engenharia de prompt te deu um agente que funciona. A engenharia de contexto é o que o mantém funcionando quando ele lida com volume real, histórico real e casos extremos reais — e é a habilidade em que hoje passo mais tempo do que na formulação do prompt.

Engenharia de prompt e engenharia de contexto não são o mesmo trabalho

Um prompt é uma instrução. Contexto é tudo que o modelo vê ao agir sobre essa instrução: o prompt de sistema, as ferramentas que ele pode chamar, o que você recuperou ou consultou, e quanto de conversa ou histórico de execuções anteriores você decidiu levar adiante. A engenharia de prompt otimiza a redação da primeira coisa. A engenharia de contexto otimiza a composição de todas as quatro.

Essa distinção importa na prática, não só no vocabulário. Se escrevo um prompt bem calibrado e entrego ao agente cinco esquemas de ferramentas irrelevantes e quarenta turnos de histórico obsoleto, a redação deixa de importar — o modelo está raciocinando sobre um contexto que é majoritariamente ruído. Cada um dos meus agentes que passou de “funciona na demo” para “funciona às 3 da manhã com uma entrada estranha” chegou lá corrigindo o que estava na janela, não reformulando as instruções dentro dela.

As quatro coisas que competem por espaço

A cada turno, quatro categorias disputam o mesmo espaço limitado:

1. Instruções de sistema — identidade, regras, formato de saída. Veja as cinco camadas que uso para prompts de sistema — esta é a única categoria que deve permanecer quase fixa, porque o prompt caching só compensa quando o prefixo não muda.
2. Definições de ferramentas — os esquemas de cada ferramenta que o agente poderia chamar neste turno, precisando dela ou não.
3. Dados recuperados — qualquer coisa extraída de um banco de dados, um vector store ou uma chamada de API: memória, documentos, registros de clientes.
4. Histórico de conversa ou execução — o que já aconteceu nesta sessão ou execução.

Nenhuma dessas é gratuita. Cada token de qualquer categoria é um token que o modelo precisa pesar contra todos os outros ao decidir o que fazer a seguir, e cada token é um token que você paga em cada requisição que não é um acerto de cache.

O erro é quase sempre demais, não de menos

Quando um agente se comporta mal, o instinto é adicionar mais contexto — mais instruções, mais antecedentes, mais histórico “só por garantia”. Na minha experiência isso costuma ser o contrário do certo.

Esquemas de ferramentas demais. Já vi um agente chamar a ferramenta errada não porque a certa estivesse faltando, mas porque estava enterrada atrás de outras seis que não eram necessárias para aquela tarefa. Envie só as ferramentas relevantes para a etapa atual, não a caixa de ferramentas inteira em cada chamada. Uma camada de roteamento que decide qual subconjunto de ferramentas expor é barata de construir e se paga na primeira vez que evita uma chamada errada.

Histórico de conversa obsoleto. Um agente de suporte carregando 60 turnos de histórico de três problemas não relacionados de tempos atrás não está “lembrando do cliente” — está diluindo o pedido atual com ruído irrelevante, e ocasionalmente agindo sobre algo que não é mais verdade. Este é exatamente o modo de falha que a memória episódica com uma janela limitada deveria prevenir, e vale a pena verificar se sua janela está realmente limitada ou cresceu sem limite silenciosamente.

Documentos recuperados que ninguém pediu. Uma recuperação semântica que retorna os 10 fragmentos “mais similares” em vez dos 2 relevantes enterra a resposta em distração de aparência plausível. Mais contexto recuperado não é mais sinal — a partir de certo ponto é ativamente pior, porque o modelo tem que trabalhar mais para encontrar a parte que importa.

Instruções repetidas defensivamente. Vejo isso em prompts que repetem a mesma regra de quatro formas diferentes porque uma versão anterior do agente a ignorou uma vez. Isso é um sinal de que a regra precisava se mover para mais cedo no prompt ou ser imposta estruturalmente (uma restrição no esquema de uma ferramenta, uma etapa de validação) — não um sinal para encher o contexto com repetição.

O orçamento que realmente aplico

Em mais de 30 agentes em produção, defino um orçamento explícito de tokens por categoria antes de construir o agente, não depois que ele começa a se comportar mal:

A ordem dessa última coluna é o verdadeiro modelo de decisão: primeiro o histórico, depois a amplitude da recuperação, depois o escopo das ferramentas, e as instruções de sistema por último. Histórico é o mais barato de comprimir sem perder correção — um resumo de duas frases de “o que aconteceu nos turnos 1-30” geralmente carrega o mesmo valor operacional que a transcrição completa. Cortar instruções de sistema é o mais perigoso, porque é ali que vive o comportamento real do agente.

Resuma antes de truncar

Truncar — simplesmente descartar os turnos mais antigos — é a versão crua disso. Funciona até o turno descartado conter o único fato que o agente precisava. O padrão melhor é a compactação: antes de descartar histórico bruto, condensá-lo em um resumo estruturado curto que capture as decisões e os fatos, e manter esse resumo permanentemente mesmo depois que os turnos brutos tiverem sumido.

// workers/compact-history.ts

interface HistoryDigest {
  summary: string; // 2-3 frases: o que foi decidido, resolvido, ou ainda está em aberto
  keyFacts: Record<string, string>; // fatos estáveis que vale a pena manter literalmente
  turnCount: number; // quantos turnos brutos este resumo substitui
}

async function compactIfNeeded(
  history: ConversationTurn[],
  env: Env
): Promise<{ digest: HistoryDigest | null; recent: ConversationTurn[] }> {
  const RECENT_WINDOW = 10;
  if (history.length <= RECENT_WINDOW) {
    return { digest: null, recent: history };
  }

  const toCompact = history.slice(0, -RECENT_WINDOW);
  const recent = history.slice(-RECENT_WINDOW);

  // Um modelo barato resumindo quase sempre é suficiente para esta etapa
  const digest = await summarizeTurns(toCompact, env);
  return { digest, recent };
}

Este é o mesmo princípio de um eval harness transformando cada falha de produção em um caso de teste permanente (veja o eval harness que uso para lançar agentes de IA): não descarte informação, comprima-a numa forma barata de manter e ainda útil. Os turnos brutos são descartáveis. Os fatos dentro deles normalmente não são.

Recuperação: menos resultados, mais relevantes, superam mais resultados

A mesma disciplina se aplica a tudo que é extraído de um vector store ou banco de dados. É tentador recuperar generosamente — top-10, top-20 — na teoria de que mais contexto não pode fazer mal. Pode. Cada fragmento irrelevante é um fragmento que o modelo precisa ler, pesar e descartar, e uma pilha grande o bastante de quase-acertos pode pesar mais que o único fragmento que realmente responde à pergunta.

Meu padrão é começar com um k pequeno (2-4) e só ampliar se eu conseguir mostrar, com casos reais, que a resposta realmente está faltando naquela amplitude — não porque uma rede mais ampla parece mais segura. Se a qualidade da recuperação for inconsistente, o conserto geralmente é uma consulta melhor ou uma etapa de re-ranking, não um k maior.

Conecte isso a custo e correção

Engenharia de contexto não é só um problema de qualidade — é a maior alavanca isolada sobre o que custa rodar um agente, porque na maioria das cargas de trabalho de agentes você é cobrado muito mais por tokens de entrada do que de saída. Uma janela de contexto inchada é uma fatura inchada antes de ser um bug de comportamento. Se você ainda não viu a matemática de custo para escolher entre níveis de modelo, o orçamento de contexto que você aplica muda essa matemática diretamente: um contexto menor e bem delimitado torna um modelo mais barato viável para mais das suas tarefas, porque o modelo não é solicitado a procurar uma agulha num palheiro desnecessariamente grande.

Todo agente que opero roda em Claude, e a decisão de nível de modelo só faz sentido depois que o orçamento de contexto está fixado — comparar custos sobre um contexto inchado e sem delimitação não te diz nada sobre o que a tarefa realmente precisa.

E porque mudar o que está na janela de contexto muda o comportamento tanto quanto mudar o prompt, toda mudança de contexto passa pelo mesmo portão que uma mudança de prompt: rodá-la contra o conjunto de avaliações construído a partir de falhas reais de produção antes de lançar. Cortar histórico ou estreitar a amplitude de uma recuperação é exatamente o tipo de mudança “obviamente segura” que silenciosamente faz um caso extremo regredir se você não verificar.

O veredito do operador

Engenharia de contexto é decidir, a cada turno, o que merece um lugar numa janela limitada — e a falha padrão é incluir demais, não de menos. Mantenha as instruções de sistema estáveis e como última coisa a cortar. Limite as definições de ferramentas à etapa atual. Recupere de forma estreita e amplie só com evidência. Compacte o histórico em resumos antes de descartá-lo, e corte primeiro os turnos brutos mais antigos. Depois verifique cada mudança contra suas avaliações, porque mudanças de contexto alteram o comportamento exatamente como mudanças de prompt — só é mais fácil fingir que não.

Perguntas frequentes

O que é engenharia de contexto para agentes de IA?

É a disciplina de decidir quais tokens — instruções de sistema, definições de ferramentas, dados recuperados e histórico de conversa — entram na janela de contexto de um agente a cada etapa, ao contrário da engenharia de prompt, que trata de como uma única instrução é formulada. Importa mais em produção, onde as quatro categorias competem pelo mesmo espaço limitado a cada requisição.

Engenharia de contexto é diferente de engenharia de prompt?

Sim. A engenharia de prompt otimiza a redação de uma instrução. A engenharia de contexto otimiza tudo mais que o modelo vê junto dessa instrução — quais ferramentas estão expostas, o que foi recuperado, e quanto histórico é levado adiante. Um prompt bem redigido ainda falha se estiver cercado de esquemas de ferramentas irrelevantes ou histórico obsoleto.

Quanto histórico de conversa um agente de IA deveria manter?

Menos do que você pensa. Uma janela deslizante limitada (10-20 turnos recentes é típico) mais um resumo condensado de tudo mais antigo geralmente supera uma transcrição bruta completa, porque remove ruído sem perder os fatos que importam. Compacte antes de descartar histórico, não apenas trunque.

Uma janela de contexto maior significa que preciso de menos engenharia de contexto?

Não — ela remove o teto técnico rígido, mas não o problema de custo ou ruído. Uma janela maior torna a folga mais barata, mas cada token irrelevante ainda dilui o sinal que o modelo precisa processar e ainda custa dinheiro em cada requisição que não é um acerto de cache. A disciplina importa tanto a 200 mil tokens quanto a 8 mil.

Relacionado: Como escrever prompts de sistema de agentes de IA que não falham em produção · Como adicionar memória a um agente de IA · Prompt caching: reduza seus custos de Claude sem trocar de modelo · O eval harness que uso para lançar agentes de IA

Precisa de ajuda para projetar o contexto e a memória de um agente? Entre em contato — projeto sistemas de agentes em produção para equipes operadoras.