Compactação de Contexto

Intenção

Resumir ou podar o contexto à medida que ele cresce, mantendo o que importa para os próximos passos. Serve para agentes e conversas longas que, sem isso, enchem a janela e pioram a cada volta.

Problema

O agente de código de Renata resolve tarefas de duas a três horas: migrar um módulo, atualizar dependências, corrigir uma bateria de testes. No começo da tarefa ele é preciso. Depois de 150 voltas, o contexto tem centenas de resultados de ferramenta: arquivos inteiros, saídas de teste com milhares de linhas, buscas que não deram em nada.

Perto do fim, o agente começa a editar arquivos que já tinha consertado, a reaplicar mudanças que foram revertidas e a esquecer a restrição combinada no começo (“não mexa na API pública”). Em algumas tarefas, a janela estoura e a execução falha.

Isso é o smell Contexto Podre: o histórico ainda está lá, mas já não é memória útil. O paper “Lost in the Middle” (Liu et al., 2023) ajuda a explicar o sintoma. Com a janela cheia, o modelo usa mal o que ficou no meio, exatamente onde está a restrição da volta 3.

Começar uma sessão nova não resolve: o agente perde o plano, as decisões e o que já foi feito. O que Renata precisa é de um jeito de o contexto continuar útil depois de horas.

A pergunta que este padrão responde: como manter um agente lúcido numa tarefa mais longa do que a janela de contexto aguenta?

Solução

Trate o contexto como memória de trabalho, com manutenção contínua. Três operações, em ordem de custo:

• Podar: apagar resultados de ferramenta antigos que já foram usados (o conteúdo de um arquivo lido 80 voltas atrás). A chamada fica registrada; o conteúdo sai.
• Resumir: quando o contexto passa de um limite, trocar a parte antiga por um resumo que guarda objetivo, decisões, estado atual e próximos passos.
• Externalizar: fatos que precisam sobreviver a qualquer resumo (plano, restrições, lista de arquivos alterados) vão para um arquivo ou estado fora do contexto, e o agente consulta quando precisa.

O gatilho é um limite de tokens, conferido antes de cada volta. Os turnos mais recentes ficam sempre inteiros.

O guia “Building effective agents” da Anthropic (dezembro de 2024) trata compactação como manutenção de contexto, não como truque de prompt. O código decide quando cortar. O modelo só escreve o resumo.

Exemplo trabalhado

Na volta 3, Renata combinou: “não altere a API pública do módulo billing”. Na volta 80, o agente leu billing/api.py (2.400 tokens) e rodou os testes (1.800 tokens de log). Na volta 150, esses resultados ainda viajam em toda chamada, junto com dezenas de outros.

Suponha, para a conta, um system prompt de 4.000 tokens e 400 tokens acrescentados por volta. Na volta 150, a entrada já passa de 60 mil tokens. Sem poda, as 50 voltas seguintes reenviam esse volume: uns 3 milhões de tokens de entrada só para terminar a tarefa.

A poda troca o conteúdo antigo por uma linha:

tool_result read_file billing/api.py
[conteúdo removido; chame a ferramenta de novo se precisar]

O histórico ainda diz que a leitura aconteceu. Os 2.400 tokens saem. Se o agente precisar do arquivo de novo, ele lê de novo. Isso é mais barato do que carregar o arquivo em 50 voltas.

Quando a poda não basta, o resumo entra. O schema que funciona no eval da Renata é este:

{
  "goal": "Migrar billing para a API v2",
  "constraints": ["não alterar a API pública"],
  "decisions": ["manter os nomes dos endpoints", "adaptar só o cliente interno"],
  "done": ["cliente interno atualizado", "testes de unidade passando"],
  "current_state": "falha o teste de contrato em test_public_api.py:41",
  "next_steps": ["ler o teste de contrato", "ajustar o adapter, não a assinatura pública"]
}

A restrição da volta 3 só sobrevive se o schema tiver um campo para ela, e se a mesma restrição estiver num arquivo de notas que o resumo não pode apagar. Sem isso, o compactador “ajuda” a esquecer exatamente o que não podia ser esquecido.

Estrutura

flowchart TD
  L(["1. Volta do agente"]):::llm --> C{"2. Contexto passou do limite?"}
  C -->|não| L
  C -->|sim| P["3. Podar resultados antigos"]:::tool
  P --> C2{"4. Ainda acima?"}
  C2 -->|não| L
  C2 -->|sim| S(["5. Resumir a parte antiga"]):::llm
  S --> N[("6. Notas e estado externos")]:::store
  N --> L

