Context Engineering: porque o seu agent fica mais burro no turno 40

A Anthropic traçou a linha em setembro de 2025 e as duas frases pertencem lado a lado. Prompt engineering é «métodos para escrever e organizar instruções de LLM para resultados ideais». Context engineering é «o conjunto de estratégias para curar e manter o conjunto ideal de tokens (informação) durante a inferência de LLM, incluindo toda a outra informação que possa lá aterrar fora dos prompts».¹

A diferença operacional é quando, e por quem. Um prompt é escrito uma vez, por uma pessoa, e revisto. Um contexto é montado em cada chamada, por código que ninguém está a olhar, a partir de material que ninguém escreveu à mão: quarenta turnos de histórico, seis resultados de ferramentas, quatro passagens recuperadas, um perfil de utilizador, doze esquemas JSON. O Capítulo 15 mediu o que instruções melhores compram. Este capítulo é sobre os outros noventa por cento dos tokens, que chegam sozinhos.

O mesmo documento nomeia o recurso que todos eles gastam: os modelos «têm um “attention budget” ao qual recorrem ao analisar grandes volumes de contexto. Cada novo token introduzido esgota este orçamento em alguma medida». E nomeia o sintoma: «à medida que o número de tokens na context window aumenta, a capacidade do modelo de recordar informação desse contexto com precisão diminui» — context rot.¹

Essa última frase é uma afirmação sobre comportamento, o que significa que pode ser verificada, e a tabela no topo desta página é a verificação.

Quarenta linhas contra o endpoint local do Capítulo 22 — um pequeno servidor Python com Qwen2.5-0.5B-Instruct no CPU e a falar no formato chat-completions, para o ciclo ficar em TypeScript e os tensores ficarem do outro lado da porta.

const DEPTHS = [0, 0.125, 0.25, 0.375, 0.5, 0.625, 0.75, 0.875, 1];

for (const d of DEPTHS) {
  const slot = Math.round(d * (N - 1));
  let hits = 0, other = 0;
  for (let t = 0; t < TRIALS; t++) {
    const recs = buildRecords(N, 1000 + t);          // 25 unique tickets
    const gold = recs[Math.floor(rng(7 + t)() * N)]; // a different one each trial
    const rest = recs.filter((x) => x.ticket !== gold.ticket).slice(0, N - 1);
    const lines = [...rest.slice(0, slot).map((x) => x.line),   
                   gold.line,                                   
                   ...rest.slice(slot).map((x) => x.line)];     
    const r = await complete(prompt(lines, ask(gold.owner)), { maxTokens: 12 });
    const said = /\d{4}/.exec(r.text)?.[0];
    if (said === String(gold.ext)) hits++;
    else if (said && recs.some((x) => String(x.ext) === said)) other++;
  }
}

O contador other é o que transforma um resultado dececionante num resultado útil: quando o modelo erra, está perdido ou está confiante?

A resposta é: confiante. Nas oito posições que não são a primeira, 136 das 205 respostas erradas eram a extensão de outro ticket — um número real de quatro dígitos, formatado corretamente, lido da linha errada. Na posição 1, apenas uma das cinco falhas foi assim; na posição 7, vinte e uma de vinte e seis foram.

Essa distinção é o que importa em produção. Um modelo que diz não consigo encontrar é um bug que se nota; um modelo que devolve o número de uma linha vizinha é um bug que se envia, porque no ecrã os dois parecem idênticos. É a falha contra a qual o Capítulo 19 construiu citações verificáveis, chegada de dentro do prompt em vez de vir do índice.

A posição é um eixo. O comprimento é o outro, e mais fácil de testar: mantenha a resposta no meio e aumente a lista.

Um registo e 97 tokens: 90 %. Três registos e 159 tokens: 55 %. Oito registos e 315 tokens: 15 %, e a partir daí baixo e plano até 140 registos e 4.477 tokens. Toda a derrocada acontece entre a primeira e a oitava linha de uma lista.

A última coluna é tudo o que não é nem a extensão certa nem a de outro registo, o que, com um único registo na página, é o único sítio onde uma resposta errada pode cair. As duas falhas com um registo merecem ser reportadas em vez de arredondadas para fora, porque nenhuma foi uma recusa: uma respondeu 5806 a um registo cuja única linha diz 5805. Com 97 tokens e um único candidato, este modelo ainda copia mal um dígito duas vezes em vinte, e esse é o piso contra o qual tudo o resto é medido.

