Compactación

ConstruirGestió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.

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.

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 de agentes. Maneja la gestión del contexto automáticamente con un trabajo de integración mínimo.

La compactación extiende la longitud efectiva del contexto para conversaciones y tareas de larga duración resumiendo automáticamente el contexto más antiguo cuando se aproxima al límite de la ventana de contexto. Esto no se trata solo de mantenerse por debajo de un límite de tokens. A medida que las conversaciones se hacen más largas, los modelos tienen dificultades para mantener el enfoque en todo el historial. La compactación mantiene el contexto activo enfocado y eficiente reemplazando el contenido obsoleto con resúmenes concisos.

Para una mirada más profunda a por qué los contextos largos se degradan y cómo la compactación ayuda, consulta Ingeniería de contexto efectiva.

Esto es ideal para:

Conversaciones basadas en chat de múltiples turnos donde deseas que los usuarios usen un chat durante un largo período de tiempo
Indicaciones orientadas a tareas que requieren mucho trabajo de seguimiento (a menudo uso de herramientas) que pueden 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 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)

Cómo funciona la compactación

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

Detecta cuando los tokens de entrada exceden tu umbral de activación especificado.
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, añade la respuesta a tus mensajes. La API elimina automáticamente todos los bloques de mensajes anteriores al bloque compaction, continuando la conversación desde el resumen.

Diagrama de flujo que muestra el proceso de compactación: cuando los tokens de entrada exceden el umbral de activación, Claude genera un resumen en un bloque de compactación y continúa la respuesta con el contexto compactado

Uso básico

Habilita la compactación añadiendo la estrategia compact_20260112 a context_management.edits en tu solicitud de API de Mensajes.

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	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.

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

Instrucciones de resumen personalizado

De forma predeterminada, 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:

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

Pausa después de la compactación

Utiliza 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 orientados a instrucciones específicas) 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:

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

Aplicación de 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 compactación para estimar el uso acumulativo y finalizar la tarea de manera elegante una vez que se alcanza un presupuesto:

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

Trabajo 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 resultar en múltiples compactaciones. El último bloque de compactación refleja el estado final del prompt, reemplazando el contenido anterior 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..."
    }
  ]
}

Devolución de bloques de compactación

Debes devolver el bloque compaction 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-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"}]},
)

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

Mantener los mensajes originales en tu lista y dejar que la API maneje la eliminación del contenido compactado
Eliminar manualmente los mensajes compactados e incluir solo el bloque de compactación en adelante

Transmisión

Cuando transmites respuestas con la 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.

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

Almacenamiento en caché de indicaciones

La compactación funciona bien con el almacenamiento en caché de indicaciones. Puedes agregar un punto de interrupción cache_control en bloques de compactación para almacenar en caché 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..."
    }
  ]
}

Maximizar aciertos de caché con indicaciones del sistema

Cuando ocurre la compactación, el resumen se convierte en contenido nuevo que debe escribirse en el 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 acierto 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é separada de la conversación, por lo que cuando ocurre la compactación:

El caché de la indicación del sistema permanece válido y se lee desde el 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-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"}]},
)

Este enfoque es particularmente beneficioso para indicaciones del sistema largas, ya que permanecen almacenadas en caché incluso en múltiples eventos de compactación a lo largo de 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 de uso detallada 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 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 input_tokens y output_tokens de nivel superior coinciden exactamente con la iteración message en este ejemplo porque hay solo una iteración sin compactación. 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 la iteración de compactación. Reflejan la suma de todas las iteraciones sin compactación. Para calcular los tokens totales consumidos y facturados para una solicitud, suma todos los valores en el array usage.iterations.

Si anteriormente confiabas en 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 valores 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.

Combinar con otras características

Herramientas del servidor

Cuando se usan herramientas del servidor (como búsqueda web), el disparador 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 disparo y la cantidad de salida generada.

Conteo de tokens

El endpoint 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:

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

Ejemplos

Aquí hay 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-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

Aquí hay un ejemplo que usa pause_after_compaction para preservar el intercambio anterior y el mensaje del usuario actual (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-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

Limitaciones actuales

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

Próximos pasos

Libro de recetas 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 threading de fondo y almacenamiento en caché de indicaciones.

Ventanas de contexto

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

Edición de contexto

Explora otras estrategias para gestionar el contexto de la conversación como la limpieza de resultados de herramientas y la limpieza de bloques de pensamiento.

Was this page helpful?

ConstruirGestió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.

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 una mirada más profunda a por qué los contextos largos se degradan y cómo la compactación ayuda, consulta Ingeniería de contexto efectiva.

Esto es ideal para:

Conversaciones basadas en chat de múltiples turnos donde deseas que los usuarios usen un chat durante un largo período de tiempo
Indicaciones orientadas a tareas que requieren mucho trabajo de seguimiento (a menudo uso de herramientas) que pueden 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 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)

Cómo funciona la compactación

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

Detecta cuando los tokens de entrada exceden tu umbral de activación especificado.
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 añadiendo la estrategia compact_20260112 a context_management.edits en tu solicitud de API de Mensajes.

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	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.

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

Instrucciones de resumen personalizado

De forma predeterminada, 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.

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

Pausa después de la compactación

Cuando está habilitado, la API devuelve un mensaje con la razón de parada 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-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"}]},
    )

Aplicación de un presupuesto 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.",
            }
        )

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

Devolución de bloques 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-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"}]},
)

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

Mantener los mensajes originales en tu lista y dejar que la API maneje la eliminación del contenido compactado
Eliminar manualmente los mensajes compactados e incluir solo el bloque de compactación en adelante

Transmisión

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

Almacenamiento en caché de indicaciones

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

Maximizar aciertos de caché con indicaciones del sistema

El caché de la indicación del sistema permanece válido y se lee desde el 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-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"}]},
)

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 de uso detallada 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
      }
    ]
  }
}

Combinar con otras características

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

Ejemplos

Aquí hay 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-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

Aquí hay un ejemplo que usa pause_after_compaction para preservar el intercambio anterior y el mensaje del usuario actual (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-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

Limitaciones actuales

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

Próximos pasos

Libro de recetas de compactación de memoria de sesión

Ventanas de contexto

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

Edición de contexto

Explora otras estrategias para gestionar el contexto de la conversación como la limpieza de resultados de herramientas y la limpieza de bloques de pensamiento.

Was this page helpful?