Compactação em um limite de tokens

A “threshold compaction” (compactação por limite) é o tipo automático de “compaction” (compactação): você define um limite de tokens nas suas requisições comuns, e a API resume o contexto mais antigo no meio de uma requisição assim que o limite é atingido. Ela é suportada junto com a compactação sob demanda, na qual você decide quando o resumo é escrito (consulte Compactação sob demanda). Para escolher entre elas, consulte Escolha como compactar.

A compactação estende o comprimento efetivo do contexto para conversas e tarefas de longa duração, resumindo automaticamente o contexto mais antigo ao se aproximar do limite da “context window” (janela de contexto). Ela também mantém o contexto ativo pequeno: à medida que uma conversa cresce, a qualidade das respostas se degrada, então a compactação substitui o conteúdo mais antigo por um resumo conciso.

Isso é ideal para:

• Conversas baseadas em chat, com múltiplos turnos, nas quais você deseja que os usuários usem um único chat por um longo período de tempo
• Prompts orientados a tarefas que exigem muito trabalho de acompanhamento (frequentemente “tool use” (uso de ferramentas)) que pode exceder a janela de contexto

Como a compactação funciona

Quando a compactação está habilitada, Claude resume automaticamente sua conversa quando ela atinge o limite de tokens configurado. A API:

1. Detecta quando os tokens de entrada atingem o limite de acionamento especificado por você.
2. Gera um resumo da conversa atual.
3. Cria um bloco compaction contendo o resumo.
4. Continua a resposta com o contexto compactado.

Nas requisições subsequentes, anexe a resposta às suas mensagens. A API descarta automaticamente todos os blocos de conteúdo anteriores ao bloco compaction, continuando a conversa a partir do resumo.

Uso básico

Habilite a compactação adicionando a estratégia compact_20260112 a context_management.edits na sua requisição à Messages API.

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# Anexe a resposta (incluindo qualquer bloco de compactação) para continuar a conversa
messages.append({"role": "assistant", "content": response.content})

Parâmetros

Configuração do acionador

Configure quando a compactação é acionada usando o parâmetro trigger:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Instruções de sumarização personalizadas

O prompt de sumarização padrão varia de acordo com o modelo. Cada padrão instrui Claude a escrever um resumo dentro de tags <summary></summary> com as informações necessárias para continuar a tarefa em uma janela de contexto futura. Por exemplo, alguns modelos usam o seguinte prompt:

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

Você pode fornecer instruções personalizadas por meio do parâmetro instructions. As instruções personalizadas não complementam o prompt padrão. Elas o substituem completamente:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

No Claude 5.1 e em modelos posteriores, uma requisição com instructions personalizadas resume apenas a partir da conversa visível: os blocos de pensamento anteriores não fazem parte da entrada do sumarizador.

Pausando após a compactação

Use pause_after_compaction para pausar a API após gerar o resumo da compactação. Isso permite que você adicione blocos de conteúdo adicionais (como preservar mensagens recentes ou mensagens específicas orientadas a instruções) antes que a API continue com a resposta.

Quando habilitado, a API retorna uma mensagem com o motivo de parada compaction após gerar o bloco de compactação:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Verifica se a compactação acionou uma pausa
if response.stop_reason == "compaction":
    # A resposta contém apenas o bloco de compactação
    messages.append({"role": "assistant", "content": response.content})

    # Continua a requisição
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

A API pausa mesmo que nenhum resumo seja gerado. O content do bloco compaction é então null, portanto mantenha as mensagens originais ao continuar. Se as salvaguardas bloquearem o resumo, content também é null e o motivo de parada é refusal em vez de compaction. stop_details fornece a categoria de política, se houver uma. Continue da mesma forma em ambos os casos: procure o bloco compaction em vez de testar stop_reason, como faz o exemplo que preserva mensagens recentes.

Aplicando um orçamento total de tokens

Quando um modelo trabalha em tarefas longas com muitas iterações de uso de ferramentas, o consumo total de tokens pode crescer significativamente. Você pode combinar pause_after_compaction com um contador de compactações para estimar o uso cumulativo e concluir a tarefa de forma elegante quando um orçamento for atingido.

Este exemplo aparece apenas nas linguagens de SDK: seu valor está na lógica de acompanhamento do orçamento em torno da requisição. A requisição bruta combina o trigger de Configuração do acionador com o pause_after_compaction de Pausando após a compactação.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                "pause_after_compaction": True,
            }
        ]
    },
)

if response.stop_reason == "compaction":
    n_compactions += 1
    messages.append({"role": "assistant", "content": response.content})

    # Estima o total de tokens consumidos; solicita a finalização se exceder o orçamento
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Trabalhando com blocos de compactação

Quando a compactação é acionada, a API retorna um bloco compaction no início da resposta do assistente.

