Edición de contexto

Descripción general

La "context editing" (edición de contexto) te permite eliminar selectivamente contenido específico del historial de la 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 da 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:

• Eliminación de resultados de herramientas - Ideal para flujos de trabajo agénticos con un uso de herramientas intensivo donde los resultados de herramientas antiguos ya no son necesarios
• Eliminación de bloques de pensamiento - Para gestionar bloques de pensamiento al usar "extended thinking" (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 el 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

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 configuraste. Esto es particularmente útil para flujos de trabajo agénticos con un uso de herramientas intensivo. 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 elimina automáticamente los resultados de herramientas más antiguos en orden cronológico. La API reemplaza cada resultado eliminado con un texto de marcador de posición que le indica a Claude 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 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 la conversación localmente como lo harías normalmente.

En Claude Fable 5.1, la gestión de contexto del lado del servidor nunca invalida los bloques de pensamiento. Las ediciones del lado del cliente a turnos anteriores pueden invalidar los bloques de pensamiento en cada turno posterior del asistente. Para las cuentas nuevas creadas a partir del 31 de agosto de 2026, una solicitud que reproduce un bloque invalidado se rechaza a menos que optes por descartarlo. Consulta Pensamiento preservado.

Edición de contexto y almacenamiento en caché de prompts

La interacción de la edición de contexto con el "prompt caching" (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 tener esto en cuenta, elimina suficientes tokens para que la invalidación de la caché valga la pena. Usa el parámetro clear_at_least para garantizar 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 nuevo prefijo 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 quieres 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-5",
    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 la eliminación de resultados de herramientas con parámetros adicionales:

response = client.beta.messages.create(
    model="claude-opus-5",
    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",
                # Activar la limpieza cuando se supere 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: limpiar al menos esta cantidad de tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Excluir 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 forma efectiva cuando el pensamiento extendido está habilitado:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    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-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    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-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    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-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    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 la 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 las 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 que se aplique la edición de contexto.

response = client.beta.messages.count_tokens(
    model="claude-opus-5",
    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 se puede combinar 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 la 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 la 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: Habilita flujos de trabajo agénticos que de otro modo superarían los límites de contexto al trasladar información a un almacenamiento persistente
• Acceder a la información bajo demanda: Claude puede buscar información previamente eliminada en los archivos de memoria cuando la necesite, 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 seguir trabajando de forma efectiva.

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

response = client.beta.messages.create(
    model="claude-opus-5",
    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 "compaction" (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 le indica a Claude que resuma el historial de la conversación y luego reemplaza el historial completo con ese resumen. Esto permite que Claude siga 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 (consulta Almacenamiento en caché de prompts para los campos de tokens de caché).
2. Generación del resumen: Cuando se supera el umbral, se inyecta un prompt de resumen como turno del 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 a 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 sigue trabajando a partir de 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 corre el riesgo de alcanzar los límites.

Uso de 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 un dominio. Tu prompt debe indicarle a Claude que envuelva su resumen en etiquetas <summary></summary>.

Prompt de resumen predeterminado

El prompt de resumen integrado le indica a Claude que cree un resumen de continuación estructurado que incluya:

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

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

You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:

1. Task Overview
The user's core request and success criteria
Any clarifications or constraints they specified

2. Current State
What has been completed so far
Files created, modified, or analyzed (with paths if relevant)
Key outputs or artifacts produced

3. Important Discoveries
Technical constraints or requirements uncovered
Decisions made and their rationale
Errors encountered and how they were resolved
What approaches were tried that didn't work (and why)

4. Next Steps
Specific actions needed to complete the task
Any blockers or open questions to resolve
Priority order if multiple steps remain

5. Context to Preserve
User preferences or style requirements
Domain-specific details that aren't obvious
Any promises made to the user

Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.

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

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 extensiva

Casos límite del uso de herramientas

Cuando el SDK activa la compactación mientras hay una respuesta de uso de herramientas 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

Entender 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 agentes 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 varios pasos con un 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 extensiva
• Tareas que necesitan mantener un estado exacto a través de muchas variables

Próximos pasos