Compactação de contexto em agentes: o que preservar antes de continuar

Depois de uma sessão longa, o agente pode continuar sabendo o objetivo geral e esquecer o arquivo exato que estava alterando. Também pode recuperar uma decisão rejeitada, repetir uma investigação ou agir com uma aprovação que já não vale.

Esse é o limite da compactação de contexto. Ela reduz o histórico que será enviado ao modelo, mas o resumo não deve virar a fonte de verdade da tarefa. A aplicação precisa guardar o estado operacional em separado, compactar a conversa com uma instrução clara e verificar o resultado antes de liberar a próxima ação.

Este artigo complementa o guia de context engineering para coding agents. Lá, a pergunta é qual evidência merece entrar no contexto. Aqui, a pergunta é o que precisa sobreviver quando o histórico é reescrito. O código é ilustrativo e não foi executado contra um provedor.

Resposta curta

• Trate o histórico da conversa como material resumível, não como o registro oficial da tarefa.
• Persista intenção, etapa atual, decisões, aprovações, efeitos externos e próximo passo fora do resumo.
• Preserve referências aos arquivos e artefatos; não carregue logs enormes só por segurança.
• Valide versão, permissões e invariantes depois da compactação antes de executar outra tool call.

O que a compactação de contexto preserva e o que pode perder?

A compactação troca muitas mensagens por uma representação menor. Ela costuma manter o objetivo e uma narrativa do progresso, mas pode perder detalhes que pareciam secundários quando o resumo foi produzido. Por isso, a fronteira segura não é "resumir ou não resumir". É decidir quais fatos precisam de fidelidade exata.

Em 2026, a documentação da Anthropic descreve uma compactação que detecta um limite de tokens, cria um bloco de resumo e continua a conversa a partir dele (Anthropic, "Compaction", 2026). A configuração documentada usa input_tokens como gatilho, com valor padrão de 150.000 tokens e mínimo de 50.000. Esse limite é do recurso da Anthropic, não uma regra para todo agente.

Uma boa implementação separa três classes:

O resumo pode dizer que um arquivo foi investigado. O estado da tarefa precisa dizer qual arquivo, qual hipótese continua válida e qual teste ainda falta. Essa diferença evita que uma frase plausível do modelo substitua um fato que o runtime pode verificar.

O erro de projeto é usar uma única representação para duas necessidades diferentes. A conversa precisa ser curta para a próxima inferência. O estado precisa ser preciso para autorizar a próxima transição. Um resumo excelente para leitura ainda pode ser insuficiente para executar uma escrita.

Qual estado deve ficar fora do resumo?

Mantenha fora do histórico compactado tudo que muda a permissão para agir. Um estado mínimo deve permitir que um novo turno responda cinco perguntas: qual é a intenção, onde a tarefa está, o que já foi decidido, qual efeito externo existe e qual passo está permitido agora.

Uma forma provider-neutral de representar isso é um registro versionado:

type TaskState = {
  runId: string;
  stateVersion: number;
  objective: string;
  currentStep: string;
  nextAction: "inspect" | "edit" | "test" | "ask_human" | "stop";
  decisions: Array<{ summary: string; reason: string }>;
  approvals: Array<{
    scope: string;
    approvedBy: string;
    expiresAt?: string;
  }>;
  effects: Array<{
    actionId: string;
    status: "none" | "confirmed" | "unknown";
    externalId?: string;
  }>;
  artifactRefs: string[];
  updatedAt: string;
};

O campo nextAction é mais útil que uma frase como "continue o trabalho". O agente precisa de um verbo que o executor entenda e de uma política que possa recusar. Se o estado diz ask_human, a próxima chamada não deve editar um arquivo só porque o resumo parece confiante.

O stateVersion também é importante. Se uma compactação atrasada substituir um registro mais novo, o runtime precisa rejeitar a gravação antiga. A persistência pode ser uma linha em um banco, um documento versionado ou um arquivo controlado pelo processo. O requisito é concorrência explícita e histórico suficiente para investigar a troca.

O SDK de agentes da OpenAI descreve sessões persistentes e modos de compactação que podem usar a cadeia de respostas ou reconstruir a solicitação a partir dos itens atuais (OpenAI Agents SDK, "Sessions", 2026). Essa escolha muda a origem do histórico enviado. Ela não elimina a necessidade de uma fonte de verdade para o estado da aplicação.

Quando resumir, limpar resultados ou iniciar um contexto novo?

Use compactação quando a tarefa ainda é uma linha contínua e o agente precisa do contexto recente para tomar a próxima decisão. Use limpeza de resultados quando a saída bruta já cumpriu seu papel e pode ser recuperada por uma referência. Use um novo contexto quando a tarefa mudou, o histórico ficou contaminado ou a próxima etapa precisa de uma revisão independente.

