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 brinda un control detallado en tiempo de ejecución sobre esa curación. Para conocer los principios más amplios detrás de la gestión del contexto, consulta Ingeniería de contexto efectiva. Esta página cubre:

• Borrado de resultados de herramientas - Ideal para flujos de trabajo agénticos con uso intensivo de herramientas donde los resultados antiguos ya no son necesarios
• Borrado de bloques de pensamiento - Para gestionar bloques de pensamiento cuando se usa el pensamiento extendido, con opciones para preservar el pensamiento reciente para la continuidad del contexto
• Compactación del lado del cliente con SDK - Una alternativa basada en SDK para la gestión de contexto basada en resúmenes (generalmente se prefiere la compactación del lado del servidor)

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 supera el umbral configurado. Esto es particularmente útil para flujos de trabajo agénticos 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. Cada resultado borrado se reemplaza con texto de marcador de posición para que Claude sepa que fue eliminado. Por defecto, solo se borran los resultados de herramientas. Opcionalmente, puedes borrar tanto los resultados de herramientas como las llamadas a herramientas (los parámetros de uso de herramientas) configurando clear_tool_inputs en true.

Borrado de bloques de pensamiento

La estrategia clear_thinking_20251015 gestiona los bloques thinking en las 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 de forma más agresiva 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 prompt llegue a Claude. Tu aplicación cliente mantiene el historial completo y sin modificar de la conversación. No necesitas sincronizar el estado de tu cliente con la versión editada. Continúa gestionando tu historial completo de conversación localmente como lo harías normalmente.

Edición de contexto y caché de prompts

La interacción de la edición de contexto con el caché de prompts varía según la estrategia:

• Borrado de resultados de herramientas: Invalida los prefijos de prompts en caché cuando se borra contenido. Para tener esto en cuenta, borra suficientes tokens para que la invalidación del caché valga la pena. Usa el parámetro clear_at_least para garantizar 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 se mantienen en el contexto (no se borran), el caché de prompts se preserva, lo que permite aciertos de caché y reduce los costos de tokens de entrada. Cuando los bloques de pensamiento se borran, el caché se invalida en el punto donde ocurre el borrado. Configura el parámetro keep según si deseas priorizar el rendimiento del caché o la disponibilidad de la ventana de contexto.

Modelos compatibles

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.6 (claude-sonnet-4-6)
• 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 sencilla de habilitar el borrado de resultados de herramientas es especificar solo el tipo de estrategia. Todas las demás opciones de configuración usan sus valores predeterminados:

Configuración avanzada

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

Uso del borrado de bloques de pensamiento

Habilita el borrado de bloques de pensamiento para gestionar el contexto y el caché de prompts de manera efectiva cuando el pensamiento extendido está habilitado:

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

La estrategia clear_thinking_20251015 admite la siguiente configuración:

Configuraciones de ejemplo:

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

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

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

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

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": [
      // Al usar `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // Al usar `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

Para respuestas en streaming, 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, lo que te permite previsualizar cuántos tokens usará tu prompt después de aplicar la edición de contexto.

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

La respuesta muestra tanto el recuento final de tokens después de aplicar la gestión de contexto (input_tokens) como el recuento original de tokens antes de que ocurriera cualquier borrado (original_input_tokens).

Uso con la herramienta de memoria

La edición de contexto puede combinarse 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 a Claude guardar resultados de herramientas o contexto en sus archivos de memoria antes de que sean borrados 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 sean borrados
• Mantener flujos de trabajo de larga duración: Habilitar flujos de trabajo agénticos que de otro modo superarían los límites de contexto descargando información en almacenamiento persistente
• Acceder a información bajo demanda: Claude puede buscar información previamente borrada en 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 los cambios completados en archivos de memoria a medida que crece el contexto. Cuando se borran los resultados de herramientas, Claude mantiene acceso a esa información a través de su sistema de memoria y puede continuar trabajando de manera efectiva.

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

Compactación del lado del cliente (SDK)

La compactación es una función 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 a resumir el historial de conversación y luego reemplaza el historial completo con ese resumen. Esto permite a Claude continuar trabajando en tareas de larga duración que de otro modo superarí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 del umbral: El SDK calcula el total de tokens como input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens.
2. Generación del resumen: Cuando se supera el umbral, se inyecta un prompt de resumen como turno de usuario, y Claude genera un resumen estructurado envuelto en etiquetas <summary></summary>.
3. Reemplazo del 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 retomando donde lo dejó.

Uso de la compactación

Agrega compaction_control a tu llamada tool_runner:

Qué ocurre 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 intercambios más como este ...
]

Cuando los tokens superan 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 original de la conversación.

Opciones de configuración

Elección de 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 los límites.

# Compactación más frecuente para escenarios con restricciones de memoria
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# Compactación menos frecuente cuando necesitas más contexto
compaction_control = {"enabled": True, "context_token_threshold": 150000}

Uso de un modelo diferente para los resúmenes

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

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

Prompts de resumen personalizados

Puedes proporcionar un prompt personalizado para necesidades específicas del dominio. Tu prompt debe instruir a Claude a 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.""",
}

Prompt de resumen predeterminado

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

1. Descripción general de la tarea: La solicitud principal del usuario, los criterios de éxito y las restricciones.
2. Estado actual: Lo que se ha completado, los archivos modificados y los 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 adquiridos.

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

Limitaciones

Herramientas del lado del servidor

Cuando se utilizan herramientas del lado del servidor, el SDK puede calcular incorrectamente el uso de tokens, lo que provoca que la compactación se active en el momento equivocado.

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 de cache_read_input_tokens incluye lecturas acumuladas de múltiples llamadas internas a la API realizadas por la herramienta del lado del servidor, no el contexto real de tu conversación. La longitud real de tu contexto podría ser solo los 63.000 input_tokens, pero el SDK ve 333k y activa la compactación de forma prematura.

Soluciones alternativas:

• Usa el endpoint de conteo de tokens para obtener la longitud de contexto precisa
• Evita la compactación cuando uses herramientas del lado del servidor de forma extensiva

Casos extremos en el uso de herramientas

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

Monitoreo de la 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 la compactación

Casos de uso ideales:

• 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 un recuerdo preciso de los detalles de conversaciones anteriores
• Flujos de trabajo que utilizan herramientas del lado del servidor de forma extensiva
• Tareas que necesitan mantener un estado exacto a través de muchas variables