Was this page helpful?
A compactação no 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 trabalho de integração mínimo.
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. Isso é ideal para:
A compactação está atualmente em beta. Inclua o cabeçalho beta compact-2026-01-12 em suas solicitações de API para usar este recurso.
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 é suportada nos seguintes modelos:
claude-opus-4-6)Quando a compactação está ativada, Claude resume automaticamente sua conversa quando se aproxima do limite de tokens configurado. A API:
compaction contendo o resumo.Em solicitações subsequentes, anexe a resposta às suas mensagens. A API automaticamente remove todos os blocos de mensagem anteriores ao bloco compaction, continuando a conversa a partir do resumo.
Ative a compactação adicionando a estratégia compact_20260112 a context_management.edits em sua solicitação da API Messages.
| 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. |
Configure quando a compactação é acionada usando o parâmetro trigger:
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 através do parâmetro instructions para substituir este prompt completamente. Instruções personalizadas não complementam o padrão; elas o substituem completamente:
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 por instruções) antes da API continuar com a resposta.
Quando ativado, a API retorna uma mensagem com a razão de parada compaction após gerar o bloco de compactação:
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:
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-6",
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.",
}
)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..."
}
]
}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:
Quando a API recebe um bloco compaction, todos os blocos de conteúdo anteriores a ele são ignorados. Você pode:
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 então um evento content_block_stop.
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 cachear 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..."
}
]
}Quando a compactação ocorre, o resumo se torna 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-cacheado 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 em cache separadamente da conversa, então quando a compactação ocorre:
Esta abordagem é particularmente benéfica para prompts de sistema longos, pois permanecem em cache mesmo através de múltiplos eventos de compactação ao longo de uma conversa.
A compactação requer uma etapa de amostragem adicional, que contribui para limites de taxa e faturamento. A API retorna informações de uso detalhadas na resposta:
{
"usage": {
"input_tokens": 45000,
"output_tokens": 1234,
"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. 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 através de usage.iterations quando a compactação está 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.
Ao usar ferramentas de servidor (como busca na web), o acionador de compactação é verificado no início de cada iteração de amostragem. A compactação pode ocorrer múltiplas vezes dentro de uma única solicitação dependendo do seu limite de acionamento e da quantidade de saída gerada.
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:
Aqui está um exemplo completo de uma conversa de longa duração com compactação:
Aqui está um exemplo que usa pause_after_compaction para preservar as últimas duas mensagens (um turno de usuário + um turno de assistente) verbatim em vez de resumi-las:
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: compact-2026-01-12" \
--header "content-type: application/json" \
--data \
'{
"model": "claude-opus-4-6",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Help me build a website"
}
],
"context_management": {
"edits": [
{
"type": "compact_20260112"
}
]
}
}'response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-4-6",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 150000},
}
]
},
)response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-4-6",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
}
]
},
)response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-4-6",
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-6",
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-6",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)import anthropic
client = anthropic.Anthropic()
with client.beta.messages.stream(
betas=["compact-2026-01-12"],
model="claude-opus-4-6",
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})response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-4-6",
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"}]},
)count_response = client.beta.messages.count_tokens(
betas=["compact-2026-01-12"],
model="claude-opus-4-6",
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}")import anthropic
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-6",
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 neededimport anthropic
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-6",
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 last 2 messages (1 user + 1 assistant turn)
# by including them after the compaction block
preserved_messages = messages[-2:] if len(messages) >= 2 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-6",
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 neededExplore outras estratégias para gerenciar contexto de conversa, como limpeza de resultado de ferramenta e limpeza de bloco de pensamento.