Ventanas de contexto

A medida que las conversaciones crecen, eventualmente te acercarás a los límites de la ventana de contexto. Para conversaciones de larga duración y flujos de trabajo agénticos, la compactación del lado del servidor es la estrategia principal para la gestión del contexto.

Cómo funciona la ventana de contexto

La "context window" (ventana de contexto) se refiere a todo el texto que un modelo de lenguaje puede referenciar al generar una respuesta, incluida la respuesta misma. Esto es diferente del gran corpus de datos con el que se entrenó el modelo de lenguaje, y en su lugar representa una "memoria de trabajo" para el modelo. Una ventana de contexto más grande permite que el modelo maneje prompts más complejos y extensos, pero más contexto no es automáticamente mejor. A medida que crece el recuento de tokens, la precisión y la capacidad de recuperación se degradan, un fenómeno conocido como context rot (deterioro del contexto). Esto hace que seleccionar cuidadosamente lo que está en el contexto sea tan importante como cuánto espacio hay disponible.

El siguiente diagrama ilustra el comportamiento estándar de la ventana de contexto para solicitudes de API¹:

¹ Las interfaces de chat como claude.ai también pueden gestionar la ventana de contexto de forma continua bajo el principio de "primero en entrar, primero en salir".

• Acumulación progresiva de tokens: A medida que la conversación avanza a través de los turnos, cada mensaje del usuario y cada respuesta del asistente se acumulan dentro de la ventana de contexto, y los turnos anteriores se conservan por completo.
• Capacidad de la ventana de contexto: La ventana de contexto (hasta 1M de tokens, según el modelo) contiene el historial de la conversación más la nueva salida que Claude genera.
• Flujo de entrada-salida: Cada turno consiste en:
  • Fase de entrada: Contiene todo el historial previo de la conversación más el mensaje actual del usuario
  • Fase de salida: Genera una respuesta de texto que se convierte en parte de la entrada para el siguiente turno

Todo lo que hay en la solicitud cuenta para la ventana de contexto: la indicación del sistema, cada mensaje en messages (incluidos los resultados de herramientas, imágenes y documentos) y tus definiciones de herramientas. La salida que Claude genera para el turno, incluido su pensamiento extendido, también cuenta. Cada respuesta informa lo que consumió la solicitud en su campo usage. Si usas almacenamiento en caché de prompts, el recuento de entrada se divide entre input_tokens, cache_read_input_tokens y cache_creation_input_tokens, y los tres cuentan para la ventana. Para estimar una solicitud antes de enviarla, usa la API de conteo de tokens.

Tamaños de ventana de contexto por modelo

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6 y Claude Mythos Preview tienen una ventana de contexto de 1M de tokens. Una sola solicitud a cualquiera de ellos puede generar hasta 128k tokens de salida (max_tokens). Otros modelos Claude, incluido Claude Sonnet 4.5, tienen una ventana de contexto de 200k tokens.

Para cada modelo con una ventana de contexto de 1M de tokens, 1M es el valor predeterminado: no necesitas un encabezado beta, y las solicitudes de contexto largo se facturan según los precios estándar.

Una sola solicitud puede incluir hasta 600 imágenes o páginas de PDF (100 para modelos con una ventana de contexto de 200k tokens). Si envías muchas imágenes o documentos grandes, podrías alcanzar los límites de tamaño de solicitud antes del límite de tokens.

Consulta la tabla de comparación de modelos para ver una lista de tamaños de ventana de contexto por modelo.

La ventana de contexto con pensamiento

Con el pensamiento, todos los tokens de entrada y salida, incluidos los tokens de pensamiento, cuentan para el límite de la ventana de contexto, con algunos matices en situaciones de múltiples turnos.

Los tokens de pensamiento son un subconjunto de tu parámetro max_tokens, se facturan como tokens de salida y cuentan para los límites de velocidad. Con el pensamiento adaptativo, Claude determina su asignación de pensamiento de forma dinámica, por lo que el uso de tokens de pensamiento varía de una solicitud a otra.