Uma conversa de longa duração pode resultar em múltiplas compactações. O último bloco de compactação reflete o estado final do prompt, substituindo o conteúdo anterior a ele pelo resumo gerado.

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

Enviando os blocos de compactação de volta

Você deve enviar o bloco compaction de volta à API nas requisições subsequentes para continuar a conversa com o prompt encurtado. A abordagem mais simples é anexar todo o conteúdo da resposta às suas mensagens:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# Após receber uma resposta com um bloco de compactação
messages.append({"role": "assistant", "content": response.content})

# Continue a conversa
messages.append({"role": "user", "content": "Now add error handling"})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Em Python, use client.beta.messages, como fazem os exemplos desta página. Se você chamar client.messages e serializar os blocos por conta própria, um model_dump() simples adiciona text: null e citations: null ao bloco compaction. A API então rejeita a requisição com um erro 400 (Extra inputs are not permitted). Em vez disso, use to_dict() ou model_dump(exclude_none=True). Continuar a partir do resumo dá o mesmo conselho para a compactação sob demanda.

Quando a API recebe um bloco compaction, todos os blocos de conteúdo anteriores a ele são ignorados. Você pode:

• Manter as mensagens originais na sua lista e deixar a API cuidar da remoção do conteúdo compactado
• Descartar manualmente as mensagens compactadas e incluir apenas o bloco de compactação em diante

Se nenhum resumo for gerado, o content do bloco é null e a API ignora o bloco. Nada é compactado, então mantenha as mensagens originais.

Nos modelos Claude 5.1 e posteriores, os blocos de pensamento anteriores a um bloco compaction não são levados adiante, então o resumo é tudo o que o modelo tem desse trabalho anterior. Se você escrever suas próprias instructions, diga ao modelo o que o resumo deve reter; consulte Diga ao modelo o que preservar nos resumos de compactação.

Streaming

O bloco de compactação é transmitido via streaming de forma diferente dos blocos de texto. Você recebe um evento content_block_start, seguido por um único content_block_delta com o conteúdo completo do resumo (sem streaming intermediário) e, em seguida, um evento content_block_stop.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        match event.type:
            case "content_block_start":
                block = event.content_block
                match block.type:
                    case "compaction":
                        print("Compaction started...")
                    case "text":
                        print("Text response started...")

            case "content_block_delta":
                delta = event.delta
                match delta.type:
                    case "compaction_delta":
                        print(f"Compaction complete: {len(delta.content or '')} chars")
                    case "text_delta":
                        print(delta.text, end="", flush=True)

    # Obtém a mensagem final acumulada
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Cache de prompt

A compactação funciona bem com o “prompt caching” (cache de prompt). Você pode adicionar um ponto de interrupção cache_control nos blocos de compactação para armazenar em cache o conteúdo resumido.

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

Maximizando acertos de cache com prompts do sistema

Quando a compactação ocorre, o resumo se torna um novo conteúdo que precisa ser gravado no cache. Sem pontos de interrupção de cache adicionais, isso também invalidaria qualquer “system prompt” (prompt do sistema) em cache, exigindo que ele fosse armazenado em cache novamente junto com o resumo da compactação.

Para maximizar as taxas de acerto de cache, adicione um ponto de interrupção cache_control no final do seu prompt do sistema. Isso mantém o prompt do sistema em cache separadamente da conversa, de modo que, quando a compactação ocorre:

• O cache do prompt do sistema permanece válido e é lido do cache
• Apenas o resumo da compactação precisa ser gravado como uma nova entrada de cache

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "You are a helpful coding assistant...",
            "cache_control": {
                "type": "ephemeral"
            },  # Cache the system prompt separately
        }
    ],
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Isso mantém prompts do sistema longos em cache ao longo de múltiplos eventos de compactação durante uma conversa.

Entendendo o uso

A compactação requer uma etapa de amostragem adicional, que contribui para os “rate limits” (limites de taxa) e para o faturamento. A API retorna informações detalhadas de uso na resposta:

{
  "usage": {
    "input_tokens": 23000,
    "output_tokens": 1000,
    "iterations": [
      {
        "type": "compaction",
        "input_tokens": 180000,
        "output_tokens": 3500
      },
      {
        "type": "message",
        "input_tokens": 23000,
        "output_tokens": 1000
      }
    ]
  }
}

O array iterations mostra o uso de cada iteração de amostragem. Quando a compactação ocorre, você verá uma iteração compaction seguida pela iteração principal message. Os campos de nível superior input_tokens e output_tokens correspondem exatamente à iteração message neste exemplo porque há apenas uma iteração que não é de compactação. As contagens de tokens da iteração final refletem o tamanho efetivo do contexto após a compactação.

Combinando com outros recursos

Ferramentas de servidor

Ao usar ferramentas de servidor (como a busca na web), o acionador de compactação é verificado no início de cada iteração de amostragem. A compactação pode ocorrer várias vezes em uma única requisição, dependendo do seu limite de acionamento e da quantidade de saída gerada.

