Edición de contexto

Descripción general

La edición de contexto te permite borrar selectivamente contenido específico del historial de conversación a medida que crece. Esto te ayuda a optimizar costos y mantenerte dentro de los límites de la ventana de contexto. Esta página cubre:

• Borrado de resultados de herramientas - Mejor para flujos de trabajo con agentes que usan mucho las herramientas donde los resultados antiguos de herramientas ya no son necesarios
• Borrado de bloques de pensamiento - Para gestionar bloques de pensamiento cuando se usa pensamiento extendido, con opciones para preservar el pensamiento reciente para la continuidad del contexto
• Compactación del lado del cliente SDK - Una alternativa basada en SDK para la gestión de contexto basada en resúmenes (la compactación del lado del servidor es generalmente preferida)

Estrategias del lado del servidor

Borrado de resultados de herramientas

La estrategia clear_tool_uses_20250919 borra los resultados de herramientas cuando el contexto de la conversación crece más allá de tu umbral configurado. Esto es particularmente útil para flujos de trabajo con agentes que usan mucho las herramientas. Los resultados antiguos de herramientas (como contenidos de archivos o resultados de búsqueda) ya no son necesarios una vez que Claude los ha procesado.

Cuando se activa, la API borra automáticamente los resultados de herramientas más antiguos en orden cronológico. Cada resultado borrado se reemplaza con texto de marcador de posición para que Claude sepa que fue removido. Por defecto, solo se borran los resultados de herramientas. Opcionalmente, puedes borrar tanto los resultados de herramientas como las llamadas de herramientas (los parámetros de uso de herramientas) estableciendo clear_tool_inputs en true.

Borrado de bloques de pensamiento

La estrategia clear_thinking_20251015 gestiona bloques de thinking en conversaciones cuando el pensamiento extendido está habilitado. Esta estrategia te da control sobre la preservación del pensamiento: puedes elegir mantener más bloques de pensamiento para mantener la continuidad del razonamiento, o borrarlos más agresivamente para ahorrar espacio de contexto.

Un turno de conversación del asistente puede incluir múltiples bloques de contenido (por ejemplo, cuando se usan herramientas) y múltiples bloques de pensamiento (por ejemplo, con pensamiento intercalado).

La edición de contexto ocurre del lado del servidor

La edición de contexto se aplica del lado del servidor antes de que el mensaje llegue a Claude. Tu aplicación cliente mantiene el historial de conversación completo sin modificar. No necesitas sincronizar el estado de tu cliente con la versión editada. Continúa gestionando tu historial de conversación completo localmente como lo harías normalmente.

Edición de contexto y almacenamiento en caché de mensajes

La interacción de la edición de contexto con almacenamiento en caché de mensajes varía según la estrategia:

• Borrado de resultados de herramientas: Invalida los prefijos de mensajes en caché cuando se borra contenido. Para tener en cuenta esto, borra suficientes tokens para que la invalidación del caché valga la pena. Usa el parámetro clear_at_least para asegurar que se borre un número mínimo de tokens cada vez. Incurrirás en costos de escritura de caché cada vez que se borre contenido, pero las solicitudes posteriores pueden reutilizar el prefijo recién almacenado en caché.

• Borrado de bloques de pensamiento: Cuando los bloques de pensamiento son mantenidos en contexto (no borrados), el caché de mensajes se preserva, permitiendo aciertos de caché y reduciendo costos de tokens de entrada. Cuando los bloques de pensamiento son borrados, el caché se invalida en el punto donde ocurre el borrado. Configura el parámetro keep basándote en si deseas priorizar el rendimiento del caché o la disponibilidad de la ventana de contexto.

Modelos soportados

La edición de contexto está disponible en:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Uso del borrado de resultados de herramientas

La forma más simple de habilitar el borrado de resultados de herramientas es especificar solo el tipo de estrategia. Todas las otras opciones de configuración usan sus valores predeterminados:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Search for recent developments in AI"
            }
        ],
        "tools": [
            {
                "type": "web_search_20250305",
                "name": "web_search"
            }
        ],
        "context_management": {
            "edits": [
                {"type": "clear_tool_uses_20250919"}
            ]
        }
    }'

Configuración avanzada

Puedes personalizar el comportamiento del borrado de resultados de herramientas con parámetros adicionales:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Create a simple command line calculator app using Python"
            }
        ],
        "tools": [
            {
                "type": "text_editor_20250728",
                "name": "str_replace_based_edit_tool",
                "max_characters": 10000
            },
            {
                "type": "web_search_20250305",
                "name": "web_search",
                "max_uses": 3
            }
        ],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 3
                    },
                    "clear_at_least": {
                        "type": "input_tokens",
                        "value": 5000
                    },
                    "exclude_tools": ["web_search"]
                }
            ]
        }
    }'