O recurso nativo da OpenAI envia uma representação compactada e permite configurar quando a compactação ocorre (OpenAI, "From model to agent: Equipping the Responses API with a computer environment", 2026). O SDK de agentes também alerta que a compactação automática pode prolongar uma execução em streaming, porque o runtime espera a operação terminar antes de fechar o turno. Isso é um motivo para tratar a compactação como uma transição observável, não como um detalhe invisível.

Não faça uma nova compactação a cada turno sem medir o efeito. Reescrever o prefixo pode invalidar cache, consumir tempo e remover justamente a evidência que você ainda não registrou. O gatilho deve considerar espaço reservado para a próxima resposta, resultados de ferramentas e o estado que será anexado ao pedido.

Como preparar uma compactação sem perder o próximo passo?

Prepare a compactação em duas fases. Primeiro, consolide o estado operacional em armazenamento durável. Depois, produza o resumo com uma lista explícita do que ele deve carregar. Se a primeira fase falhar, não compacte e não avance o agente como se o estado estivesse seguro.

type CompactionInput = {
  history: unknown[];
  state: TaskState;
};

async function prepareCompaction(input: CompactionInput) {
  const saved = await stateStore.compareAndSet(
    input.state.runId,
    input.state.stateVersion,
    input.state,
  );

  if (!saved) {
    throw new Error("task state changed before compaction");
  }

  return {
    history: input.history,
    instruction: [
      "Summarize conversation history for the next turn.",
      "Do not invent decisions, approvals, tool effects, or test results.",
      "The durable task state is authoritative for permissions and nextAction.",
      `State version: ${input.state.stateVersion}`,
      `Next action: ${input.state.nextAction}`,
    ].join("\n"),
  };
}

Esse helper não implementa a compactação de nenhum provedor. Ele mostra a ordem do contrato: salvar a versão, montar instruções, compactar e anexar ao próximo pedido. Em uma implementação real, trate a resposta da compactação como uma operação que pode falhar, atrasar ou retornar conteúdo vazio.

Depois da compactação, compare o estado que voltou com o estado persistido. Não aceite um resumo que altere nextAction, remova uma aprovação vigente ou transforme unknown em confirmed. A compactação pode propor um resumo. A aplicação decide se ele é suficiente para continuar.

Como lidar com tool results e artefatos grandes?

Guarde a conclusão operacional e descarte o volume que não precisa viajar em cada turno. Para um teste, isso pode ser o comando, o status, a falha principal e o arquivo afetado. Para uma leitura de código, pode ser o caminho, a função relevante e uma impressão digital do conteúdo que foi analisado.

O arquivo ou objeto original deve continuar recuperável quando a próxima decisão depender dele. Uma referência sem controle de acesso não é uma memória segura. Registre quem pode buscar o artefato, qual versão foi usada e quando ele pode ser substituído.

O paper Context Compaction Theory, de Tirmazi, Markelon, Bishop e Mitzenmacher, formaliza a compactação como seleção ou geração de uma mensagem menor para responder a necessidades futuras. A implicação prática é simples: o resumo só pode preservar bem aquilo que o sistema sabe que será perguntado depois. Quando as perguntas futuras são abertas, referências externas e invariantes explícitos reduzem o risco de perda.

Não coloque segredos, prompts completos ou logs brutos no resumo apenas porque eles parecem úteis. Isso aumenta o custo e mistura material confiável com dados que podem ter vindo de uma tool. O estado deve carregar o mínimo necessário para autorizar e verificar a ação seguinte.

Como verificar a tarefa depois da compactação?

Faça a retomada falhar de forma explícita quando o estado não passar por invariantes simples. A verificação precisa ocorrer antes da próxima escrita, chamada externa ou aprovação automática. Um resumo legível não prova que as referências e permissões ainda são válidas.

Confira pelo menos:

1. O runId e o stateVersion pertencem à execução atual.
2. O objetivo não mudou silenciosamente.
3. currentStep aponta para um estado conhecido do workflow.
4. nextAction é compatível com as aprovações atuais.
5. Cada efeito externo tem status e identificador coerentes.
6. As referências aos arquivos e artefatos ainda apontam para uma versão permitida.
7. O resumo não é a única evidência de um teste, uma escrita ou uma aprovação.

function assertResumable(state: TaskState) {
  if (!state.runId || state.stateVersion < 1) {
    throw new Error("invalid task identity");
  }

  if (state.nextAction === "edit" && state.approvals.length === 0) {
    throw new Error("edit requires a current approval");
  }

  if (state.effects.some((effect) => effect.status === "unknown")) {
    throw new Error("reconcile unknown external effects first");
  }
}

Essa política é apenas ilustrativa. Uma aplicação pode permitir edições sem aprovação ou usar outra forma de autorização. O teste importante é que cada combinação permitida esteja documentada e que estados desconhecidos não sejam convertidos em sucesso por conveniência.

O melhor teste de compactação não pergunta se o resumo "parece bom". Ele restaura um caso salvo e verifica se o agente continua proibido de fazer aquilo que ainda não foi provado. A qualidade da compactação aparece nas decisões que ela impede, não só no texto que ela produz.

