Compactação

ConstruirGerenciamento de contexto

Compactação

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

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

A compactação do lado do servidor é a estratégia recomendada para gerenciar contexto em conversas de longa duração e fluxos de trabalho com agentes. Ela gerencia o contexto automaticamente com o mínimo de trabalho de integração.

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 janela de contexto. Não se trata apenas de ficar abaixo de um limite de tokens. À medida que as conversas ficam mais longas, os modelos têm dificuldade em manter o foco em todo o histórico. A compactação mantém o contexto ativo focado e com bom desempenho, substituindo conteúdo obsoleto por resumos concisos.

Para uma análise mais profunda sobre por que contextos longos se degradam e como a compactação ajuda, consulte Engenharia de contexto eficaz.

Isso é ideal para:

Conversas baseadas em chat, com múltiplos turnos, onde você deseja que os usuários usem um chat por um longo período de tempo
Prompts orientados por tarefas que requerem muito trabalho de acompanhamento (frequentemente uso de ferramentas) que podem exceder a janela de contexto

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

Modelos suportados

A compactação é suportada nos seguintes modelos:

Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Como funciona a compactação

Quando a compactação está ativada, Claude resume automaticamente sua conversa quando se aproxima do limite de tokens configurado. A API:

Detecta quando os tokens de entrada excedem seu 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 solicitações subsequentes, anexe a resposta às suas mensagens. A API automaticamente descarta todos os blocos de mensagens anteriores ao bloco compaction, continuando a conversa a partir do resumo.

Diagrama de fluxo mostrando o processo de compactação: quando os tokens de entrada excedem o limite de acionamento, Claude gera um resumo em um bloco de compactação e continua a resposta com o contexto compactado

Uso básico

Ative a compactação adicionando a estratégia compact_20260112 a context_management.edits em sua solicitação da API Messages.

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

# Append the response (including any compaction block) to continue the conversation
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	150.000 tokens	Quando acionar a compactação. Deve ser 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 resumo personalizado. Substitui completamente o prompt padrão quando fornecido.

Configuração de acionamento

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

Instruções de resumo personalizado

Por padrão, a compactação usa o seguinte prompt de resumo:

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 para substituir completamente este prompt. Instruções personalizadas não complementam o 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-7",
    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 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 orientadas por instruções específicas) antes da API continuar com a resposta.

Quando ativado, 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-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

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

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ção para estimar o uso cumulativo e encerrar graciosamente a tarefa uma vez que um orçamento é atingido:

Python

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-7",
    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})

    # Estimate total tokens consumed; prompt wrap-up if over budget
    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 solicitaçõ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-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

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

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    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 o bloco de compactação em diante

Streaming

Ao fazer streaming de respostas com compactação ativada, você receberá um evento content_block_start quando a compactação começar. O bloco de compactação faz streaming de forma diferente dos blocos de texto. Você receberá um evento content_block_start, seguido por um único content_block_delta com o conteúdo de resumo completo (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-4-7",
    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)} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # Get the final accumulated message
    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 ponto de interrupção cache_control em blocos de compactação para armazenar em cache o conteúdo resumido. O conteúdo compactado original é ignorado.

{
  "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 de sistema

Quando a compactação ocorre, o resumo se torna um novo conteúdo que precisa ser escrito no cache. Sem pontos de interrupção de cache adicionais, isso também invalidaria qualquer prompt de sistema em cache, exigindo que seja re-armazenado em cache junto com o resumo de compactação.

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

O cache do prompt de sistema permanece válido e é lido do cache
Apenas o resumo de compactação precisa ser escrito 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-7",
    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"}]},
)

Esta abordagem é particularmente benéfica para prompts de sistema longos, pois permanecem em cache mesmo em múltiplos eventos de compactação ao longo de uma conversa.

Entendendo o uso

A compactação requer uma etapa de amostragem adicional, que contribui para limites de taxa e faturamento. 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 não-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 não-compactação. Para calcular o total de tokens consumidos e faturados para uma solicitação, some todos os valores no array usage.iterations.

Se você anteriormente confiava em usage.input_tokens e usage.output_tokens para rastreamento de custos ou auditoria, você precisará atualizar sua lógica de rastreamento para agregar entre usage.iterations quando a compactação estiver ativada. O array iterations é preenchido apenas quando uma nova compactação é acionada durante a solicitação. Re-aplicar um bloco compaction anterior não incorre em custo de compactação adicional, 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 em uma única solicitação dependendo do seu limite de gatilho 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 dispara 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-7",
    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-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Append response (compaction blocks are automatically included)
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
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 as long as needed

Aqui está um exemplo que usa pause_after_compaction para preservar a troca anterior e a mensagem do usuário atual (três mensagens no total) verbatim 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-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Check if compaction occurred and paused
    if response.stop_reason == "compaction":
        # Get the compaction block from the response
        compaction_block = response.content[0]

        # Preserve the prior exchange + current user message (3 messages)
        # by including them after the compaction block
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Build new message list: compaction + preserved messages
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continue the request with the compacted context + preserved messages
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-7",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Update our message list to reflect the compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Append the final response
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
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 as long as needed

Limitações atuais

Mesmo modelo para resumo: O modelo especificado em sua solicitação é usado para resumo. Não há opção de usar um modelo diferente (por exemplo, mais barato) para o resumo.

Próximas etapas

Livro de receitas 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.

Janelas de contexto

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

Edição de contexto

Explore outras estratégias para gerenciar contexto de conversa, como limpeza de resultado de ferramenta e limpeza de bloco de pensamento.

Was this page helpful?

ConstruirGerenciamento de contexto

Compactação

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

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Para uma análise mais profunda sobre por que contextos longos se degradam e como a compactação ajuda, consulte Engenharia de contexto eficaz.

Isso é ideal para:

Conversas baseadas em chat, com múltiplos turnos, onde você deseja que os usuários usem um chat por um longo período de tempo
Prompts orientados por tarefas que requerem muito trabalho de acompanhamento (frequentemente uso de ferramentas) que podem exceder a janela de contexto

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

Modelos suportados

A compactação é suportada nos seguintes modelos:

Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Como funciona a compactação

Quando a compactação está ativada, Claude resume automaticamente sua conversa quando se aproxima do limite de tokens configurado. A API:

Detecta quando os tokens de entrada excedem seu 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

Ative a compactação adicionando a estratégia compact_20260112 a context_management.edits em sua solicitação da API Messages.

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

# Append the response (including any compaction block) to continue the conversation
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	150.000 tokens	Quando acionar a compactação. Deve ser 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 resumo personalizado. Substitui completamente o prompt padrão quando fornecido.

Configuração de acionamento

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

Instruções de resumo personalizado

Por padrão, a compactação usa o seguinte prompt de resumo:

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.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    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 compactação

Quando ativado, 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-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

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

Aplicando um orçamento total de tokens

Python

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-7",
    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})

    # Estimate total tokens consumed; prompt wrap-up if over budget
    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-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

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

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    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 o 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-7",
    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)} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # Get the final accumulated message
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Cache de prompt

{
  "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 de sistema

O cache do prompt de sistema permanece válido e é lido do cache
Apenas o resumo de compactação precisa ser escrito 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-7",
    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"}]},
)

Esta abordagem é particularmente benéfica para prompts de sistema longos, pois permanecem em cache mesmo em múltiplos eventos de compactação ao longo de uma conversa.

Entendendo o uso

A compactação requer uma etapa de amostragem adicional, que contribui para limites de taxa e faturamento. 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-7",
    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-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Append response (compaction blocks are automatically included)
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
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 as long as needed

Aqui está um exemplo que usa pause_after_compaction para preservar a troca anterior e a mensagem do usuário atual (três mensagens no total) verbatim 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-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Check if compaction occurred and paused
    if response.stop_reason == "compaction":
        # Get the compaction block from the response
        compaction_block = response.content[0]

        # Preserve the prior exchange + current user message (3 messages)
        # by including them after the compaction block
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Build new message list: compaction + preserved messages
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continue the request with the compacted context + preserved messages
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-7",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Update our message list to reflect the compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Append the final response
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
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 as long as needed

Limitações atuais

Mesmo modelo para resumo: O modelo especificado em sua solicitação é usado para resumo. Não há opção de usar um modelo diferente (por exemplo, mais barato) para o resumo.

Próximas etapas

Livro de receitas 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.

Janelas de contexto

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

Edição de contexto

Explore outras estratégias para gerenciar contexto de conversa, como limpeza de resultado de ferramenta e limpeza de bloco de pensamento.

Was this page helpful?