MensagensGerenciamento de contexto

Compactação

Compactação de contexto no lado do servidor para gerenciar conversas longas que se aproximam dos limites da janela de contexto.

Este recurso é elegível para Zero Data Retention (ZDR). Quando sua organização possui um acordo de ZDR, os dados enviados por meio deste recurso não são armazenados após a resposta da API ser retornada.

A compactação no lado do servidor é a estratégia recomendada para gerenciar contexto em conversas de longa duração e fluxos de trabalho agênticos. Ela lida com o gerenciamento de contexto automaticamente, sem código de sumarização no lado do cliente.

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

Para uma análise mais aprofundada sobre por que contextos longos degradam e como a compactação ajuda, consulte Effective context engineering.

Isso é ideal para:

Conversas multi-turno baseadas em chat, onde 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 uso de ferramentas) que pode exceder a janela de contexto

A compactação está em beta. Inclua o cabeçalho beta compact-2026-01-12 em suas requisições de API para usar este recurso.

Modelos suportados

A compactação é suportada nos seguintes modelos:

Claude Fable 5 (claude-fable-5)
Claude Mythos 5 (claude-mythos-5)
Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)

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:

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

Em 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.

Fluxo de compactação: quando os tokens de entrada atingem o gatilho, Claude escreve um resumo em um bloco de compactação e continua

Uso básico

Habilite a compactação adicionando a estratégia compact_20260112 a context_management.edits em sua requisição da 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-4-8",
    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

Parâmetro	Tipo	Padrão	Descrição
`type`	string	Obrigatório	Deve ser `"compact_20260112"`
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	Quando acionar a compactação. `input_tokens` é o único tipo de gatilho suportado. `value` deve ser de pelo menos 50.000 tokens.
`pause_after_compaction`	boolean	`false`	Se deve pausar após gerar o resumo de compactação
`instructions`	string	`null`	Prompt de sumarização personalizado. Substitui completamente o prompt padrão quando fornecido.

Configuração do gatilho

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-4-8",
    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 através do parâmetro instructions. 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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

Pausando após a compactação

Use pause_after_compaction para pausar a API após gerar o resumo de 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 stop reason 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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Verifique 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})

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

Impondo 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ção para estimar o uso cumulativo e encerrar a tarefa de forma elegante assim que um orçamento for atingido.

Este exemplo aparece apenas nas linguagens do SDK: seu valor está na lógica de rastreamento de orçamento em torno da requisição. A requisição bruta combina o trigger de Configuração do gatilho com 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-4-8",
    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 encerramento 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.

Output

{
  "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..."
    }
  ]
}

Passando blocos de compactação de volta

Você deve passar o bloco compaction de volta para a API em 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-4-8",
    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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

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 em sua lista e deixar a API lidar com a remoção do conteúdo compactado
Descartar manualmente as mensagens compactadas e incluir apenas do bloco de compactação em diante

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 então 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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            if event.content_block.type == "compaction":
                print("Compaction started...")
            elif event.content_block.type == "text":
                print("Text response started...")

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

    # Obtenha 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 cache de prompt. Você pode adicionar um breakpoint cache_control em 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 novo conteúdo que precisa ser gravado no cache. Sem breakpoints de cache adicionais, isso também invalidaria qualquer prompt do sistema em cache, exigindo que ele seja armazenado em cache novamente junto com o resumo de compactação.

Para maximizar as taxas de acerto de cache, adicione um breakpoint 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 de 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-4-8",
    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 limites de taxa e cobrança. A API retorna informações detalhadas de uso na resposta:

Output

