MensajesGestión de contexto

Compactación

Compactación de contexto del lado del servidor para gestionar conversaciones largas que se acercan a los límites de la ventana de contexto.

Esta función es elegible para Zero Data Retention (ZDR). Cuando tu organización tiene un acuerdo de ZDR, los datos enviados a través de esta función no se almacenan después de que se devuelve la respuesta de la API.

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 agénticos. Maneja la gestión del contexto automáticamente, sin necesidad de código de resumen del lado del cliente.

La "compaction" (compactación) extiende la longitud efectiva del contexto para conversaciones y tareas de larga duración al resumir automáticamente el contexto más antiguo cuando se acerca al límite de la 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 más antiguo con un resumen conciso.

Para un análisis más profundo de por qué los contextos largos se degradan y cómo ayuda la compactación, consulta Effective context engineering.

Esto es ideal para:

Conversaciones de múltiples turnos basadas en chat donde 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

La compactación está en beta. Incluye el encabezado beta compact-2026-01-12 en tus solicitudes de API para usar esta función.

Modelos compatibles

La compactación es compatible con los siguientes 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)

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:

Detecta cuando los tokens de entrada alcanzan el umbral de activación que especificaste.
Genera un resumen de la conversación actual.
Crea un bloque compaction que contiene el resumen.
Continúa la respuesta con el contexto compactado.

En solicitudes posteriores, agrega la respuesta a tus mensajes. La API descarta automáticamente todos los bloques de contenido anteriores al bloque compaction, continuando la conversación desde el resumen.

Flujo de compactación: cuando los tokens de entrada alcanzan el umbral de activación, Claude escribe un resumen en un bloque de compactación y continúa

Uso básico

Habilita la compactación agregando la estrategia compact_20260112 a context_management.edits en tu solicitud de la API de 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-8",
    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