Quando a compactação não é a melhor escolha?

Não compacte no meio de uma mutação externa sem registrar seu resultado. Se uma cobrança, migração, publicação ou mensagem pode ter sido aceita, a prioridade é reconciliar o efeito. Um resumo não transforma uma operação ambígua em uma operação segura.

Também prefira uma fronteira de pausa quando uma pessoa precisa decidir, quando a tarefa mudou de responsável ou quando o contexto acumulou instruções conflitantes. O guia sobre pausar e retomar um agente sem reiniciar detalha o checkpoint que atravessa essa interrupção. Já a execução durável para agentes trata da escolha entre fila e workflow.

Se o agente continua reabrindo a mesma investigação, compactar mais cedo pode esconder o problema. Registre a repetição, verifique o sinal de progresso e considere iniciar uma etapa nova com uma entrada menor. Contexto menor ajuda, mas não corrige uma tarefa sem critério de conclusão.

Checklist de compactação para um agente de longa duração

Antes de ativar compactação automática, revise esta sequência:

1. Defina qual parte do histórico é conversa e qual parte é estado operacional.
2. Persista intenção, etapa, decisões, aprovações, efeitos e próximo passo.
3. Dê uma versão ao estado e rejeite gravações atrasadas.
4. Transforme tool results grandes em conclusões e referências recuperáveis.
5. Declare o que o resumo pode omitir e o que ele nunca pode inventar.
6. Registre o início, o fim, o motivo e a falha de cada compactação.
7. Valide o estado antes da próxima tool call com efeito.
8. Teste contexto cheio, resumo vazio, estado atrasado, aprovação vencida e efeito externo desconhecido.
9. Use uma nova sessão quando a tarefa, o responsável ou a fronteira de confiança mudar.
10. Mantenha o histórico completo disponível para auditoria, mesmo que o modelo receba só uma projeção compactada.

Perguntas frequentes

A compactação garante que o agente não vai esquecer nada?

Não. Ela produz uma representação menor do histórico e pode perder detalhes. A tarefa deve persistir fora do resumo os fatos que autorizam uma ação, como decisões, aprovações, efeitos externos e o próximo passo. Use invariantes e testes de retomada para detectar perda antes de continuar.

Devo guardar a conversa inteira no contexto do próximo turno?

Não necessariamente. A conversa inteira pode aumentar o custo e dificultar a recuperação do sinal importante. Mantenha o histórico em armazenamento para auditoria, envie uma projeção compactada ao modelo e recupere tool results ou artefatos por referência quando a próxima decisão exigir detalhes.

Compaction e checkpoint são a mesma coisa?

Não. Compaction reduz a representação enviada ao modelo. Checkpoint registra o estado da execução que precisa sobreviver a uma interrupção. Eles podem acontecer juntos, mas um resumo de conversa não substitui um checkpoint com versão, permissões, efeitos e próximo passo.

Qual limite de tokens devo usar?

Não existe um valor universal. O limite depende do modelo, das ferramentas, da resposta reservada, do cache e do tamanho do estado que acompanha cada pedido. Comece pelo contrato do provedor, meça o seu runtime e reserve espaço para a próxima resposta. Não copie o gatilho de outro agente sem testar.

Conclusão

Compactação de contexto resolve um problema de tamanho. Ela não resolve sozinha o problema de continuidade. O histórico pode ser resumido, enquanto a intenção, as decisões, as aprovações, os efeitos externos e o próximo passo precisam continuar verificáveis em outra fonte.

O desenho seguro tem uma ordem clara: persistir o estado, compactar a conversa, validar a versão resultante e só então deixar o agente agir. Quando essa validação falhar, pause, reconcilie ou comece uma etapa nova. Um resumo menor é útil. Um estado operacional que ninguém consegue provar não é.

Nota de produção

Samuel Fajreldines é o responsável editorial por este artigo. A pesquisa combinou documentação oficial da OpenAI, Anthropic e OpenAI Agents SDK com um paper primário sobre a teoria de compactação e discussões públicas recentes. O código é ilustrativo e não foi executado contra um provedor. A assistência de IA ajudou a organizar fontes, redigir, localizar, gerar a imagem e revisar consistência; não forneceu teste de produção ou benchmark próprio. Para organizar sessões longas de agentes, uso o RemoteCode, uma ferramenta minha, sem apresentar isso como evidência de desempenho.

Fontes consultadas

• OpenAI, "From model to agent: Equipping the Responses API with a computer environment", consultado em 2026-09-11
• Anthropic, "Compaction", consultado em 2026-09-11
• OpenAI Agents SDK, "Sessions", consultado em 2026-09-11
• Tirmazi et al., "Context Compaction Theory", consultado em 2026-09-11
• OpenCode V2 Compaction Internals, consultado em 2026-09-11