Contagem de tokens

O endpoint de contagem de tokens (/v1/messages/count_tokens) aplica os blocos compaction existentes no seu prompt, mas não aciona novas compactações. Use-o para verificar sua contagem efetiva de tokens após compactações anteriores:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")

Exemplos

Aqui está um exemplo completo de uma conversa de longa duração com compactação:

client = anthropic.Anthropic()

messages: list[dict] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Anexa a resposta (os blocos de compactação são incluídos automaticamente)
    messages.append({"role": "assistant", "content": response.content})

    # Retorna o conteúdo de texto
    return next((block.text for block in response.content if block.type == "text"), "")


# Executa uma conversa longa
print(chat("Briefly, help me build a Python web scraper"))
print(chat("Briefly, add support for JavaScript-rendered pages"))
print(chat("Briefly, add rate limiting and error handling"))
# Continue chamando chat() pelo tempo que a conversa precisar

Nos modelos Claude 5.1 e posteriores, os blocos de pensamento em qualquer turno do assistente que você reinserir após o bloco de compactação falham na verificação de prefixo, porque foram produzidos quando o histórico completo estava presente. Remova os blocos thinking e redacted_thinking desses turnos. Como alternativa, envie thinking.block_binding.prefix_mismatch_behavior: "drop_block" com o cabeçalho beta thinking-binding-controls-2026-08-01. Os blocos de texto e de ferramentas preservados podem permanecer como estão. Deixar a API resumir tudo, sem reinserir turnos anteriores, evita isso. No Claude Sonnet 5.5 e Claude Haiku 5.5, block_binding funciona apenas com thinking: {"type": "adaptive"}. Com qualquer outra configuração de pensamento nesses modelos, remova os blocos.

Aqui está um exemplo que usa pause_after_compaction para preservar a troca anterior e a mensagem atual do usuário (três mensagens no total) em vez de resumi-las. Ele mantém seus blocos de texto e de ferramentas inalterados, remove os blocos thinking e redacted_thinking do turno do assistente preservado e descarta esse turno se nada mais restar:

from typing import Any

client = anthropic.Anthropic()

messages: list[dict[str, Any]] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Procure o bloco de compactação, não o motivo de parada:
    # stop_reason é "refusal", não "compaction", se o resumo foi bloqueado
    compaction_block = next(
        (block for block in response.content if block.type == "compaction"), None
    )

    # Substitui o histórico apenas se um resumo foi gerado
    if compaction_block is not None and compaction_block.content is not None:
        # Preserva a troca anterior + a mensagem atual do usuário (3 mensagens)
        # incluindo-as após o bloco de compactação, sem os blocos de
        # pensamento; um turno do assistente que fica sem conteúdo é descartado
        preserved_messages = [
            {
                **message,
                "content": [
                    block
                    for block in message["content"]
                    if block.type not in ("thinking", "redacted_thinking")
                ],
            }
            if message["role"] == "assistant"
            else message
            for message in messages[-3:]
        ]
        preserved_messages = [m for m in preserved_messages if m["content"]]

        # Monta a nova lista de mensagens: compactação + mensagens preservadas
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Atualiza a lista de mensagens para refletir a compactação
        messages.clear()
        messages.extend(messages_after_compaction)

    if compaction_block is not None:
        # Continua a requisição, com o histórico completo se não houver resumo
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-5-5",
            max_tokens=4096,
            messages=messages,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

    # Adiciona a resposta final
    messages.append({"role": "assistant", "content": response.content})

    # Retorna o conteúdo de texto
    return next((block.text for block in response.content if block.type == "text"), "")


# Executa uma conversa longa
print(chat("Briefly, help me build a Python web scraper"))
print(chat("Briefly, add support for JavaScript-rendered pages"))
print(chat("Briefly, add rate limiting and error handling"))
# Continue chamando chat() enquanto a conversa precisar

Limitações atuais

• Mesmo modelo para a sumarização: O modelo especificado na sua requisição é usado para a sumarização. Não há opção para usar um modelo diferente (por exemplo, mais barato) para o resumo.

• A compactação pode falhar quando ferramentas estão definidas: Quando sua requisição inclui tools, o modelo ocasionalmente chama uma ferramenta durante a etapa interna de sumarização em vez de escrever um resumo. Quando isso ocorre, a resposta contém um bloco compaction com content: null. Para evitar isso, defina instructions com um prompt que diga explicitamente ao modelo para não chamar ferramentas, por exemplo:

  Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.

  

Próximos passos

Disponibilidade

Compactação por limite está em beta em modelos selecionados e é elegível para retenção zero de dados.

Suporte da API

Os cabeçalhos beta permitem que você acesse recursos experimentais e novas capacidades de modelos antes que eles se tornem parte da API padrão.