Daqui decorrem duas coisas. Uma context maior compra o direito de enviar mais, não a certeza de ser lido: este modelo tem uma janela de 32.768 tokens e um intervalo funcional, nesta tarefa, de algumas centenas de tokens. E não há limiar, precipício, nem estado de «contexto cheio» — a degradação já está em curso no terceiro registo e completa no oitavo, a um por cento da janela. Seja o que for um limite de contexto, não é isso que governa isto.

Costumam ser propostos dois mecanismos. O primeiro é a aritmética do Capítulo 9, que a Anthropic formula nos mesmos termos deste curso: os modelos «baseiam-se na arquitetura transformer, que permite a cada token fazer attention a todos os outros tokens em todo o contexto. Isto resulta em n² relações par a par para n tokens».¹ Attention sobre uma sequência mais longa não é a mesma operação aplicada a mais material; é um orçamento fixo de massa de probabilidade espalhado por mais concorrentes. O segundo é o treino: os modelos veem muito mais sequências curtas do que longas, por isso os padrões posicionais de longo alcance são a parte menos praticada da rede. Isso é um argumento, não uma medição, e este capítulo não o pode resolver.

O que está resolvido é a forma, e está-o desde 2023. Liu et al. testaram resposta a perguntas multi-documento e recuperação key-value em famílias e tamanhos de modelos e descobriram que «o desempenho é muitas vezes mais alto quando a informação relevante ocorre no início ou no fim do contexto de entrada, e degrada-se significativamente quando os modelos têm de aceder a informação relevante no meio de contextos longos, mesmo em modelos explicitamente de contexto longo».² O Capítulo 15 retirou desse artigo a sua regra de posição; o Capítulo 19 retirou dele a razão pela qual vinte chunks recuperados podem pontuar pior do que quatro. A forma prática do facto é a única frase aqui sobre a qual deve agir: isto demora cinco minutos a medir no seu próprio modelo com os seus próprios dados, e nenhuma curva publicada substitui a sua.

Pergunte a uma equipa o que preenche o contexto do seu agent e recebe uma estimativa, porque nenhuma API devolve a resposta: a resposta dá-lhe prompt_tokens, um número para tudo.

Pode recuperar a decomposição com quatro contagens e três subtrações — o prompt renderizado inteiro, o mesmo sem definições de ferramentas, só a mensagem de sistema com e sem elas, e tudo com os resultados de ferramentas removidos:

async function buckets(messages: Msg[]) {
  const sys = messages.slice(0, 1);
  const withoutResults = messages.filter((m) => m.role !== "tool");
  const [total, sysWithTools, sysNoTools, noResults] = await Promise.all([
    countPrompt(messages, CATALOGUE),        // everything
    countPrompt(sys, CATALOGUE),             // system + scaffolding + schemas
    countPrompt(sys),                        // system + scaffolding
    countPrompt(withoutResults, CATALOGUE),  // everything but tool output
  ]);
  return {
    system: sysNoTools,
    tools: sysWithTools - sysNoTools,                                  
    toolResults: total - noResults,                                    
    conversation: total - sysWithTools - (total - noResults),          
    total,
  };
}

countPrompt aplica o template de chat do próprio modelo antes de tokenizar, o que importa mais do que parece: o seu texto não é o que é contado. Marcadores de função, o preâmbulo de tool-calling e a renderização do esquema são todos tokens que paga e que nunca escreveu. O Capítulo 7 construiu um tokenizer e o Capítulo 16 contou com js-tiktoken; aqui a contagem vem do mesmo modelo que vai ler o prompt, que é a única contagem exatamente certa.

Agora corra um agent real através disto: quarenta turnos de uma investigação de incidente, doze ferramentas, um ambiente operacional falso a devolver dumps de logs e séries de métricas realistas.

Leia a primeira linha contra a última.

No turno 1, o prompt tem 2.547 tokens e 71 % dele são definições de ferramentas. O system prompt é 3 %. O que o utilizador escreveu é 6 %. O agent ainda não fez nada e já carrega 1.817 tokens de esquema JSON.