Parámetro	Tipo	Valor predeterminado	Descripción
`type`	string	Obligatorio	Debe ser `"compact_20260112"`
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	Cuándo activar la compactación. `input_tokens` es el único tipo de activador admitido. `value` debe ser de 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`	Prompt de resumen personalizado. Reemplaza completamente el prompt predeterminado cuando se proporciona.

Configuración del activador

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-4-8",
    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 uno de los predeterminados 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 a través del 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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

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

# Verifica si la compactación activó 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-4-8",
        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 finalizar la tarea de manera ordenada una vez que se alcance un presupuesto.

Este ejemplo aparece solo en los lenguajes del SDK: su valor radica en la lógica de seguimiento del presupuesto alrededor de la solicitud. La solicitud sin procesar combina el trigger de Configuración del activador 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-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 el total de tokens consumidos; solicita el cierre 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 podría resultar en múltiples compactaciones. El último bloque de compactación refleja el estado final del prompt, reemplazando el contenido anterior a él con el resumen generado.

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

Pasar bloques de compactación de vuelta

Debes pasar el bloque compaction de vuelta a la API en solicitudes posteriores para continuar la conversación con el prompt acortado. El enfoque más simple 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-4-8",
    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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Cuando la API recibe un bloque compaction, todos los bloques de contenido anteriores a él se ignoran. 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

Streaming

El bloque de compactación se transmite de manera 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-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)

    # 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 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 la 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 indicación del sistema almacenada en caché, requiriendo que se vuelva a almacenar 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 la compactación:

La caché de la indicación del sistema permanece válida y se lee desde la caché
Solo el resumen de compactación necesita 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-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"}]},
)

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

Entender el uso

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 detallada de uso en la respuesta:

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
      }
    ]
  }
}

El arreglo iterations muestra el uso de cada iteración de muestreo. Cuando ocurre la 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 efectivo del contexto después de la compactación.

Los valores de nivel superior input_tokens y output_tokens no incluyen el uso de la iteración de compactación. Reflejan la suma de todas las iteraciones que no son de compactación. Para calcular el total de tokens consumidos y facturados para una solicitud, suma todas las entradas del arreglo usage.iterations.

Si anteriormente dependías de usage.input_tokens y usage.output_tokens para el seguimiento de costos o auditoría, deberás actualizar tu lógica de seguimiento para agregar a través de usage.iterations cuando la compactación esté habilitada. Con la beta de compactación habilitada, cada respuesta incluye usage.iterations, incluso si no ocurrió ninguna compactación. Una entrada compaction aparece solo cuando se activa una nueva compactación durante la solicitud. Volver a aplicar un bloque compaction anterior no genera ningún costo adicional de compactación, y los campos de uso de nivel superior siguen siendo precisos en ese caso.

Combinación con otras funciones

Herramientas del servidor

Al usar herramientas del servidor (como la búsqueda web), el activador de compactación se verifica al inicio de cada iteración de muestreo. La compactación podría ocurrir varias veces dentro de una sola solicitud dependiendo de 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 efectivo de tokens 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-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}")

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-4-8",
        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"))
# Continúa llamando a chat() durante todo el tiempo que la conversación lo requiera

Aquí tienes un ejemplo que usa pause_after_compaction para preservar el intercambio anterior y el mensaje actual del usuario (tres mensajes en total) textualmente 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-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Verifica si ocurrió 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]

        # Preserva 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

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

        # Continúa la solicitud con el contexto compactado + mensajes preservados
        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"}]},
        )

        # Actualiza nuestra 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"))
# Continúa llamando a chat() tanto tiempo como la conversación lo requiera

Limitaciones actuales

Mismo modelo para el resumen: El modelo especificado en tu solicitud se usa para el resumen. No hay opción de usar un modelo diferente (por ejemplo, más económico) para el resumen.
La compactación podría 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 evitar esto, establece instructions con un prompt que 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

Edición de contexto

Gestiona automáticamente el contexto de la conversación a medida que crece con la edición de contexto.

Ventanas de contexto

Aprende sobre los tamaños de ventana de contexto y las estrategias de gestión.

Cookbook de compactación de memoria de sesión

Explora una implementación práctica que gestiona conversaciones de larga duración con compactación instantánea de memoria de sesión usando hilos en segundo plano y almacenamiento en caché de prompts.

Was this page helpful?

MensajesGestión de contexto

Compactación

Compactación de contexto del lado del servidor para gestionar conversaciones largas que se acercan a los límites de la ventana de contexto.

Para un análisis más profundo de por qué los contextos largos se degradan y cómo ayuda la compactación, consulta Effective context engineering.

Esto es ideal para:

Conversaciones de múltiples turnos basadas en chat donde 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

La compactación está en beta. Incluye el encabezado beta compact-2026-01-12 en tus solicitudes de API para usar esta función.

Modelos compatibles

La compactación es compatible con los siguientes 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)

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:

Detecta cuando los tokens de entrada alcanzan el umbral de activación que especificaste.
Genera un resumen de la conversación actual.
Crea un bloque compaction que contiene el resumen.
Continúa la respuesta con el contexto compactado.

Uso básico

Habilita la compactación agregando la estrategia compact_20260112 a context_management.edits en tu solicitud de la API de 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-8",
    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

Parámetro	Tipo	Valor predeterminado	Descripción
`type`	string	Obligatorio	Debe ser `"compact_20260112"`
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	Cuándo activar la compactación. `input_tokens` es el único tipo de activador admitido. `value` debe ser de 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`	Prompt de resumen personalizado. Reemplaza completamente el prompt predeterminado cuando se proporciona.

Configuración del activador

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

Instrucciones de resumen 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.

Puedes proporcionar instrucciones personalizadas a través del 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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

Pausar después de la compactación

Cuando está habilitado, la API devuelve un mensaje con el stop reason 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-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Verifica si la compactación activó 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-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

Aplicar un presupuesto 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 el total de tokens consumidos; solicita el cierre 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.

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