1. O agente trabalha normalmente.
2. Antes de cada volta, o código mede o contexto.
3. A primeira medida é barata: apagar conteúdo de resultados de ferramenta antigos.
4. Se a poda bastou, o loop segue.
5. Senão, um modelo resume tudo que veio antes dos últimos turnos.
6. Fatos críticos ficam fora do contexto, num arquivo de notas ou estado, e o resumo aponta para eles.

Pseudocódigo

schema Compaction { goal: string, decisions: list[string], done: list[string],
                    current_state: string, next_steps: list[string] }

function step(state):
    if tokens(state.messages) > SOFT_LIMIT:
        # 3. podar: manter a chamada, apagar o conteúdo antigo
        for r in old_tool_results(state.messages, older_than=20):
            r.content = "[conteúdo removido; chame a ferramenta de novo se precisar]"

    if tokens(state.messages) > HARD_LIMIT:
        # 5. resumir a parte antiga, manter os últimos turnos
        old, recent = split(state.messages, keep_last=10)
        summary = llm(COMPACT_PROMPT, old + read(state.notes_file)) -> Compaction
        write(state.notes_file, summary)                    # 6. externalizar
        state.messages = [as_message(summary)] + recent
        trace.span("compaction", tokens_before, tokens(state.messages))

    return llm_with_tools(SYSTEM, TOOLS, state)              # 1

Cenários reais

• Agente de código. Tarefas longas com muita leitura de arquivo. A poda de resultados antigos resolve a maior parte; o resumo entra só nas tarefas mais longas, e o plano fica num arquivo de notas.
• Automação de back-office com execução durável. Processos que duram dias, com pausas para aprovação. Cada retomada começa do estado compactado, não do histórico de três dias.
• Tutor educacional. Sessões que viram semanas. O que a aluna domina e as regras combinadas (“só dicas, sem a resolução”) ficam como fatos; o resto vira resumo de aula.

Aplicabilidade

• Tarefas ou conversas que passam com frequência de algumas dezenas de milhares de tokens.
• Agentes que leem muito (arquivos, páginas, logs) e usam pouco do que leram depois.
• Custo ou latência por volta crescendo ao longo da execução.
• Qualidade que cai no fim das tarefas longas e é boa no começo.

Quando não usar

• Tarefas curtas. O passo de compactação custa mais do que economiza.
• O problema é leitura pesada numa subtarefa bem definida. Isole num subagente: veja Isolamento de Contexto. Às vezes os dois padrões andam juntos.
• Conteúdo que precisa ser lido inteiro para a resposta (um contrato revisado cláusula por cláusula). Resumir ali perde o que importa.
• Conversa de atendimento curta em que o problema é guardar dois ou três fatos. Guarde esses fatos em estado explícito, fora do texto bruto, em vez de resumir o chat.

Como implementar

1. Meça o tamanho do contexto por volta nos traces atuais e ache onde ele cresce.
2. Comece pela poda de resultados de ferramenta antigos. Muitas vezes ela sozinha resolve.
3. Defina o schema do resumo: objetivo, decisões, feito, estado atual, próximos passos, restrições.
4. Dê ao agente um arquivo de notas (ou ferramenta de memória) para registrar plano e decisões ao longo do caminho.
5. Escolha limites: um suave para podar e um forte para resumir.
6. Verifique se o provedor oferece compactação no servidor ou edição de contexto, e prefira usar essa opção quando ela cobrir o seu caso.
7. Monte um eval com tarefas longas que dependem de algo do começo e rode antes e depois.

Armadilhas comuns

• Resumir cedo demais. Compactar a cada poucas voltas gasta chamada e apaga detalhe que ainda seria usado. Meça primeiro; corte quando a curva de tokens doer.
• Schema sem restrições. Objetivo e próximos passos não guardam um “não faça”. O eval de retenção precisa de um caso desses.
• Cortar no meio de uma chamada de ferramenta. Separar o tool_use do tool_result deixa o próximo request inválido. O corte começa num turno do usuário.
• Jogar o histórico bruto fora. Você vai precisar dele para depurar um resumo que inventou uma decisão. Compactação muda o que o modelo vê, não o que você guarda.

Variações

• Compactação no servidor. A API resume o contexto antigo sozinha quando ele passa de um limite. Menos código; você precisa devolver os blocos de compactação que ela gera.
• Edição de contexto. A API apaga resultados de ferramenta antigos antes de o modelo ver o contexto. É a poda, sem código seu.
• Janela deslizante. Só os últimos N turnos. Simples, mas perde tudo que saiu da janela; serve quando o passado realmente não importa.
• Nota escrita pelo próprio agente. O agente mantém um arquivo de progresso que sobrevive a qualquer corte. Combina com as outras variações.

