Compactación en un umbral de tokens

La "threshold compaction" (compactación por umbral) es el tipo automático de "compaction" (compactación): estableces un umbral de tokens en tus solicitudes ordinarias, y la API resume el contexto anterior a mitad de una solicitud una vez que se alcanza el umbral. Se admite junto con la compactación bajo demanda, en la que tú decides cuándo se escribe el resumen (consulta Compactación bajo demanda). Para elegir entre ambas, consulta Elige cómo compactar.

La compactación amplía la longitud de contexto efectiva para conversaciones y tareas de larga duración al resumir automáticamente el contexto anterior cuando se acerca al límite de la "context window" (ventana de contexto). También mantiene pequeño el contexto activo: a medida que una conversación crece, la calidad de las respuestas se degrada, por lo que la compactación reemplaza el contenido anterior con un resumen conciso.

Esto es ideal para:

• Conversaciones de múltiples turnos basadas en chat en las que quieres que los usuarios utilicen un mismo chat durante un período prolongado
• Prompts orientados a tareas que requieren mucho trabajo de seguimiento (a menudo uso de herramientas) que podría exceder la ventana de contexto

Cómo funciona la compactación

Cuando la compactación está habilitada, Claude resume automáticamente tu conversación cuando alcanza el umbral de tokens configurado. La API:

1. Detecta cuándo los tokens de entrada alcanzan el umbral de activación que especificaste.
2. Genera un resumen de la conversación actual.
3. Crea un bloque compaction que contiene el resumen.
4. Continúa la respuesta con el contexto compactado.

En las solicitudes posteriores, agrega la respuesta a tus mensajes. La API descarta automáticamente todos los bloques de contenido anteriores al bloque compaction y continúa la conversación a partir del resumen.

Uso básico

Habilita la compactación agregando la estrategia compact_20260112 a context_management.edits en tu solicitud a la Messages API.

client = anthropic.Anthropic()

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

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

# Agrega la respuesta (incluido cualquier bloque de compactación) para continuar la conversación
messages.append({"role": "assistant", "content": response.content})

Parámetros

Configuración del disparador

Configura cuándo se activa la compactación usando el parámetro trigger:

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

Instrucciones de resumen personalizadas

El prompt de resumen predeterminado varía según el modelo. Cada prompt predeterminado le indica a Claude que escriba un resumen dentro de etiquetas <summary></summary> con la información necesaria para continuar la tarea en una ventana de contexto futura. Por ejemplo, algunos modelos usan el siguiente 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.

Puedes proporcionar instrucciones personalizadas mediante el parámetro instructions. Las instrucciones personalizadas no complementan el prompt predeterminado. Lo reemplazan por completo:

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

En Claude 5.1 y modelos posteriores, una solicitud con instructions personalizadas resume únicamente a partir de la conversación visible: los bloques de pensamiento anteriores no forman parte de la entrada del resumidor.

Pausar después de la compactación

Usa pause_after_compaction para pausar la API después de generar el resumen de compactación. Esto te permite agregar bloques de contenido adicionales (como conservar 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 el motivo de detención compaction después de generar el bloque de compactación:

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

# Comprueba si la compactación provocó una pausa
if response.stop_reason == "compaction":
    # La respuesta contiene solo el bloque de compactación
    messages.append({"role": "assistant", "content": response.content})

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

Aplicar un presupuesto total de tokens

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 compactaciones para estimar el uso acumulado y concluir la tarea de forma ordenada una vez que se alcance un presupuesto.

Este ejemplo aparece solo en los lenguajes de los SDK: su valor está en la lógica de seguimiento del presupuesto alrededor de la solicitud. La solicitud sin procesar combina el trigger de Configuración del disparador con pause_after_compaction de Pausar después de la compactación.

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

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

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

    # Estima el total de tokens consumidos; pide cerrar si se excede el presupuesto
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Trabajar con bloques de compactación

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 dar lugar a múltiples compactaciones. El último bloque de compactación refleja el estado final del prompt y reemplaza el contenido anterior a él 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..."
    }
  ]
}

Devolver los bloques de compactación

Debes devolver el bloque compaction a la API en las solicitudes posteriores para continuar la conversación con el prompt acortado. El enfoque más sencillo es agregar todo el contenido de la respuesta a tus mensajes:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# Después de recibir una respuesta con un bloque de compactación
messages.append({"role": "assistant", "content": response.content})

# Continúa la conversación
messages.append({"role": "user", "content": "Now add error handling"})

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

En Python, usa client.beta.messages, como hacen los ejemplos de esta página. Si llamas a client.messages y serializas los bloques tú mismo, un model_dump() simple agrega text: null y citations: null al bloque compaction. La API entonces rechaza la solicitud con un error 400 (Extra inputs are not permitted). Usa to_dict() o model_dump(exclude_none=True) en su lugar. Continuar a partir del resumen da el mismo consejo para la compactación bajo demanda.

Cuando la API recibe un bloque compaction, se ignoran todos los bloques de contenido anteriores a él. Puedes:

• Mantener los mensajes originales en tu lista y dejar que la API se encargue de eliminar el contenido compactado
• Descartar manualmente los mensajes compactados e incluir solo desde el bloque de compactación en adelante

En Claude Fable 5.1, Claude Mythos 5.1 y Claude Opus 5.5, los bloques de pensamiento anteriores a un bloque compaction no se trasladan, por lo que el resumen es todo lo que el modelo conserva de ese trabajo anterior. Si escribes tus propias instructions, indícale al modelo qué debe conservar el resumen; consulta Indica al modelo qué conservar en los resúmenes de compactación.