{
  "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 para cada iteração de amostragem. Quando a compactação ocorre, você verá uma iteração compaction seguida pela iteração principal message. Os input_tokens e output_tokens de nível superior 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.

Os input_tokens e output_tokens de nível superior não incluem o uso da iteração de compactação. Eles refletem a soma de todas as iterações que não são de compactação. Para calcular o total de tokens consumidos e cobrados para uma requisição, some todas as entradas no array usage.iterations.

Se você anteriormente dependia de usage.input_tokens e usage.output_tokens para rastreamento de custos ou auditoria, precisará atualizar sua lógica de rastreamento para agregar em usage.iterations quando a compactação estiver habilitada. Com o beta de compactação habilitado, toda resposta inclui usage.iterations, mesmo que nenhuma compactação tenha ocorrido. Uma entrada compaction aparece apenas quando uma nova compactação é acionada durante a requisição. Reaplicar um bloco compaction anterior não incorre em custo adicional de compactação, e os campos de uso de nível superior permanecem precisos nesse caso.

Combinando com outros recursos

Ferramentas de servidor

Ao usar ferramentas de servidor (como busca na web), o gatilho de compactação é verificado no início de cada iteração de amostragem. A compactação pode ocorrer várias vezes dentro de 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 blocos compaction existentes em 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-4-8",
    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-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Anexa a resposta (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("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Continue chamando chat() pelo tempo que a conversa precisar

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) literalmente, em vez de resumi-las:

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-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Verifica se a compactação ocorreu e foi pausada
    if response.stop_reason == "compaction":
        # Obtém o bloco de compactação da resposta
        compaction_block = response.content[0]

        # Preserva a troca anterior + mensagem atual do usuário (3 mensagens)
        # incluindo-as após o bloco de compactação
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

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

        # Continua a requisição com o contexto compactado + mensagens preservadas
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-8",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

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

    # Anexa 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("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Continue chamando chat() pelo tempo que a conversa precisar

Limitações atuais

Mesmo modelo para sumarização: O modelo especificado em sua requisição é usado para sumarização. Não há opção de usar um modelo diferente (por exemplo, mais barato) para o resumo.
A compactação pode falhar quando ferramentas sã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 como um prompt que instrua explicitamente o modelo a 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

Edição de contexto

Gerencie automaticamente o contexto da conversa à medida que ele cresce com a edição de contexto.

Janelas de contexto

Saiba mais sobre tamanhos de janela de contexto e estratégias de gerenciamento.

Cookbook de compactação de memória de sessão

Explore uma implementação prática que gerencia conversas de longa duração com compactação instantânea de memória de sessão usando threading em segundo plano e cache de prompt.

Was this page helpful?

MensagensGerenciamento de contexto

Compactação

Compactação de contexto no lado do servidor para gerenciar conversas longas que se aproximam dos limites da janela de contexto.

Para uma análise mais aprofundada sobre por que contextos longos degradam e como a compactação ajuda, consulte Effective context engineering.

Isso é ideal para:

Conversas multi-turno baseadas em chat, onde 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 uso de ferramentas) que pode exceder a janela de contexto

A compactação está em beta. Inclua o cabeçalho beta compact-2026-01-12 em suas requisições de API para usar este recurso.

Modelos suportados

A compactação é suportada nos seguintes modelos:

Claude Fable 5 (claude-fable-5)
Claude Mythos 5 (claude-mythos-5)
Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)

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:

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

Uso básico

Habilite a compactação adicionando a estratégia compact_20260112 a context_management.edits em sua requisição da 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-4-8",
    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

Parâmetro	Tipo	Padrão	Descrição
`type`	string	Obrigatório	Deve ser `"compact_20260112"`
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	Quando acionar a compactação. `input_tokens` é o único tipo de gatilho suportado. `value` deve ser de pelo menos 50.000 tokens.
`pause_after_compaction`	boolean	`false`	Se deve pausar após gerar o resumo de compactação
`instructions`	string	`null`	Prompt de sumarização personalizado. Substitui completamente o prompt padrão quando fornecido.

Configuração do gatilho

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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Instruções de sumarização personalizadas

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 através do parâmetro instructions. 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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

Pausando após a compactação

Quando habilitado, a API retorna uma mensagem com o stop reason 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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Verifique 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})

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

Impondo um orçamento total de tokens

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-4-8",
    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 encerramento 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.

Output

{
  "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..."
    }
  ]
}