Que los bloques de pensamiento de turnos anteriores del asistente permanezcan en la ventana de contexto depende del modelo. En Claude Opus 4.5 y modelos Opus posteriores, Claude Sonnet 4.6 y modelos Sonnet posteriores, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 y Claude Mythos Preview, la API conserva los bloques de pensamiento anteriores de forma predeterminada, y cuentan para la ventana de contexto como cualquier otro token de entrada. En modelos Opus y Sonnet anteriores y en todos los modelos Haiku, la API elimina automáticamente los bloques de pensamiento anteriores del historial de la conversación cuando los devuelves, lo que preserva la capacidad de tokens para el contenido de la conversación. Para los valores predeterminados por modelo, consulta conservación de bloques de pensamiento por modelo. Para anular el valor predeterminado en cualquier dirección, usa la limpieza de bloques de pensamiento.

El siguiente diagrama muestra cómo se gestionan los tokens cuando el pensamiento está habilitado en un modelo que elimina los bloques de pensamiento anteriores:

• Eliminación de bloques de pensamiento: En los modelos que eliminan los bloques de pensamiento anteriores, los bloques de pensamiento (mostrados en gris oscuro) se generan durante la fase de salida de cada turno, pero no se trasladan como tokens de entrada para los turnos posteriores. No necesitas eliminar los bloques de pensamiento tú mismo: si los devuelves, la API de Claude los elimina automáticamente.
• Facturación: Los tokens de pensamiento se facturan como tokens de salida una sola vez, cuando se generan. En los modelos que conservan los bloques de pensamiento anteriores, los bloques conservados pasan a formar parte de la entrada de solicitudes posteriores y se facturan como tokens de entrada, al igual que el resto del historial de la conversación.

La ventana de contexto con pensamiento y uso de herramientas

El siguiente diagrama ilustra cómo se gestionan los tokens cuando combinas el pensamiento con el "tool use" (uso de herramientas) en un modelo que elimina los bloques de pensamiento anteriores:

1. 1

   Arquitectura del primer turno

   • Componentes de entrada: Configuración de herramientas y mensaje del usuario
   • Componentes de salida: Pensamiento + respuesta de texto + solicitud de uso de herramientas
   • Cálculo de tokens: Todos los componentes de entrada y salida cuentan para la ventana de contexto, y todos los componentes de salida se facturan como tokens de salida.
2. 2

   Manejo de resultados de herramientas (turno 2)

   • Componentes de entrada: Cada bloque del primer turno y el tool_result. Debes devolver el bloque de pensamiento con los resultados de herramientas correspondientes. Este es el único caso en el que tienes que devolver bloques de pensamiento.
   • Componentes de salida: Después de que los resultados de herramientas se han devuelto a Claude, Claude responde solo con texto (sin pensamiento adicional hasta el siguiente mensaje de user, a menos que el pensamiento intercalado esté habilitado).
   • Cálculo de tokens: Todos los componentes de entrada y salida cuentan para la ventana de contexto, y todos los componentes de salida se facturan como tokens de salida.
3. 3

   Nuevo turno del usuario (turno 3)

   • Componentes de entrada: Todas las entradas y la salida del turno anterior se trasladan. El bloque de pensamiento del ciclo de uso de herramientas completado ya no tiene que permanecer en el contexto: en los modelos que eliminan los bloques de pensamiento anteriores, la API lo descarta automáticamente cuando lo devuelves, y en los modelos que conservan los bloques de pensamiento anteriores, permanece a menos que lo limpies con la limpieza de bloques de pensamiento. Aquí también es donde agregas el siguiente turno de user.
   • Componentes de salida: Debido a que hay un nuevo turno de user fuera del ciclo de uso de herramientas, Claude genera un nuevo bloque de pensamiento y continúa desde ahí.
   • Cálculo de tokens: En los modelos que eliminan los bloques de pensamiento anteriores, los tokens de pensamiento anteriores ya no cuentan para la ventana de contexto. Todos los demás bloques anteriores siguen contando para la ventana de contexto, al igual que el bloque de pensamiento del turno actual de assistant.

