La compactación del lado del servidor es la estrategia recomendada para gestionar el contexto en conversaciones de larga duración y flujos de trabajo con agentes. Maneja la gestión del contexto automáticamente con un trabajo de integración mínimo.
La compactación extiende la longitud de contexto efectiva para conversaciones y tareas de larga duración resumiendo automáticamente el contexto anterior cuando se aproxima al límite de la ventana de contexto. Esto es ideal para:
La compactación está actualmente en beta. Incluye el encabezado beta compact-2026-01-12 en tus solicitudes de API para usar esta función.
La compactación es compatible con los siguientes modelos:
claude-opus-4-6)Cuando la compactación está habilitada, Claude resume automáticamente tu conversación cuando se aproxima al umbral de tokens configurado. La API:
compaction que contiene el resumen.En solicitudes posteriores, añade la respuesta a tus mensajes. La API automáticamente elimina todos los bloques de mensajes anteriores al bloque compaction, continuando la conversación desde el resumen.
Habilita la compactación añadiendo la estrategia compact_20260112 a context_management.edits en tu solicitud de API de Mensajes.
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
type | string | Requerido | Debe ser "compact_20260112" |
trigger | object | 150,000 tokens | Cuándo activar la compactación. Debe ser al menos 50,000 tokens. |
pause_after_compaction | boolean | false | Si se debe pausar después de generar el resumen de compactación |
instructions | string | null | Indicación de resumen personalizada. Reemplaza completamente la indicación predeterminada cuando se proporciona. |
Configura cuándo se activa la compactación usando el parámetro trigger:
Por defecto, la compactación utiliza la siguiente indicación de resumen:
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.Puedes proporcionar instrucciones personalizadas a través del parámetro instructions para reemplazar completamente esta indicación. Las instrucciones personalizadas no complementan la predeterminada; la reemplazan completamente:
Usa pause_after_compaction para pausar la API después de generar el resumen de compactación. Esto te permite añadir bloques de contenido adicionales (como preservar mensajes recientes o mensajes específicos orientados a instrucciones) antes de que la API continúe con la respuesta.
Cuando está habilitado, la API devuelve un mensaje con la razón de parada compaction después de generar el bloque de compactación:
Cuando un modelo trabaja en tareas largas con muchas iteraciones de uso de herramientas, el consumo total de tokens puede crecer significativamente. Puedes combinar pause_after_compaction con un contador de compactación para estimar el uso acumulativo y terminar elegantemente la tarea una vez que se alcanza un presupuesto:
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.",
})Cuando se activa la compactación, la API devuelve un bloque compaction al inicio de la respuesta del asistente.
Una conversación de larga duración puede resultar en múltiples compactaciones. El último bloque de compactación refleja el estado final de la indicación, reemplazando el contenido anterior con el resumen generado.
{
"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..."
}
]
}Debes pasar el bloque compaction de vuelta a la API en solicitudes posteriores para continuar la conversación con la indicación acortada. El enfoque más simple es añadir todo el contenido de la respuesta a tus mensajes:
Cuando la API recibe un bloque compaction, todos los bloques de contenido anteriores se ignoran. Puedes:
Cuando transmites respuestas con compactación habilitada, recibirás un evento content_block_start cuando comience la compactación. El bloque de compactación se transmite de manera diferente a los bloques de texto. Recibirás un evento content_block_start, seguido de un único content_block_delta con el contenido de resumen completo (sin transmisión intermedia), y luego un evento content_block_stop.
Puedes añadir un punto de ruptura cache_control en bloques de compactación, que almacena en caché la indicación del sistema completa junto con el contenido resumido. El contenido compactado original se ignora.
{
"role": "assistant",
"content": [
{
"type": "compaction",
"content": "[summary text]",
"cache_control": {"type": "ephemeral"}
},
{
"type": "text",
"text": "Based on our conversation..."
}
]
}La compactación requiere un paso de muestreo adicional, que contribuye a los límites de velocidad y la facturación. La API devuelve información de uso detallada en la respuesta:
{
"usage": {
"input_tokens": 45000,
"output_tokens": 1234,
"iterations": [
{
"type": "compaction",
"input_tokens": 180000,
"output_tokens": 3500
},
{
"type": "message",
"input_tokens": 23000,
"output_tokens": 1000
}
]
}
}El array iterations muestra el uso para cada iteración de muestreo. Cuando ocurre la compactación, verás una iteración compaction seguida de la iteración principal message. Los recuentos de tokens de la iteración final reflejan el tamaño de contexto efectivo después de la compactación.
Los input_tokens y output_tokens de nivel superior no incluyen el uso de iteración de compactación—reflejan la suma de todas las iteraciones que no son de compactación. Para calcular los tokens totales consumidos y facturados para una solicitud, suma en todas las entradas del array usage.iterations.
Si anteriormente confiabas en usage.input_tokens y usage.output_tokens para el seguimiento de costos o auditoría, necesitarás actualizar tu lógica de seguimiento para agregar en usage.iterations cuando la compactación está habilitada. El array iterations solo se completa cuando se activa una nueva compactación durante la solicitud. Reaplicar un bloque compaction anterior no incurre en costo de compactación adicional, y los campos de uso de nivel superior permanecen precisos en ese caso.
Cuando se usan herramientas del servidor (como búsqueda web), el activador de compactación se verifica al inicio de cada iteración de muestreo. La compactación puede ocurrir múltiples veces dentro de una única solicitud dependiendo de tu umbral de activación y la cantidad de salida generada.
El punto final de conteo de tokens (/v1/messages/count_tokens) aplica bloques compaction existentes en tu indicación pero no activa nuevas compactaciones. Úsalo para verificar tu recuento de tokens efectivo después de compactaciones anteriores:
Aquí hay un ejemplo completo de una conversación de larga duración con compactación:
Aquí hay un ejemplo que usa pause_after_compaction para preservar los últimos dos mensajes (un turno de usuario + uno de asistente) textualmente en lugar de resumirlos:
Was this page helpful?
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})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 neededExplora ejemplos prácticos e implementaciones en el libro de recetas.