Streaming

El bloque de compactación se transmite por streaming de forma diferente a los bloques de texto. Recibes un evento content_block_start, seguido de un único content_block_delta con el contenido completo del resumen (sin streaming intermedio), y luego un evento content_block_stop.

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

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

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

    # Obtén el mensaje final acumulado
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Almacenamiento en caché de prompts

La compactación funciona bien con el "prompt caching" (almacenamiento en caché de prompts). Puedes agregar un punto de interrupción cache_control en los bloques de compactación para almacenar en caché el contenido resumido.

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

Maximizar los aciertos de caché con indicaciones del sistema

Cuando ocurre una compactación, el resumen se convierte en contenido nuevo que debe escribirse en la caché. Sin puntos de interrupción de caché adicionales, esto también invalidaría cualquier "system prompt" (indicación del sistema) almacenada en caché, lo que obligaría a volver a almacenarla en caché junto con el resumen de compactación.

Para maximizar las tasas de aciertos de caché, agrega un punto de interrupción cache_control al final de tu indicación del sistema. Esto mantiene la indicación del sistema almacenada en caché por separado de la conversación, de modo que cuando ocurre una compactación:

• La caché de la indicación del sistema sigue siendo válida y se lee desde la caché
• Solo el resumen de compactación debe escribirse como una nueva entrada de caché

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

Esto mantiene las indicaciones del sistema largas almacenadas en caché a lo largo de múltiples eventos de compactación durante una conversación.

Comprender el uso

La compactación requiere un paso de muestreo adicional, que cuenta para los "rate limits" (límites de velocidad) y la facturación. La API devuelve información detallada de uso en la respuesta:

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

El arreglo iterations muestra el uso de cada iteración de muestreo. Cuando ocurre una compactación, verás una iteración compaction seguida de la iteración principal message. Los valores de nivel superior input_tokens y output_tokens coinciden exactamente con la iteración message en este ejemplo porque solo hay una iteración que no es de compactación. Los recuentos de tokens de la iteración final reflejan el tamaño de contexto efectivo después de la compactación.

Combinar con otras funciones

Herramientas de servidor

Al usar herramientas de servidor (como la búsqueda web), el disparador de compactación se verifica al inicio de cada iteración de muestreo. La compactación puede ocurrir varias veces dentro de una sola solicitud, según tu umbral de activación y la cantidad de salida generada.

Conteo de tokens

El endpoint de conteo de tokens (/v1/messages/count_tokens) aplica los bloques compaction existentes en tu prompt, pero no activa nuevas compactaciones. Úsalo para verificar tu recuento de tokens efectivo después de compactaciones anteriores:

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

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

Ejemplos

Aquí tienes un ejemplo completo de una conversación de larga duración con compactación:

client = anthropic.Anthropic()

messages: list[dict] = []


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

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

    # Agrega la respuesta (los bloques de compactación se incluyen automáticamente)
    messages.append({"role": "assistant", "content": response.content})

    # Devuelve el contenido de texto
    return next(block.text for block in response.content if block.type == "text")


# Ejecuta una conversación larga
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"))
# Sigue llamando a chat() mientras la conversación lo necesite

En Claude Fable 5.1 y Claude Opus 5.5, elimina los bloques thinking y redacted_thinking de cualquier turno del asistente que vuelvas a insertar después del bloque de compactación, o envía thinking.block_binding.prefix_mismatch_behavior: "drop_block" con el encabezado beta thinking-binding-controls-2026-08-01. Esos bloques se produjeron cuando el historial completo estaba presente, por lo que ya no superan la verificación de la conversación. Donde se aplica la verificación, la solicitud de continuación se rechaza con un error 400. Los bloques de texto y de herramientas conservados pueden quedarse como están. Dejar que la API resuma todo, sin volver a insertar turnos anteriores, evita este problema.

Aquí tienes un ejemplo que usa pause_after_compaction para conservar textualmente el intercambio anterior y el mensaje actual del usuario (tres mensajes en total) en lugar de resumirlos:

from typing import Any

client = anthropic.Anthropic()

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


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

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

    # Comprueba si se produjo la compactación y se pausó
    if response.stop_reason == "compaction":
        # Obtén el bloque de compactación de la respuesta
        compaction_block = response.content[0]

        # Conserva el intercambio anterior + el mensaje actual del usuario (3 mensajes)
        # incluyéndolos después del bloque de compactación
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Crea la nueva lista de mensajes: compactación + mensajes conservados
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continúa la solicitud con el contexto compactado + los mensajes conservados
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-5-5",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Actualiza la lista de mensajes para reflejar la compactación
        messages.clear()
        messages.extend(messages_after_compaction)

    # Agrega la respuesta final
    messages.append({"role": "assistant", "content": response.content})

    # Devuelve el contenido de texto
    return next(block.text for block in response.content if block.type == "text")


# Ejecuta una conversación larga
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"))
# Sigue llamando a chat() mientras la conversación lo necesite

Limitaciones actuales

• Mismo modelo para el resumen: El modelo especificado en tu solicitud se usa para el resumen. No hay opción para usar un modelo diferente (por ejemplo, más económico) para el resumen.

• La compactación puede fallar cuando hay herramientas definidas: Cuando tu solicitud incluye tools, el modelo ocasionalmente llama a una herramienta durante el paso interno de resumen en lugar de escribir un resumen. Cuando esto ocurre, la respuesta contiene un bloque compaction con content: null. Para evitarlo, establece instructions con un prompt que le indique explícitamente al modelo que no llame a herramientas, por ejemplo:

  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 pasos

Compatibility