Passando blocos de compactação de volta

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

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 em sua lista e deixar a API lidar com a remoção do conteúdo compactado
Descartar manualmente as mensagens compactadas e incluir apenas do bloco de compactação em diante

Streaming

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

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

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

    # Obtenha 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 cache de prompt. Você pode adicionar um breakpoint cache_control em 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

O cache do prompt do sistema permanece válido e é lido do cache
Apenas o resumo de 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-4-8",
    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 limites de taxa e cobrança. A API retorna informações detalhadas de uso na resposta:

Output

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

Combinando com outros recursos

Ferramentas de servidor

Contagem de tokens

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    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-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Anexa a resposta (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("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Continue chamando chat() pelo tempo que a conversa precisar

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) literalmente, em vez de resumi-las:

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-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Verifica se a compactação ocorreu e foi pausada
    if response.stop_reason == "compaction":
        # Obtém o bloco de compactação da resposta
        compaction_block = response.content[0]

        # Preserva a troca anterior + mensagem atual do usuário (3 mensagens)
        # incluindo-as após o bloco de compactação
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

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

        # Continua a requisição com o contexto compactado + mensagens preservadas
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-8",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

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

    # Anexa 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("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Continue chamando chat() pelo tempo que a conversa precisar

Limitações atuais

Mesmo modelo para sumarização: O modelo especificado em sua requisição é usado para sumarização. Não há opção de usar um modelo diferente (por exemplo, mais barato) para o resumo.
A compactação pode falhar quando ferramentas sã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 como um prompt que instrua explicitamente o modelo a 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

Edição de contexto

Gerencie automaticamente o contexto da conversa à medida que ele cresce com a edição de contexto.

Janelas de contexto

Saiba mais sobre tamanhos de janela de contexto e estratégias de gerenciamento.

Cookbook de compactação de memória de sessão

Explore uma implementação prática que gerencia conversas de longa duração com compactação instantânea de memória de sessão usando threading em segundo plano e cache de prompt.

Was this page helpful?

Modelos suportados

Como a compactação funciona

Uso básico

Parâmetros

Configuração do gatilho

Instruções de sumarização personalizadas

Pausando após a compactação

Impondo um orçamento total de tokens

Trabalhando com blocos de compactação

Passando blocos de compactação de volta

Streaming

Cache de prompt

Maximizando acertos de cache com prompts do sistema

Entendendo o uso

Combinando com outros recursos

Ferramentas de servidor

Contagem de tokens

Exemplos

Limitações atuais

Próximos passos

Modelos suportados

Como a compactação funciona

Uso básico

Parâmetros

Configuração do gatilho

Instruções de sumarização personalizadas

Pausando após a compactação

Impondo um orçamento total de tokens

Trabalhando com blocos de compactação

Passando blocos de compactação de volta

Streaming

Cache de prompt

Maximizando acertos de cache com prompts do sistema

Entendendo o uso

Combinando com outros recursos

Ferramentas de servidor

Contagem de tokens

Exemplos

Limitações atuais

Próximos passos

Modelos suportados

Como a compactação funciona

Uso básico

Parâmetros

Configuração do gatilho

Instruções de sumarização personalizadas

Pausando após a compactação

Impondo um orçamento total de tokens

Trabalhando com blocos de compactação

Passando blocos de compactação de volta

Streaming

Cache de prompt

Maximizando acertos de cache com prompts do sistema

Entendendo o uso

Combinando com outros recursos

Ferramentas de servidor

Contagem de tokens

Exemplos

Limitações atuais

Próximos passos

Modelos suportados

Como a compactação funciona

Uso básico

Parâmetros

Configuração do gatilho

Instruções de sumarização personalizadas

Pausando após a compactação

Impondo um orçamento total de tokens

Trabalhando com blocos de compactação

Passando blocos de compactação de volta

Streaming

Cache de prompt

Maximizando acertos de cache com prompts do sistema

Entendendo o uso

Combinando com outros recursos

Ferramentas de servidor

Contagem de tokens

Exemplos

Limitações atuais

Próximos passos