Uso del borrado de bloques de pensamiento

Habilita el borrado de bloques de pensamiento para gestionar el contexto y el almacenamiento en caché de mensajes de forma efectiva cuando el pensamiento extendido está habilitado:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [...],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking_20251015",
                    "keep": {
                        "type": "thinking_turns",
                        "value": 2
                    }
                }
            ]
        }
    }'

Opciones de configuración para el borrado de bloques de pensamiento

La estrategia clear_thinking_20251015 soporta la siguiente configuración:

Configuraciones de ejemplo:

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Combinación de estrategias

Puedes usar tanto el borrado de bloques de pensamiento como el borrado de resultados de herramientas juntos:

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[...],
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[...],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {
                    "type": "thinking_turns",
                    "value": 2
                }
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {
                    "type": "input_tokens",
                    "value": 50000
                },
                "keep": {
                    "type": "tool_uses",
                    "value": 5
                }
            }
        ]
    }
)

Opciones de configuración para el borrado de resultados de herramientas

Respuesta de edición de contexto

Puedes ver qué ediciones de contexto se aplicaron a tu solicitud usando el campo de respuesta context_management, junto con estadísticas útiles sobre el contenido y los tokens de entrada borrados.

{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    "usage": {...},
    "context_management": {
        "applied_edits": [
            // When using `clear_thinking_20251015`
            {
                "type": "clear_thinking_20251015",
                "cleared_thinking_turns": 3,
                "cleared_input_tokens": 15000
            },
            // When using `clear_tool_uses_20250919`
            {
                "type": "clear_tool_uses_20250919",
                "cleared_tool_uses": 8,
                "cleared_input_tokens": 50000
            }
        ]
    }
}

Para respuestas de transmisión, las ediciones de contexto se incluirán en el evento final message_delta:

{
    "type": "message_delta",
    "delta": {
        "stop_reason": "end_turn",
        "stop_sequence": null
    },
    "usage": {
        "output_tokens": 1024
    },
    "context_management": {
        "applied_edits": [...]
    }
}

Conteo de tokens

El endpoint de conteo de tokens soporta gestión de contexto, permitiéndote previsualizar cuántos tokens usará tu mensaje después de que se aplique la edición de contexto.

curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "messages": [
            {
                "role": "user",
                "content": "Continue our conversation..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'

{
    "input_tokens": 25000,
    "context_management": {
        "original_input_tokens": 70000
    }
}

La respuesta muestra tanto el conteo de tokens final después de que se aplica la gestión de contexto (input_tokens) como el conteo de tokens original antes de que ocurra cualquier borrado (original_input_tokens).

Uso con la herramienta de memoria

La edición de contexto se puede combinar con la herramienta de memoria. Cuando el contexto de tu conversación se acerca al umbral de borrado configurado, Claude recibe una advertencia automática para preservar información importante. Esto permite que Claude guarde resultados de herramientas o contexto en sus archivos de memoria antes de que se borren del historial de conversación.

Esta combinación te permite:

• Preservar contexto importante: Claude puede escribir información esencial de los resultados de herramientas a archivos de memoria antes de que esos resultados se borren
• Mantener flujos de trabajo de larga duración: Habilita flujos de trabajo con agentes que de otro modo excederían los límites de contexto descargando información a almacenamiento persistente
• Acceder a información bajo demanda: Claude puede buscar información previamente borrada de archivos de memoria cuando sea necesario, en lugar de mantener todo en la ventana de contexto activa

Por ejemplo, en un flujo de trabajo de edición de archivos donde Claude realiza muchas operaciones, Claude puede resumir cambios completados a archivos de memoria a medida que crece el contexto. Cuando se borran los resultados de herramientas, Claude retiene acceso a esa información a través de su sistema de memoria y puede continuar trabajando efectivamente.

Para usar ambas características juntas, habilítalas en tu solicitud de API:

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # Your other tools
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {"type": "clear_tool_uses_20250919"}
        ]
    }
)

Compactación del lado del cliente (SDK)

La compactación es una característica del SDK que gestiona automáticamente el contexto de la conversación generando resúmenes cuando el uso de tokens crece demasiado. A diferencia de las estrategias de edición de contexto del lado del servidor que borran contenido, la compactación instruye a Claude para resumir el historial de conversación, luego reemplaza el historial completo con ese resumen. Esto permite que Claude continúe trabajando en tareas de larga duración que de otro modo excederían la ventana de contexto.

Cómo funciona la compactación

Cuando la compactación está habilitada, el SDK monitorea el uso de tokens después de cada respuesta del modelo:

