Edición de contexto



Descripción general

La edición de contexto te permite eliminar selectivamente contenido específico del historial de conversación a medida que crece. Más allá de optimizar costos y mantenerte 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 de contexto, consulta Effective context engineering. Esta página cubre:

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



Estrategias del lado del servidor



Eliminación de resultados de herramientas

La estrategia clear_tool_uses_20250919 elimina los resultados de herramientas cuando el contexto de la conversación crece más allá del umbral que hayas configurado. Esto es particularmente útil para flujos de trabajo agénticos con uso intensivo de 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 elimina automáticamente los resultados de herramientas más antiguos en orden cronológico. La API reemplaza cada resultado eliminado con texto de marcador de posición para que Claude sepa que fue eliminado. De forma predeterminada, solo se eliminan los resultados de herramientas. Opcionalmente, puedes eliminar tanto los resultados de herramientas como las llamadas a herramientas (los parámetros de uso de herramientas) estableciendo clear_tool_inputs en true.



Eliminación 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 conservar más bloques de pensamiento para mantener la continuidad del razonamiento, o eliminarlos 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, al usar 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 de conversación completo y 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 prompts

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

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

• Eliminación de bloques de pensamiento: Cuando los bloques de pensamiento se conservan en el contexto (no se eliminan), la 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 eliminan, la caché se invalida en el punto donde ocurre la eliminación. Configura el parámetro keep según si deseas priorizar el rendimiento de la caché o la disponibilidad de la ventana de contexto.



Modelos compatibles

La edición de contexto está disponible en todos los modelos de Claude compatibles.



Uso de la eliminación de resultados de herramientas

La forma más sencilla de habilitar la eliminación de resultados de herramientas es especificar solo el tipo de estrategia. Todas las demás opciones de configuración usan sus valores predeterminados:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 de eliminación de resultados de herramientas con parámetros adicionales:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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",
                # Activa la limpieza cuando se supera el umbral
                "trigger": {"type": "input_tokens", "value": 30000},
                # Número de usos de herramientas a conservar tras la limpieza
                "keep": {"type": "tool_uses", "value": 3},
                # Opcional: limpia al menos esta cantidad de tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Excluye estas herramientas de la limpieza
                "exclude_tools": ["web_search"],
            }
        ]
    },
)



Uso de la eliminación de bloques de pensamiento

Habilita la eliminación de bloques de pensamiento para gestionar el contexto y el almacenamiento en caché de prompts de manera efectiva cuando el pensamiento extendido está habilitado:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    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 eliminación 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:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)



Combinación de estrategias

Puedes usar la eliminación de bloques de pensamiento y la eliminación de resultados de herramientas juntas:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    thinking={"type": "adaptive"},
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    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},
            },
        ]
    },
)

print(response)



Opciones de configuración para la eliminación 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 eliminados.

{
  "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 en streaming, las ediciones de contexto se incluyen 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.

response = client.beta.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    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 final de tokens después de aplicar la gestión de contexto (input_tokens) como el conteo original de tokens antes de que ocurriera cualquier eliminación (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 eliminación 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 eliminen 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 eliminen
• Mantener flujos de trabajo de larga duración: Habilitar flujos de trabajo agénticos que de otro modo excederían los límites de contexto al descargar información en almacenamiento persistente
• Acceder a información bajo demanda: Claude puede buscar información previamente eliminada en 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 los cambios completados en archivos de memoria a medida que el contexto crece. Cuando se eliminan los resultados de herramientas, Claude conserva el 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 a la API:

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

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



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 eliminan contenido, la compactación instruye a Claude para que resuma el historial de conversación y 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 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 un 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, y Claude retoma donde lo dejó.



Uso de la compactación

Agrega compaction_control a tu llamada de tool_runner para habilitar el resumen automático cuando el uso de tokens supere el umbral.



Qué ocurre 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 superan el umbral, el SDK inyecta una solicitud de resumen y Claude genera un resumen. Luego se reemplaza todo el historial:

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 corre el riesgo de alcanzar los límites.



Usar un modelo diferente para los resúmenes

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



Prompts de resumen personalizados

Puedes proporcionar un prompt personalizado para necesidades específicas de dominio. Tu prompt debe instruir a Claude para que envuelva su resumen en etiquetas <summary></summary>.



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, 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, bloqueos y orden de prioridad.
5. Contexto a preservar: Preferencias del usuario, detalles específicos del dominio y compromisos adquiridos.

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, 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_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

El SDK calcula el uso total como 63,000 + 0 + 270,000 + 1,400 = 334,400 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 334k y activa la compactación prematuramente.

Soluciones alternativas:

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



Casos límite del 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 a la herramienta después de reanudar desde el resumen si aún es necesaria.



Monitoreo de la compactación

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



Cuándo usar la compactación

Buenos casos de uso:

• 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 recordar con precisión detalles tempranos de la conversación
• Flujos de trabajo que usan herramientas del lado del servidor de forma intensiva
• Tareas que necesitan mantener un estado exacto a través de muchas variables



Próximos pasos