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. Más allá de optimizar costos y mantenerse dentro de los límites, se trata de curar activamente lo que Claude ve: el contexto es un recurso finito con rendimientos decrecientes, y el contenido irrelevante degrada el enfoque del modelo. La edición de contexto te proporciona control de tiempo de ejecución granular sobre esa curación. Para los principios más amplios detrás de la administración del contexto, consulta Ingeniería de contexto efectiva. Esta página cubre:

• Borrado de resultados de herramientas - Mejor para flujos de trabajo de agentes con uso intensivo de herramientas donde los resultados de herramientas antiguos ya no son necesarios
• Borrado de bloques de pensamiento - Para administrar bloques de pensamiento al usar pensamiento extendido, con opciones para preservar el pensamiento reciente para la continuidad del contexto
• Compactación del SDK del lado del cliente - Una alternativa basada en SDK para la administración de contexto basada en resúmenes (la compactación del lado del servidor generalmente es 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 de agentes con uso intensivo de herramientas. Los resultados de herramientas más antiguos (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. La API reemplaza cada resultado borrado con texto de marcador de posición para que Claude sepa que fue eliminado. De forma predeterminada, 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) configurando clear_tool_inputs en verdadero.

Borrado de bloques de pensamiento

La estrategia clear_thinking_20251015 administra bloques thinking en conversaciones cuando el pensamiento extendido está habilitado. Esta estrategia te proporciona 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 administrando 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 mensaje 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, habilitando 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 todos los modelos Claude soportados.

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:

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    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:

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # Trigger clearing when threshold is exceeded
                "trigger": {"type": "input_tokens", "value": 30000},
                # Number of tool uses to keep after clearing
                "keep": {"type": "tool_uses", "value": 3},
                # Optional: Clear at least this many tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Exclude these tools from being cleared
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

Uso de limpieza de bloques de pensamiento

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

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

Opciones de configuración para la limpieza de bloques de pensamiento

La estrategia clear_thinking_20251015 admite la siguiente configuración:

Configuraciones de ejemplo:

Mantener bloques de pensamiento de los últimos 3 turnos del asistente:

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

Mantener todos los bloques de pensamiento (maximiza los aciertos de caché):

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Combinación de estrategias

Puedes usar tanto la limpieza de bloques de pensamiento como la limpieza de resultados de herramientas juntas:

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    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 la limpieza 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 limpiados.

{
  "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 admite la gestión de contexto, permitiéndote obtener una vista previa de cuántos tokens usará tu indicación después de que se aplique la edición de contexto.

response = client.beta.messages.count_tokens(
    model="claude-opus-4-7",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    tools=[...],  # Your tool definitions
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management['original_input_tokens']}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management['original_input_tokens'] - response.input_tokens} tokens"
)

{
  "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 limpieza (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 limpieza 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 limpien del historial de conversación.

Esta combinación te permite:

• Preservar contexto importante: Claude puede escribir información esencial de los resultados de herramientas en archivos de memoria antes de que esos resultados se limpien
• Mantener flujos de trabajo de larga duración: Habilitar flujos de trabajo agentes que de otro modo excederían los límites de contexto descargando información en almacenamiento persistente
• Acceder a información bajo demanda: Claude puede buscar información previamente limpiada de los 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 en archivos de memoria a medida que crece el contexto. Cuando se limpian los resultados de herramientas, Claude retiene acceso a esa información a través de su sistema de memoria y puede continuar trabajando de manera efectiva.

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

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}]},
)

Para la referencia completa de la herramienta de memoria incluyendo comandos y ejemplos, consulta Herramienta de memoria.

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 limpian 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 solicitud 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 donde lo dejó.

Uso de compactación

Agrega compaction_control a tu llamada tool_runner para habilitar la sumarización automática cuando el uso de tokens exceda el umbral.

Qué sucede durante la compactación

A medida que crece la conversación, 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 riesgo de 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.""",
}

Mensaje de resumen predeterminado

El mensaje de resumen integrado instruye a Claude para crear un resumen de continuación estructurado incluyendo:

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 o repetir errores.

Limitaciones

Herramientas del lado del servidor

Cuando se usan 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 de API internas 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 el SDK activa la compactación mientras una respuesta de uso de herramientas está pendiente, 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

Entender cuándo se activa la compactación te ayuda a ajustar umbrales y verificar el comportamiento esperado.

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, reportes) 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 a través de muchas variables