No turno 40, o prompt tem 10.632 tokens e as proporções inverteram-se: definições 17 %, conversa 29 %, resultados de ferramentas 53 %. A saída de ferramentas ultrapassou as definições no turno 5; a conversa só as ultrapassou no turno 25, por isso, durante os primeiros sessenta por cento da sessão, o catálogo de ferramentas era maior do que tudo o que tinha sido dito.

Depois, o total. Em 57 chamadas ao modelo, a execução faturou 370.291 tokens de input para um contexto final de 10.632 — o último prompt foi pago cerca de trinta e cinco vezes, que é o quadrático do Capítulo 16 com o multiplicador de um agent por cima. Desses 370.291, 103.569, ou 28 % de tudo o que foi faturado, eram as doze definições de ferramentas, reenviadas byte a byte idênticas em cada chamada.

O catálogo de ferramentas é o maior custo fixo de um agent e é invisível, porque nunca o vê: passa um array de objetos e o provider renderiza-o no prompt por si. Medido, nas mesmas doze ferramentas:

system prompt + chat scaffolding, no tools:        85 tokens
all twelve definitions:                          1,817 tokens
  of which fixed tool-calling scaffolding:         126 tokens
three tools instead of twelve:                     605 tokens
same twelve, one-sentence descriptions,
  no parameter prose:                            1,291 tokens  (-29 %)

Por ferramenta, o custo marginal vai de 80 tokens para get_current_time, que aceita uma string, a 263 para search_tickets, que aceita quatro parâmetros com um enum e uma frase de orientação cada. Essa é a taxa de câmbio por trás do conselho central do Capítulo 18 de que a descrição é a API: uma boa descrição custa cerca de cem tokens em cada pedido durante o resto da vida do agent. Três consequências.

Uma ferramenta que não usa continua a faturar. O agent chamou sete das doze. As outras cinco custaram 697 tokens em cada um dos 57 pedidos — 39.729 no total, mais de um décimo de tudo o que a execução faturou, por capacidades em que nunca tocou. Uma das cinco carrega o detalhe mais afiado do trace: o modelo tentou três vezes chamar read_log, que não existe. A ferramenta que queria era search_logs, a segunda definição mais cara do catálogo, com 237 tokens. Pagou por essa definição 57 vezes, nunca a usou e nunca encontrou o nome dela.

Cortar prosa é a otimização mais barata disponível, e é uma troca. Reduzir descrições a uma frase e remover documentação de parâmetros poupou 526 tokens por chamada, 29 por cento, sem tocar numa linha de lógica — e fez o modelo chamar pior as ferramentas, que foi o que o Capítulo 18 mediu. O ponto é que os dois lados dessa troca estão agora na mesma unidade.

A certa escala, enviar definições deixa de fazer sentido. A Anthropic pôs-lhe um número em novembro de 2025: um grande conjunto de servidores ligados significa processar «centenas de milhares de tokens» de definições antes de o pedido ser lido, e substituir isso por execução de código — o agent descobre e carrega apenas as definições de que precisa — «reduz o uso de tokens de 150.000 tokens para 2.000 tokens, uma poupança de tempo e custo de 98,7%».³ A mesma ideia do resto deste capítulo, aplicada a esquemas em vez de histórico: mantenha o índice, resolva a entrada a pedido.

Foram plantadas duas coisas nessa transcrição de quarenta turnos. No turno 2, antes de qualquer trabalho real, o utilizador declara uma regra permanente: qualquer ticket que abras deve ser registado sob o meu número de funcionário, 4417. No turno 19, no meio do incidente, um facto: o shard afetado é pay-shard-7, confirmado pela equipa de pagamentos. No turno 40, o utilizador pede ao agent para abrir o ticket de incidente, o que precisa de ambos. Cada sonda é feita em seis formulações diferentes e pontuada em seis — a descodificação greedy é determinística, por isso uma chamada dá um sim ou não irrepetível e seis dão uma taxa.

A transcrição é então reproduzida sob sete políticas de contexto. Reproduzida em vez de reexecutada, deliberadamente: as mensagens, as chamadas de ferramentas e os resultados de ferramentas são byte a byte idênticos nas sete, por isso a única variável é o que cada política decidiu manter. O Capítulo 16 mostrou por que motivo uma janela deslizante é uma má jogada económica, porque destrói o prefixo cacheável. Aqui está o que faz ao comportamento:

As linhas de compactação incluem o que compactar custou: 18.581 tokens de input para sete resumos e mais 3.392 para o tomador de notas. A linha de controlo está ali para que um zero possa ser lido como zero — com as duas mensagens sozinhas num prompt de 1.981 tokens, este modelo responde perfeitamente às duas sondas, por isso nenhuma linha é a tarefa ser demasiado difícil.

O histórico completo lembra-se, e é a coisa mais cara na tabela: 370.291 tokens de input para uma sessão cujo conteúdo durável são duas frases.

Isso responde a uma pergunta que a abertura deixou em aberto. Porque é que uma transcrição de 10.632 tokens guarda um facto que um registo de 853 tokens perde? Porque o comprimento é a variável errada. O registo contém vinte e cinco extensões de quatro dígitos em vinte e cinco frases idênticas — vinte e quatro iscos quase perfeitos para a que quer. A transcrição contém exatamente um número de funcionário e um nome de shard. Context rot é interferência antes de ser volume, e é por isso que 136 das 205 respostas erradas lá em cima eram o valor de um vizinho. A pergunta útil sobre uma janela não é quão longa é; é quantas coisas nela se parecem com a resposta.

A janela deslizante é 57 % mais barata e perdeu o incidente. O número de funcionário sobrevive apenas porque o agent o tinha repetido nos turnos recentes. O shard, declarado uma vez no turno 19, não está nas últimas doze mensagens — e o modelo não o diz. Perguntado seis vezes, respondeu «the affected payment shard is shard 4417», esticando-se para o número de funcionário, o único outro identificador que restava na sua janela, e duas vezes «pool», retirado da string pool_exhausted numa linha de log.

A compactação é barata e perdeu o mesmo facto. Sete resumos, escritos pelo modelo sob uma instrução explícita para manter identificadores, números, instruções permanentes e perguntas em aberto, e pay-shard-7 não aparece em nenhum dos que importavam; as seis suposições foram shard 1, pay_shard_1 e pool. A compactação não falha em voz alta. Produz uma sessão fluente, plausível e muito mais curta que deixou cair silenciosamente uma linha.

Três linhas pontuaram 0/6 no facto do turno 19 — a janela deslizante, a compactação e a compactação com notas. Dezoito respostas erradas entre elas, e nem uma delas foi «não sei».

Depois vem a linha que devia envergonhar. Manter as quarenta mensagens do próprio utilizador verbatim, mais os últimos quatro turnos na íntegra e nada mais, custa 168.550 tokens — 54 % menos do que o histórico completo — e responde às duas sondas tão bem como, ou melhor do que, o histórico completo. Sem sumarizador, sem tomador de notas, sem segundo modelo: um filtro em role === "user". As palavras do utilizador são os tokens de alto valor mais baratos na janela de um agent, e a maioria dos designs descarta-as juntamente com tudo o resto.

As duas últimas linhas são novamente a tabela de abertura, dentro do agent. O mesmo bloco fixado, movido da mensagem de sistema para o fim do prompt: 5/6 torna-se 6/6. Em seis ensaios, isto não é uma diferença significativa e não é apresentado como tal — é apresentado como lembrete de que onde é um parâmetro que está a definir, saiba-o ou não.

As quatro estratégias abaixo são da Anthropic, pela sua ordem, embora só as últimas três pertençam à sua lista de longo horizonte.¹ Todas as quatro são variações de uma instrução: não carregue o que pode ir buscar, e não carregue em bruto o que pode carregar comprimido.

const elide: Policy = (h) => [SYSTEM, ...h.flatMap((turn, ti) =>
  turn.map((m) => (ti < h.length - 4 && m.role === "tool"
    ? { role: "tool", name: m.name,
        content: `[${m.name} result from turn ${ti + 1}, ${m.content.length} chars, ` +
                 `elided; call ${m.name} again with the same arguments to re-read it]` }
    : m)))];

const r = await complete([
  { role: "system", content:
      "You keep a durable note file for a support session. Given one user message, " +
      "output one short note ONLY if it states a standing rule, an identifier or a fact " +
      "that must survive the rest of the session. Otherwise output exactly NONE." },
  { role: "user", content: `Turn ${i + 1}: ${user}` },
], { maxTokens: 40 });
if (!/^none\b/i.test(r.text.trim())) notes.push(`turn ${i + 1}: ${r.text.trim()}`);