Custo, latência e falhas

Como avaliar

• Retenção: perguntas de eval sobre fatos do começo da tarefa, feitas depois da compactação.
• Taxa de conclusão e retrabalho (arquivos editados duas vezes pela mesma razão) em tarefas longas.
• Custo por tarefa e tokens por volta no fim da execução.

{ "task": "Migre o módulo billing para a nova API", "constraint_turn": 3, "constraint": "não alterar a API pública", "check": "nenhuma assinatura pública mudou" }

O caso de retenção é o eval que mais gente esquece. Sem ele, a compactação “funciona” no custo e falha no produto.

Em produção

• Span compaction com tokens antes e depois e o resumo gerado.
• Painel de tokens por volta ao longo da execução: a curva deve ter dentes, não subir sem parar.
• Alerta para execuções que compactam muitas vezes. Talvez a tarefa devesse ser dividida.
• Guarde o histórico bruto fora do contexto para depurar resumos ruins.
• Se tokens_before e tokens_after quase não mudam, o splice não substituiu as mensagens antigas.

Segurança

O resumo e o arquivo de notas costumam ir para log. Se a conversa tem dados pessoais (CPF, saldo, número de pedido com nome), a compactação cria mais uma cópia. Na LGPD, isso é tratamento. Restrinja quem lê esses logs e não mande o histórico bruto para um modelo de compactação fora da política da empresa.

Prós e contras

Relações

• Smell que cura: Contexto Podre, quando o histórico cresceu e a qualidade caiu.
• Refatoração que chega aqui: Trocar Histórico por Resumo.
• Vizinhos: Isolamento de Contexto evita que o material pesado entre no histórico. Compactação limpa o que já entrou. Se a subtarefa é bem delimitada, isole primeiro.

Código

A aba Python faz poda e resumo à mão. A aba TypeScript usa a compactação no servidor da API.

import json

import anthropic

client = anthropic.Anthropic()
SOFT, HARD, KEEP_LAST = 60_000, 120_000, 10

COMPACT_PROMPT = """Resuma o trabalho do agente até aqui em JSON com as chaves:
goal, constraints, decisions, done, current_state, next_steps.
Mantenha toda restrição combinada com o usuário. Não invente nada."""


def count(messages: list) -> int:
    return client.messages.count_tokens(model="claude-opus-5-5", messages=messages).input_tokens


def prune(messages: list, older_than: int = 20) -> None:  # 3. poda
    for msg in messages[:-older_than]:
        if msg["role"] == "user" and isinstance(msg["content"], list):
            for block in msg["content"]:
                if block.get("type") == "tool_result":
                    block["content"] = "[removido; chame a ferramenta de novo se precisar]"


def compact(messages: list, notes_path: str) -> list:
    if count(messages) > SOFT:
        prune(messages)
    if count(messages) <= HARD:
        return messages
    old, recent = messages[:-KEEP_LAST], messages[-KEEP_LAST:]
    while recent and recent[0]["role"] != "user":  # o corte começa num turno do usuário
        old.append(recent.pop(0))
    reply = client.messages.create(  # 5. resumo
        model="claude-opus-5-5", max_tokens=4000, system=COMPACT_PROMPT,
        messages=[{"role": "user", "content": json.dumps(old, default=str)[:400_000]}],
    )
    summary = reply.content[-1].text
    open(notes_path, "w", encoding="utf-8").write(summary)  # 6. externalizar
    return [{"role": "user", "content": f"Resumo do trabalho anterior:\n{summary}"}] + recent

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const messages: Anthropic.Beta.BetaMessageParam[] = [];

export async function turn(userMessage: string, tools: Anthropic.Beta.BetaTool[]) {
  messages.push({ role: "user", content: userMessage });

  const response = await client.beta.messages.create({
    betas: ["compact-2026-01-12"],
    model: "claude-opus-5-5",
    max_tokens: 16000,
    tools,
    messages,
    // 2 a 5. a API resume o contexto antigo quando ele passa do limite
    context_management: { edits: [{ type: "compact_20260112" }] },
  });

  // devolva o conteúdo inteiro: os blocos de compactação precisam voltar na próxima chamada
  messages.push({ role: "assistant", content: response.content });
  return response;
}

Teste seu entendimento