• Consideraciones para el uso de herramientas con pensamiento:
  • Cuando envías resultados de herramientas, debes incluir el bloque de pensamiento completo y sin modificar que acompaña a esa solicitud de herramienta, incluida su firma.
  • La API usa firmas criptográficas para verificar la autenticidad de los bloques de pensamiento. Si modificas un bloque de pensamiento, la API devuelve un error.

Para reducir el contexto consumido por las propias definiciones de herramientas, consulta Gestionar el contexto de herramientas, o difiere las definiciones de herramientas con la herramienta de búsqueda de herramientas.

Conciencia del contexto

Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 y Claude Haiku 4.5 tienen "context awareness" (conciencia del contexto): estos modelos hacen un seguimiento de su ventana de contexto restante (su "presupuesto de tokens") a lo largo de una conversación. Esto permite que el modelo gestione tareas de larga duración en función del espacio que queda, en lugar de adivinar cuántos tokens restan. La conciencia del contexto es automática: no hay nada que debas habilitar, y nunca envías tú mismo las etiquetas que se muestran en esta sección. La API las inyecta.

Cómo funciona

En la indicación del sistema de cada solicitud, la API le proporciona a Claude su ventana de contexto total:

<budget:token_budget>200000</budget:token_budget>

El presupuesto coincide con la ventana de contexto disponible para tu solicitud: 1M de tokens para Claude Sonnet 5 y Claude Sonnet 4.6, y 200k tokens para Claude Sonnet 4.5 y Claude Haiku 4.5. Los ejemplos de esta sección muestran un modelo con una ventana de contexto de 200k tokens.

Después de cada llamada a herramienta, la API le proporciona a Claude una actualización de su capacidad restante:

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

Los tokens de imagen se incluyen en estos presupuestos.

Claude Opus 4.7 y modelos Opus posteriores, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 y Claude Mythos 5 no reciben estas etiquetas inyectadas. En estos modelos, puedes darle al modelo un presupuesto explícito con los presupuestos de tareas, que están en beta.

Para obtener orientación sobre prompts para usar la conciencia del contexto, consulta Mejores prácticas de prompting.

Gestionar el contexto con compactación

Si tus conversaciones se acercan regularmente a los límites de la ventana de contexto, usa la compactación del lado del servidor. La compactación resume automáticamente las partes anteriores de la conversación en el servidor, de modo que la conversación pueda continuar más allá del límite de la ventana de contexto. Está disponible en beta para Claude 4.6 y modelos posteriores y para Claude Mythos Preview.

Para necesidades más especializadas, la edición de contexto ofrece estrategias adicionales:

• Limpieza de resultados de herramientas: Limpia resultados de herramientas antiguos en flujos de trabajo agénticos
• Limpieza de bloques de pensamiento: Gestiona los bloques de pensamiento cuando usas el pensamiento extendido

Los prefijos de prompt almacenados en caché siguen ocupando la ventana de contexto: el almacenamiento en caché de prompts cambia lo que pagas por esos tokens, no si cuentan o no.

Comportamiento de desbordamiento de la ventana de contexto

Si la entrada por sí sola ya excede la ventana de contexto del modelo, la API devuelve un error 400 invalid_request_error ("prompt is too long") en todos los modelos.

En los modelos Claude 4.5 y más recientes, si los tokens de entrada más max_tokens exceden el tamaño de la ventana de contexto, la API acepta la solicitud. Si la generación luego alcanza el límite de la ventana de contexto, se detiene con stop_reason: "model_context_window_exceeded". En modelos anteriores, la API devuelve en su lugar un error de validación. Para optar por el comportamiento model_context_window_exceeded en esos modelos, usa el encabezado beta model-context-window-exceeded-2025-08-26. Consulta Razones de detención y alternativas para más detalles.

Para mantenerte dentro de los límites de la ventana de contexto, usa la API de conteo de tokens para estimar el uso de tokens antes de enviar mensajes a Claude.

Próximos pasos