1. Verificación de umbral: El SDK calcula tokens totales como input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens.
2. Generación de resumen: Cuando se excede el umbral, se inyecta un mensaje de resumen como un turno de usuario, y Claude genera un resumen estructurado envuelto en etiquetas <summary></summary>.
3. Reemplazo de contexto: El SDK extrae el resumen y reemplaza todo el historial de mensajes con él.
4. Continuación: La conversación se reanuda desde el resumen, con Claude continuando desde donde se quedó.

Uso de compactación

Añade compaction_control a tu llamada tool_runner:

import anthropic

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[
        {
            "role": "user",
            "content": "Analyze all the files in this directory and write a summary report."
        }
    ],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000
    }
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

final = runner.until_done()

Qué sucede durante la compactación

A medida que la conversación crece, el historial de mensajes se acumula:

Antes de la compactación (acercándose a 100k tokens):

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  { "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  { "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
  { "role": "assistant", "content": "After analyzing file2.txt..." },
  // ... 50 more exchanges like this ...
]

Cuando los tokens exceden el umbral, el SDK inyecta una solicitud de resumen y Claude genera un resumen. Todo el historial se reemplaza entonces:

Después de la compactación (de vuelta a ~2-3k tokens):

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude continúa trabajando desde este resumen como si fuera el historial de conversación original.

Opciones de configuración

Elegir un umbral de tokens

El umbral determina cuándo ocurre la compactación. Un umbral más bajo significa compactaciones más frecuentes con ventanas de contexto más pequeñas. Un umbral más alto permite más contexto pero arriesga alcanzar límites.

# More frequent compaction for memory-constrained scenarios
compaction_control={
    "enabled": True,
    "context_token_threshold": 50000
}

# Less frequent compaction when you need more context
compaction_control={
    "enabled": True,
    "context_token_threshold": 150000
}

Usar un modelo diferente para resúmenes

Puedes usar un modelo más rápido o más barato para generar resúmenes:

compaction_control={
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5"
}

Mensajes de resumen personalizados

Puedes proporcionar un mensaje personalizado para necesidades específicas del dominio. Tu mensaje debe instruir a Claude para envolver su resumen en etiquetas <summary></summary>.

compaction_control={
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags."""
}

Aviso de resumen predeterminado

El aviso de resumen integrado instruye a Claude para crear un resumen de continuación estructurado que incluya:

1. Descripción General de la Tarea: La solicitud principal del usuario, criterios de éxito y restricciones.
2. Estado Actual: Qué se ha completado, archivos modificados y artefactos producidos.
3. Descubrimientos Importantes: Restricciones técnicas, decisiones tomadas, errores resueltos y enfoques fallidos.
4. Próximos Pasos: Acciones específicas necesarias, bloqueadores y orden de prioridad.
5. Contexto a Preservar: Preferencias del usuario, detalles específicos del dominio y compromisos realizados.

Esta estructura permite que Claude reanude el trabajo de manera eficiente sin perder contexto importante ni repetir errores.

Limitaciones

Herramientas del lado del servidor

Al usar herramientas del lado del servidor, el SDK puede calcular incorrectamente el uso de tokens, causando que la compactación se active en el momento incorrecto.

Por ejemplo, después de una operación de búsqueda web, la respuesta de la API podría mostrar:

{
  "usage": {
    "input_tokens": 63000,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

El SDK calcula el uso total como 63,000 + 270,000 = 333,000 tokens. Sin embargo, el valor cache_read_input_tokens incluye lecturas acumuladas de múltiples llamadas internas de API realizadas por la herramienta del lado del servidor, no tu contexto de conversación real. Tu longitud de contexto real podría ser solo los 63,000 input_tokens, pero el SDK ve 333k y activa la compactación prematuramente.

Soluciones alternativas:

• Usa el punto final de conteo de tokens para obtener la longitud de contexto precisa
• Evita la compactación cuando uses herramientas del lado del servidor extensamente

Casos extremos de uso de herramientas

Cuando la compactación se activa mientras una respuesta de uso de herramientas está pendiente, el SDK elimina el bloque de uso de herramientas del historial de mensajes antes de generar el resumen. Claude volverá a emitir la llamada de herramienta después de reanudar desde el resumen si aún es necesario.

Monitoreo de compactación

Habilita el registro para rastrear cuándo ocurre la compactación:

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# Los registros mostrarán:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

Cuándo usar compactación

Casos de uso buenos:

• Tareas de agente de larga duración que procesan muchos archivos o fuentes de datos
• Flujos de trabajo de investigación que acumulan grandes cantidades de información
• Tareas de múltiples pasos con progreso claro y medible
• Tareas que producen artefactos (archivos, informes) que persisten fuera de la conversación

Casos de uso menos ideales:

• Tareas que requieren recuerdo preciso de detalles de conversación temprana
• Flujos de trabajo que usan herramientas del lado del servidor extensamente
• Tareas que necesitan mantener estado exacto en muchas variables