Compactación

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 anterior cuando se aproxima al límite de la ventana de contexto. 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 de 200K

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

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.

Modelos compatibles

La compactación es compatible con los siguientes modelos:

Claude Opus 4.6 (claude-opus-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 automáticamente elimina todos los bloques de mensaje 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.

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 de activación

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

Instrucciones de resumen personalizado

Por defecto, la compactación utiliza la siguiente indicación de resumen:

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

Puedes proporcionar instrucciones personalizadas a través del parámetro instructions para reemplazar completamente esta indicación. Las instrucciones personalizadas no complementan la predeterminada; la reemplazan completamente:

Pausa 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 añadir bloques de contenido adicionales (como preservar mensajes recientes o mensajes específicos orientados a instrucciones) antes de que la API continúe con la respuesta.

Cuando está habilitado, la API devuelve un mensaje con la razón de parada compaction después de generar el bloque de compactación:

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 elegantemente la tarea una vez que se alcanza un presupuesto:

Python

TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

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

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

    # Estimate total tokens consumed; prompt wrap-up if over budget
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

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 resultar en múltiples compactaciones. El último bloque de compactación refleja el estado final de la indicación, reemplazando el contenido anterior con el resumen generado.

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

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 la indicación acortada. El enfoque más simple es añadir todo el contenido de la respuesta a tus mensajes:

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

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

Almacenamiento en caché de indicaciones

La compactación funciona bien con almacenamiento en caché de indicaciones. Puedes añadir un punto de ruptura 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 necesita escribirse en el caché. Sin puntos de ruptura de caché adicionales, esto también invalidaría cualquier indicación del sistema almacenada en caché, requiriendo que se almacene en caché nuevamente junto con el resumen de compactación.

Para maximizar las tasas de acierto de caché, añade un punto de ruptura 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é

Este enfoque es particularmente beneficioso para indicaciones del sistema largas, ya que permanecen almacenadas en caché incluso a través 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 de uso detallada en la respuesta:

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

El array iterations muestra el uso para cada iteración de muestreo. Cuando ocurre la compactación, verás una iteración compaction seguida de la iteración principal message. Los recuentos de tokens de la iteración final reflejan el tamaño de contexto efectivo después de la compactación.

Los campos input_tokens y output_tokens de nivel superior no incluyen el uso de iteración de compactación; reflejan la suma de todas las iteraciones que no son de compactación. Para calcular los tokens totales consumidos y facturados para una solicitud, suma 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, necesitarás actualizar tu lógica de seguimiento para agregar entre 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.

Combinación con otras características

Herramientas del servidor

Cuando se usan herramientas del servidor (como búsqueda web), el activador de compactación se verifica al inicio de cada iteración de muestreo. La compactación puede ocurrir múltiples veces dentro de una única solicitud dependiendo de tu umbral de activación y la cantidad de salida generada.

Conteo de tokens

El punto final de conteo de tokens (/v1/messages/count_tokens) aplica bloques compaction existentes en tu indicación pero no activa nuevas compactaciones. Úsalo para verificar tu recuento de tokens efectivo después de compactaciones anteriores:

Ejemplos

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

Aquí hay un ejemplo que usa pause_after_compaction para preservar los últimos dos mensajes (un turno de usuario + uno de asistente) literalmente en lugar de resumirlos:

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

Explora ejemplos prácticos e implementaciones en el libro de recetas.

Ventanas de contexto

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: compact-2026-01-12" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-6",
    "max_tokens": 4096,
    "messages": [
        {
            "role": "user",
            "content": "Help me build a website"
        }
    ],
    "context_management": {
        "edits": [
            {
                "type": "compact_20260112"
            }
        ]
    }
}'

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

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

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

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

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

# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
messages.append({"role": "user", "content": "Now add error handling"})

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

import anthropic

client = anthropic.Anthropic()

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

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

    # Get the final accumulated message
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

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

count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-6",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

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

import anthropic

client = anthropic.Anthropic()

messages: list[dict] = []


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

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

    # Append response (compaction blocks are automatically included)
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# ... continue as long as needed

import anthropic
from typing import Any

client = anthropic.Anthropic()

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


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

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

    # Check if compaction occurred and paused
    if response.stop_reason == "compaction":
        # Get the compaction block from the response
        compaction_block = response.content[0]

        # Preserve the last 2 messages (1 user + 1 assistant turn)
        # by including them after the compaction block
        preserved_messages = messages[-2:] if len(messages) >= 2 else messages

        # Build new message list: compaction + preserved messages
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continue the request with the compacted context + preserved messages
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-6",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Update our message list to reflect the compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Append the final response
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# ... continue as long as needed