Pasar bloques de compactación de vuelta

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

Cuando la API recibe un bloque compaction, todos los bloques de contenido anteriores a él se ignoran. 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

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)

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

Almacenamiento en caché de prompts

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

La caché de la indicación del sistema permanece válida y se lee desde la caché
Solo el resumen de compactación necesita 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-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"}]},
)

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

Entender el uso

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 detallada de uso en la respuesta:

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
      }
    ]
  }
}

Combinación con otras funciones

Herramientas del servidor

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

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-4-8",
        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"))
# Continúa llamando a chat() durante todo el tiempo que la conversación lo requiera

Aquí tienes un ejemplo que usa pause_after_compaction para preservar el intercambio anterior y el mensaje actual del usuario (tres mensajes en total) textualmente 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-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Verifica si ocurrió 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]

        # Preserva 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

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

        # Continúa la solicitud con el contexto compactado + mensajes preservados
        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"}]},
        )

        # Actualiza nuestra 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"))
# Continúa llamando a chat() tanto tiempo como la conversación lo requiera

Limitaciones actuales

Mismo modelo para el resumen: El modelo especificado en tu solicitud se usa para el resumen. No hay opción de usar un modelo diferente (por ejemplo, más económico) para el resumen.
La compactación podría 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 evitar esto, establece instructions con un prompt que 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

Edición de contexto

Gestiona automáticamente el contexto de la conversación a medida que crece con la edición de contexto.

Ventanas de contexto

Aprende sobre los tamaños de ventana de contexto y las estrategias de gestión.

Cookbook de compactación de memoria de sesión

Was this page helpful?

Modelos compatibles

Cómo funciona la compactación

Uso básico

Parámetros

Configuración del activador

Instrucciones de resumen personalizadas

Pausar después de la compactación

Aplicar un presupuesto total de tokens

Trabajar con bloques de compactación

Pasar bloques de compactación de vuelta

Streaming

Almacenamiento en caché de prompts

Maximizar los aciertos de caché con indicaciones del sistema

Entender el uso

Combinación con otras funciones

Herramientas del servidor

Conteo de tokens

Ejemplos

Limitaciones actuales

Próximos pasos

Modelos compatibles

Cómo funciona la compactación

Uso básico

Parámetros

Configuración del activador

Instrucciones de resumen personalizadas

Pausar después de la compactación

Aplicar un presupuesto total de tokens

Trabajar con bloques de compactación

Pasar bloques de compactación de vuelta

Streaming

Almacenamiento en caché de prompts

Maximizar los aciertos de caché con indicaciones del sistema

Entender el uso

Combinación con otras funciones

Herramientas del servidor

Conteo de tokens

Ejemplos

Limitaciones actuales

Próximos pasos

Modelos compatibles

Cómo funciona la compactación

Uso básico

Parámetros

Configuración del activador

Instrucciones de resumen personalizadas

Pausar después de la compactación

Aplicar un presupuesto total de tokens

Trabajar con bloques de compactación

Pasar bloques de compactación de vuelta

Streaming

Almacenamiento en caché de prompts

Maximizar los aciertos de caché con indicaciones del sistema

Entender el uso

Combinación con otras funciones

Herramientas del servidor

Conteo de tokens

Ejemplos

Limitaciones actuales

Próximos pasos

Modelos compatibles

Cómo funciona la compactación

Uso básico

Parámetros

Configuración del activador

Instrucciones de resumen personalizadas

Pausar después de la compactación

Aplicar un presupuesto total de tokens

Trabajar con bloques de compactación

Pasar bloques de compactación de vuelta

Streaming

Almacenamiento en caché de prompts

Maximizar los aciertos de caché con indicaciones del sistema

Entender el uso

Combinación con otras funciones

Herramientas del servidor

Conteo de tokens

Ejemplos

Limitaciones actuales

Próximos pasos