O sub-agent não está na tabela acima porque não corre durante quarenta turnos: corre uma vez, numa janela que alguém delimitou para ele. Dado o system prompt, os turnos 17 a 19 e nada mais — 2.737 tokens — respondeu à sonda do shard 6/6, melhor do que qualquer política na tabela, e à sonda do funcionário 0/6, porque esse número não está nos três turnos que lhe foram entregues.

Isso são sub-agents em dois números: uma janela limpa não é inteligência, é âmbito, e o âmbito é definido antecipadamente por código que já tem de saber que turnos importam. Vale a pena guardar mais uma coisa nessas respostas. Esta foi a única política que respondeu «None available» em vez de inventar algo. Um modelo com um contexto pequeno e coerente sabe o que lhe falta; um modelo com um contexto grande e ruidoso não sabe.

Quase todas as conversas confusas sobre memória de agent são três mecanismos a vestir uma só palavra. Têm tempos de vida, donos e modos de falha diferentes, e um sistema que os mantém no mesmo sítio tem um problema de que ainda não se apercebeu.

O enquadramento académico é o da CoALA, que organiza language agents em torno de «componentes de memória modulares» e separa memória de trabalho de stores episódicos, semânticos e procedimentais.⁴ MemGPT leva a mesma ideia literalmente, tomando emprestada a memória virtual dos sistemas operativos: uma camada rápida dentro da janela, uma camada lenta fora dela, e o próprio modelo a mover dados entre ambas com function calls.⁵ Ambos forçam a pergunta a que um produto tem de responder de qualquer forma — não quanto posso guardar, mas a que store pertence isto, e quando expira.

O teste prático é uma pergunta por facto: o que deve continuar a ser verdade amanhã? Um resultado de ferramenta do turno 12, nada. Um resumo da sessão, até a sessão terminar. Que o número de funcionário do utilizador é 4417, até ele mudar de emprego. Três respostas, três stores.

Agora pode medir o que está numa janela, decidir o que fica nela e distinguir entre um agent que se esqueceu de algo e um que o carregava mas não olhou.

A última das quatro estratégias é a que não cabe aqui. Um sub-agent não é uma política de contexto, é um segundo agent, e no momento em que há dois tem de decidir o que passa entre eles e quem manda. O Capítulo 25 é isso: os cinco padrões de orquestração e de onde vem realmente cada um dos seus nomes, as duas topologias que se confundem — pedir a um sub-agent e receber uma resposta de volta, contra entregar-lhe a conversa e não a receber de volta — e a descoberta medida de que, na tarefa a que põe preço, o arranjo mais simples ganha — seguida pelo teste para saber quando deixa de ganhar.

Também herda exatamente o que este capítulo acabou de medir. Um sub-agent devolve um resumo. Um resumo é uma compactação que não escreveu, produzida por um modelo cuja janela não consegue ver, e o pai não tem forma de distinguir um bom resumo de um errado confiante — a mesma distinção que separou 84 % de 19 % no topo desta página, e que transformou dezoito factos em falta em dezoito invenções. Portanto: quando o sub-agent está errado, o que é que o pai pode exatamente ver?

Todos os números aqui foram produzidos nesta máquina e nenhum foi estimado. O modelo é Qwen2.5-0.5B-Instruct em float32 no CPU com descodificação greedy, servido por loopback por um pequeno endpoint Python que fala no formato chat-completions e expõe uma rota de contagem de tokens — novamente a costura do Capítulo 14, tensores do lado Python e o ciclo do lado TypeScript — por isso cada contagem é o tokenizer do próprio modelo aplicado ao seu próprio template de chat. A tabela de posição são 288 chamadas, nove posições por trinta e dois ensaios com um ticket diferente em cada ensaio; a tabela de comprimento são 140 chamadas; a execução do agent são 57 chamadas ao modelo ao longo de 43 minutos de relógio; a tabela de políticas é essa transcrição reproduzida sob sete políticas. Os intervalos são de Wilson, do Capítulo 4. Nenhuma API paga foi chamada, e é também por isso que não há um único preço no capítulo: as contagens de tokens são exatas e as taxas pelas quais as multiplicaria são as do Capítulo 16.