La edición de contexto está actualmente en beta con soporte para la limpieza de resultados de herramientas y la limpieza de bloques de pensamiento. Para habilitarla, utiliza el encabezado beta context-management-2025-06-27 en tus solicitudes de API.Por favor, comunícate a través de nuestro formulario de comentarios para compartir tus comentarios sobre esta función.

​
Descripción general

La edición de contexto te permite gestionar automáticamente el contexto de la conversación a medida que crece, ayudándote a optimizar costos y mantenerte dentro de los límites de la ventana de contexto. La API proporciona diferentes estrategias para gestionar el contexto:
  • Limpieza de resultados de herramientas (clear_tool_uses_20250919): Limpia automáticamente los pares de uso/resultado de herramientas cuando el contexto de la conversación excede tu umbral configurado
  • Limpieza de bloques de pensamiento (clear_thinking_20251015): Gestiona bloques de pensamiento limpiando bloques de pensamiento más antiguos de turnos anteriores
Cada estrategia se puede configurar de forma independiente y aplicar conjuntamente para optimizar tu caso de uso específico.

​
Estrategias de edición de contexto

​
Limpieza de resultados de herramientas

La estrategia clear_tool_uses_20250919 limpia los resultados de herramientas cuando el contexto de la conversación crece más allá de tu umbral configurado. Cuando se activa, la API limpia automáticamente los resultados de herramientas más antiguos en orden cronológico, reemplazándolos con texto de marcador de posición para que Claude sepa que el resultado de la herramienta fue eliminado. Por defecto, solo se limpian los resultados de herramientas. Opcionalmente, puedes limpiar tanto los resultados de herramientas como las llamadas de herramientas (los parámetros de uso de herramientas) configurando clear_tool_inputs en true.

​
Limpieza de bloques de pensamiento

La estrategia clear_thinking_20251015 gestiona bloques thinking en conversaciones cuando el pensamiento extendido está habilitado. Esta estrategia limpia automáticamente los bloques de pensamiento más antiguos de turnos anteriores.
Comportamiento predeterminado: Cuando el pensamiento extendido está habilitado sin configurar la estrategia clear_thinking_20251015, la API mantiene automáticamente solo los bloques de pensamiento del último turno del asistente (equivalente a keep: {type: "thinking_turns", value: 1}).Para maximizar los aciertos de caché, preserva todos los bloques de pensamiento configurando keep: "all".
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 servidorLa 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 mensajesLa interacción de la edición de contexto con almacenamiento en caché de mensajes varía según la estrategia:
  • Limpieza de resultados de herramientas: Invalida los prefijos de mensajes en caché cuando se limpia contenido. Para tener esto en cuenta, recomendamos limpiar suficientes tokens para que la invalidación de caché valga la pena. Usa el parámetro clear_at_least para asegurar que se limpie un número mínimo de tokens cada vez. Incurrirás en costos de escritura de caché cada vez que se limpie contenido, pero las solicitudes posteriores pueden reutilizar el nuevo prefijo en caché.
  • Limpieza de bloques de pensamiento: Cuando los bloques de pensamiento se mantienen en contexto (no se limpian), el caché de mensajes se preserva, habilitando aciertos de caché y reduciendo costos de tokens de entrada. Cuando los bloques de pensamiento se limpian, el caché se invalida en el punto donde ocurre la limpieza. Configura el parámetro keep según si deseas priorizar el rendimiento de caché o la disponibilidad de la ventana de contexto.

​
Modelos compatibles

La edición de contexto está disponible en:
  • 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 de limpieza de resultados de herramientas

La forma más simple de habilitar la limpieza de resultados de herramientas es especificar solo el tipo de estrategia, ya que todas las otras opciones de configuración usarán 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-sonnet-4-5",
        "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 de limpieza 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-sonnet-4-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
            }
        ],
        "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 de limpieza de bloques de pensamiento

Habilita la limpieza 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-sonnet-4-5-20250929",
        "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 limpieza de bloques de pensamiento

La estrategia clear_thinking_20251015 admite la siguiente configuración:
Opción de configuraciónPredeterminadoDescripción
keep{type: "thinking_turns", value: 1}Define cuántos turnos recientes del asistente con bloques de pensamiento se deben preservar. Usa {type: "thinking_turns", value: N} donde N debe ser > 0 para mantener los últimos N turnos, o "all" para mantener todos los bloques de pensamiento.
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 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:
Cuando uses múltiples estrategias, la estrategia clear_thinking_20251015 debe estar listada primero en el array edits.
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 limpieza de resultados de herramientas

Opción de configuraciónPredeterminadoDescripción
trigger100,000 tokens de entradaDefine cuándo se activa la estrategia de edición de contexto. Una vez que el mensaje excede este umbral, la limpieza comenzará. Puedes especificar este valor en input_tokens o tool_uses.
keep3 usos de herramientasDefine cuántos pares recientes de uso/resultado de herramientas se deben mantener después de que ocurra la limpieza. La API elimina primero las interacciones de herramientas más antiguas, preservando las más recientes.
clear_at_leastNingunoAsegura que se limpie un número mínimo de tokens cada vez que se activa la estrategia. Si la API no puede limpiar al menos la cantidad especificada, la estrategia no se aplicará. Esto ayuda a determinar si vale la pena romper tu caché de mensajes.
exclude_toolsNingunoLista de nombres de herramientas cuyos usos y resultados nunca deben ser limpiados. Útil para preservar contexto importante.
clear_tool_inputsfalseControla si los parámetros de llamada de herramientas se limpian junto con los resultados de herramientas. Por defecto, solo se limpian los resultados de herramientas mientras se mantienen visibles las llamadas de herramientas originales de Claude.

​
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.
Respuesta
{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    "usage": {...},
    "context_management": {
        "applied_edits": [
            // Cuando se usa `clear_thinking_20251015`
            {
                "type": "clear_thinking_20251015",
                "cleared_thinking_turns": 3,
                "cleared_input_tokens": 15000
            },
            // Cuando se usa `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:
Respuesta de transmisión
{
    "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 gestión de contexto, permitiéndote obtener una vista previa de 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-sonnet-4-5",
        "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
                    }
                }
            ]
        }
    }'
Respuesta
{
    "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 resultados de herramientas en archivos de memoria antes de que esos resultados se limpien
  • Mantener flujos de trabajo de larga duración: Habilita flujos de trabajo de 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 limpiada 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 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 forma efectiva. Para usar ambas funciones juntas, habilítalas en tu solicitud de API: 
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    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"}
        ]
    }
)