Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
La edición de contexto te permite administrar 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. Puedes usar estrategias de API del lado del servidor, características del SDK del lado del cliente, o ambas juntas.
| Enfoque | Dónde se ejecuta | Estrategias | Cómo funciona |
|---|---|---|---|
| Lado del servidor | API | Limpieza de resultados de herramientas (clear_tool_uses_20250919)Limpieza de bloques de pensamiento ( clear_thinking_20251015) | Se aplica antes de que el mensaje llegue a Claude. Limpia contenido específico del historial de conversación. Cada estrategia se puede configurar de forma independiente. |
| Lado del cliente | SDK | Compactación | Disponible en SDKs de Python y TypeScript cuando se usa tool_runner. Genera un resumen y reemplaza el historial completo de conversación. Ver Compactación abajo. |
La edición de contexto te permite administrar 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. Puedes usar estrategias de API del lado del servidor, características del SDK del lado del cliente, o ambas juntas.
| Enfoque | Dónde se ejecuta | Estrategias | Cómo funciona |
|---|---|---|---|
| Lado del servidor | API | Limpieza de resultados de herramientas (clear_tool_uses_20250919)Limpieza de bloques de pensamiento ( clear_thinking_20251015) | Se aplica antes de que el mensaje llegue a Claude. Limpia contenido específico del historial de conversación. Cada estrategia se puede configurar de forma independiente. |
| Lado del cliente | SDK | Compactación | Disponible en SDKs de Python y TypeScript cuando se usa tool_runner. Genera un resumen y reemplaza el historial completo de conversación. Ver Compactación abajo. |
La edición de contexto está actualmente en beta con soporte para limpieza de resultados de herramientas y limpieza de bloques de pensamiento. Para habilitarla, usa 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.
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 verdadero.
La estrategia clear_thinking_20251015 administra 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 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 completo y sin modificar de la conversación—no necesitas sincronizar el estado de tu cliente con la versión editada. Continúa administrando tu historial completo de conversación 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:
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 del 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 prefijo recién almacenado en caché.
Limpieza de bloques de pensamiento: Cuando los bloques de pensamiento están mantenidos en contexto (no limpios), el caché de mensajes se preserva, habilitando aciertos de caché y reduciendo costos de tokens de entrada. Cuando los bloques de pensamiento están limpios, el caché se invalida en el punto donde ocurre la limpieza. Configura el parámetro keep basándote en si deseas priorizar el rendimiento del caché o la disponibilidad de la ventana de contexto.
La edición de contexto está disponible en:
claude-opus-4-5-20251101)claude-opus-4-1-20250805)claude-opus-4-20250514)claude-sonnet-4-5-20250929)claude-sonnet-4-20250514)claude-haiku-4-5-20251001)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"}
]
}
}'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"]
}
]
}
}'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. Puedes usar estrategias de API del lado del servidor, características del SDK del lado del cliente, o ambas juntas.
| Enfoque | Dónde se ejecuta | Estrategias | Cómo funciona |
|---|---|---|---|
| Lado del servidor | API | Limpieza de resultados de herramientas (clear_tool_uses_20250919)Limpieza de bloques de pensamiento ( clear_thinking_20251015) | Se aplica antes de que el mensaje llegue a Claude. Limpia contenido específico del historial de conversación. Cada estrategia se puede configurar de forma independiente. |
| Lado del cliente | SDK | Compactación | Disponible en SDKs de Python y TypeScript cuando se usa tool_runner. Genera un resumen y reemplaza el historial completo de conversación. Ver Compactación abajo. |
La edición de contexto está actualmente en beta con soporte para limpieza de resultados de herramientas y limpieza de bloques de pensamiento. Para habilitarla, usa 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 tu retroalimentación sobre esta función.
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) estableciendo clear_tool_inputs en true.
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 estableciendo 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 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 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 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:
Limpieza de resultados de herramientas: Invalida los prefijos de mensaje en caché cuando se limpia contenido. Para tener esto en cuenta, recomendamos limpiar suficientes tokens para que la invalidación del 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 prefijo recién almacenado en caché.
Limpieza de bloques de pensamiento: Cuando los bloques de pensamiento se mantienen en contexto (no se limpian), el caché de mensaje 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 del caché o la disponibilidad de la ventana de contexto.
La edición de contexto está disponible en:
claude-opus-4-5-20251101)claude-opus-4-1-20250805)claude-opus-4-20250514)claude-sonnet-4-5-20250929)claude-sonnet-4-20250514)claude-haiku-4-5-20251001)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"}
]
}
}'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"]
}
]
}
}'Habilita la limpieza de bloques de pensamiento para gestionar el contexto y el almacenamiento en caché de mensajes de manera 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
}
}
]
}
}'La estrategia clear_thinking_20251015 soporta la siguiente configuración:
| Opción de configuración | Predeterminado | Descripció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"
}La estrategia clear_thinking_20251015 soporta la siguiente configuración:
| Opción de configuración | Predeterminado | Descripció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"
}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
}
}
]
}
)La estrategia clear_thinking_20251015 soporta la siguiente configuración:
| Opción de configuración | Predeterminado | Descripció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"
}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
}
}
]
}
)| Opción de configuración | Predeterminado | Descripción |
|---|---|---|
trigger | 100,000 tokens de entrada | Define cuándo se activa la estrategia de edición de contexto. Una vez que el mensaje excede este umbral, comenzará la limpieza. Puedes especificar este valor en input_tokens o tool_uses. |
keep | 3 usos de herramientas | Define 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_least | Ninguno | Asegura 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 la limpieza de contexto vale la pena romper tu caché de mensaje. |
exclude_tools | Ninguno | Lista de nombres de herramientas cuyos usos y resultados nunca deben ser limpiados. Útil para preservar contexto importante. |
clear_tool_inputs | false | Controla 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. |
La estrategia clear_thinking_20251015 soporta la siguiente configuración:
| Opción de configuración | Predeterminado | Descripció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"
}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
}
}
]
}
)| Opción de configuración | Predeterminado | Descripción |
|---|---|---|
trigger | 100,000 tokens de entrada | Define cuándo se activa la estrategia de edición de contexto. Una vez que el mensaje excede este umbral, comenzará la limpieza. Puedes especificar este valor en input_tokens o tool_uses. |
keep | 3 usos de herramientas | Define 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_least | Ninguno | Asegura 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 la limpieza de contexto vale la pena romper tu caché de mensaje. |
exclude_tools | Ninguno | Lista de nombres de herramientas cuyos usos y resultados nunca deben ser limpiados. Útil para preservar contexto importante. |
clear_tool_inputs | false | Controla 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. |
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": [...]
}
}La estrategia clear_thinking_20251015 admite la siguiente configuración:
| Opción de configuración | Predeterminado | Descripción |
|---|---|---|
keep | {type: "thinking_turns", value: 1} | Define cuántos turnos recientes del asistente con bloques de pensamiento se deben preservar. Use {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 los aciertos de caché)
{
"type": "clear_thinking_20251015",
"keep": "all"
}Puede usar tanto la limpieza de bloques de pensamiento como la limpieza de resultados de herramientas juntas:
Cuando use múltiples estrategias, la estrategia clear_thinking_20251015 debe aparecer 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
}
}
]
}
)| Opción de configuración | Predeterminado | Descripción |
|---|---|---|
trigger | 100,000 tokens de entrada | Define cuándo se activa la estrategia de edición de contexto. Una vez que el prompt excede este umbral, comenzará la limpieza. Puede especificar este valor en input_tokens o tool_uses. |
keep | 3 usos de herramientas | Define 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_least | Ninguno | Asegura 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 limpiar el contexto para romper su caché de prompt. |
exclude_tools | Ninguno | Lista de nombres de herramientas cuyos usos y resultados nunca deben ser limpiados. Útil para preservar contexto importante. |
clear_tool_inputs | false | Controla 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 originales de Claude. |
Puede ver qué ediciones de contexto se aplicaron a su 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": [
// 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:
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"stop_sequence": null
},
"usage": {
"output_tokens": 1024
},
"context_management": {
"applied_edits": [...]
}
}El endpoint de conteo de tokens admite gestión de contexto, permitiéndole obtener una vista previa de cuántos tokens usará su prompt 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
}
}
]
}
}'{
"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).
La edición de contexto se puede combinar con la herramienta de memoria. Cuando el contexto de su 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 le permite:
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ítelas en su 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"}
]
}
)La compactación está disponible en los SDK de Python y TypeScript cuando se usa el método tool_runner.
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.
Cuando la compactación está habilitada, el SDK monitorea el uso de tokens después de cada respuesta del modelo:
input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens<summary></summary>Agregue compaction_control a su llamada tool_runner:
import anthropic
client = anthropic.Anthropic()
runner = client.beta.messages.tool_runner(
model="claude-sonnet-4-5",
max_tokens=4096,
tools=[...],
messages=[
{
"role": "user",
"content": "Analyze all the files in this directory and write a summary report."
}
],
compaction_control={
"enabled": True,
"context_token_threshold": 100000
}
)
for message in runner:
print(f"Tokens used: {message.usage.input_tokens}")
final = runner.until_done()A medida que crece la conversación, el historial de mensajes se acumula:
Antes de la compactación (aproximá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.
| Parámetro | Tipo | Requerido | Predeterminado | Descripción |
|---|---|---|---|---|
enabled | boolean | Sí | - | Si se debe habilitar la compactación automática |
context_token_threshold | number | No | 100,000 | Conteo de tokens en el cual se activa la compactación |
model | string | No | Mismo que el modelo principal | Modelo a usar para generar resúmenes |
summary_prompt | string | No | Ver abajo | Prompt personalizado para generación de resumen |
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 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
}Puede 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"
}Puede proporcionar un prompt personalizado para necesidades específicas del dominio. Su prompt 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."""
}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 borren del historial de conversación.
Esta combinación te permite:
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 borran 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-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"}
]
}
)La compactación está disponible en los SDK de Python y TypeScript cuando se usa el método tool_runner.
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 borran contenido, la compactación instruye a Claude para que resuma 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.
Cuando la compactación está habilitada, el SDK monitorea el uso de tokens después de cada respuesta del modelo:
input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens<summary></summary>Agrega compaction_control a tu llamada tool_runner:
import anthropic
client = anthropic.Anthropic()
runner = client.beta.messages.tool_runner(
model="claude-sonnet-4-5",
max_tokens=4096,
tools=[...],
messages=[
{
"role": "user",
"content": "Analyze all the files in this directory and write a summary report."
}
],
compaction_control={
"enabled": True,
"context_token_threshold": 100000
}
)
for message in runner:
print(f"Tokens used: {message.usage.input_tokens}")
final = runner.until_done()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. Luego se reemplaza todo el historial:
Después de la compactación (volviendo 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.
| Parámetro | Tipo | Requerido | Predeterminado | Descripción |
|---|---|---|---|---|
enabled | boolean | Sí | - | Si se habilita la compactación automática |
context_token_threshold | number | No | 100,000 | Cantidad de tokens en la que se activa la compactación |
model | string | No | Mismo que el modelo principal | Modelo a usar para generar resúmenes |
summary_prompt | string | No | Ver abajo | Mensaje personalizado para la generación de resumen |
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
}Puedes usar un modelo más rápido o más económico para generar resúmenes:
compaction_control={
"enabled": True,
"context_token_threshold": 100000,
"model": "claude-haiku-4-5"
}Puedes proporcionar un mensaje personalizado para necesidades específicas del dominio. Tu mensaje debe instruir a Claude para que envuelva 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."""
}El mensaje de resumen integrado instruye a Claude para crear un resumen de continuación estructurado que incluya:
Esta estructura permite que Claude reanude el trabajo de manera eficiente sin perder contexto importante o repetir errores.
La compactación requiere consideración especial cuando se usan herramientas del lado del servidor como búsqueda web o búsqueda web.
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 internas de API 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:
Cuando la compactación se activa mientras una respuesta de uso de herramienta está 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 de herramienta después de reanudar desde el resumen si aún es necesario.
La compactación requiere consideración especial cuando se usan herramientas del lado del servidor como búsqueda web o búsqueda web.
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 internas de API 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:
Cuando la compactación se activa mientras una respuesta de uso de herramienta está 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 de herramienta después de reanudar desde el resumen si aún es necesario.
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)
# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500La compactación requiere consideración especial cuando se usan herramientas del lado del servidor como búsqueda web o búsqueda web.
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 internas de API 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:
Cuando la compactación se activa mientras una respuesta de uso de herramienta está 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 de herramienta después de reanudar desde el resumen si aún es necesario.
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)
# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500Casos de uso adecuados:
Casos de uso menos ideales: