Desbordamiento de Contexto y Desconexiones de Streaming: Una Lista de Verificación de Prevención

Ambas fallas comparten una causa raíz: algo que estaba bien al inicio de una solicitud sobrevivió a los recursos asignados para ello. Una conversación crece más allá de la ventana de contexto del modelo, o una conexión de streaming se interrumpe a mitad de respuesta. Esta lista de verificación cubre los pasos concretos para prevenir ambas, y para recuperarse limpiamente cuando la prevención no es suficiente.

Cómo Usar Esta Lista de Verificación

Trabaja a través de los dos niveles en orden: gestión de contexto primero, resiliencia de streaming segundo, se acumulan en bucles de agente que transmiten conversaciones largas de uso de herramientas.
Trata los ítems 1-4 como requeridos para cualquier integración Claude multi-turno o de agente; los ítems 5-8 se aplican una vez que hayas confirmado que el contexto está bajo control.
Los ítems 9-14 se aplican específicamente a cualquier código que use la API de streaming del SDK; sáltatelos si solo usas llamadas no-streaming.
Revisa esta lista de verificación cada vez que agregues una nueva herramienta a un bucle de agente, ya que los resultados de las herramientas son una fuente común de crecimiento de contexto no planificado.
Registra el conteo de tokens y el conteo de turnos en los que ocurrió cualquier falla; ese número te dice cuánto margen necesitas recortar realmente.

Prevención de Desbordamiento de Contexto (1-8)

Conoce la ventana de contexto real de tu modelo antes de construir contra ella. Busca la ventana de contexto actual para el modelo específico que estás llamando, no asumas que coincide con el límite de un modelo anterior por memoria.
Cuenta los tokens por turno, no solo por solicitud. Usa el conteo de tokens del SDK para medir el total acumulado de una conversación después de cada turno, no solo el tamaño del último mensaje.
Establece un umbral de recorte muy por debajo del límite estricto. Reserva margen, comúnmente 15-25% de la ventana, para la propia respuesta del modelo y cualquier resultado de herramienta que aún esté por venir en el mismo turno.
Resume o descarta los turnos más antiguos antes de truncar a mitad de mensaje. Truncar un mensaje a la mitad puede dejar un bloque tool_use sin su tool_result correspondiente, lo cual la API rechazará por completo.
Limita el tamaño del resultado de la herramienta antes de que vuelva a entrar en el contexto. Una herramienta que puede devolver una cantidad ilimitada de datos (un archivo completo, un resultado de consulta grande) necesita su propia truncación o resumen antes de ser añadida de nuevo a la conversación.
Persiste el historial completo fuera de la ventana de contexto, no dentro de ella. Mantén una transcripción completa en tu propio almacenamiento y solo alimenta al modelo una ventana de trabajo recortada, de modo que recortar para la API nunca signifique perder datos para tus propios registros o una revisión humana posterior.
Prueba con una conversación lo suficientemente larga como para alcanzar realmente tu umbral de recorte. Una conversación de prueba corta nunca ejercitará la lógica de recorte; construye deliberadamente una larga en una prueba para confirmar que el umbral se activa correctamente.
Alerta sobre la proximidad de los límites de contexto, no solo sobre el desbordamiento. Una advertencia al 80% de tu umbral de recorte te da tiempo para investigar una conversación que está creciendo inusualmente rápido, antes de que falle realmente.

Recuperación de Desconexiones de Streaming (9-14)

Rastrea la salida parcial a medida que se transmite, no solo al completarse. Almacena en búfer los deltas de texto a medida que llegan, de modo que una desconexión a mitad de transmisión te deje con lo que ya se generó, no con nada.
Distingue un final de transmisión limpio de una conexión caída. Una transmisión que termina con un evento message_stop adecuado tuvo éxito; una transmisión que genera un error de conexión a mitad de camino no lo hizo y necesita un manejo diferente.
Establece una política de reconexión para transmisiones caídas, utilizando la misma disciplina de retroceso que cualquier otro error transitorio. Un reintento directo en una transmisión caída debe seguir el mismo enfoque de retroceso con jitter que cualquier otro error transitorio de la API de Claude, no un bucle ad hoc separado.
Decide de antemano si una reconexión reanuda o reinicia. La API de Mensajes no reanuda una respuesta parcialmente transmitida desde donde se quedó; una reconexión emite una nueva solicitud, así que decide si reenviar el prompt completo o continuar desde la salida parcial que ya tenías en búfer.
Fragmenta salidas grandes para el consumidor, independientemente de cómo el modelo las transmita. Si tu propio consumidor downstream (una UI, otro servicio) no puede manejar una transmisión ilimitada, fragmenta lo que le reenvías independientemente de cómo Claude entregue los tokens.
Registra el conteo de bytes/tokens realmente entregado antes de una desconexión. Este número es lo que te dice, después del hecho, si el lector vio una respuesta casi completa o casi nada, lo que cambia si la recuperación correcta es "simplemente mostrar lo que tenemos" o "reiniciar limpiamente".

import anthropic
 
client = anthropic.Anthropic()
 
def stream_with_recovery(prompt: str) -> str:
    collected = ""
    try:
        with client.messages.stream(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": prompt}],
        ) as stream:
            for text in stream.text_stream:
                collected += text
        return collected
    except anthropic.APIConnectionError:
        # La salida parcial se conserva en `collected` aunque la
        # transmisión se haya interrumpido; el llamador decide si mostrarla o reintentar.
        return collected

Aplicando la Lista de Verificación en Orden

Los ítems de contexto (1-8) van primero porque un contexto desbordado puede causar que una respuesta transmitida se corte a mitad de generación, una falla de ciclo de vida que se enmascara como una falla de transmisión.
Los ítems de streaming (9-14) asumen que el contexto ya está bajo control, por lo que una desconexión que estás depurando es genuinamente un problema de conexión, no un síntoma de una solicitud demasiado grande.
Revisa ambos niveles juntos después de cualquier cambio en las definiciones de herramientas, ya que las nuevas herramientas son la fuente más común tanto de crecimiento de contexto como de salidas transmitidas más grandes.

Trampas

Truncar a mitad de mensaje en lugar de a mitad de turno. Cortar un mensaje en medio de un par tool_use/tool_result produce una conversación inválida que la API rechazará. Siempre trunca en los límites de turno.
Asumir que una transmisión caída puede reanudarse desde donde se detuvo. No puede; una reconexión es una nueva solicitud, y tu código necesita decidir explícitamente si reiniciar o continuar desde la salida parcial ya almacenada en búfer.
No alertar hasta la falla estricta. Esperar un error real de desbordamiento de contexto para notar que una conversación está creciendo demasiado significa que te enteras por una falla visible para el usuario, no por un panel de control.

Preguntas Frecuentes

¿Cuánto margen debo reservar por debajo del límite de contexto estricto?

Un punto de partida común es 15-25% de la ventana, suficiente para cubrir la propia respuesta del modelo más cualquier resultado de herramienta aún esperado en el mismo turno. Ajusta esto según el tamaño real de tus resultados de herramienta típicos.

¿Por qué no puedo simplemente truncar el mensaje más antiguo cuando una conversación se alarga?

Si el mensaje truncado es un bloque tool_use, su tool_result correspondiente más adelante en la conversación queda huérfano, y la API rechazará la secuencia de mensajes resultante. Trunca turnos completos, no fragmentos de mensajes arbitrarios.

¿La API de Claude admite la reanudación de una transmisión caída desde donde se detuvo?

No. Una reconexión después de una transmisión caída es una nueva solicitud. Tu código debe decidir explícitamente si reenviar el prompt original o continuar la conversación utilizando la salida parcial que ya tenías almacenada en búfer.

¿Debo persistir el historial completo de la conversación incluso si recorto lo que envío al modelo?

Sí. Mantén la transcripción completa en tu propio almacenamiento y solo envía una ventana de trabajo recortada a la API. De esa manera, recortar por razones de ventana de contexto nunca significa perder datos para tus propios registros, auditorías o una revisión humana posterior.

¿Cuál es la diferencia entre una transmisión que termina limpiamente y una transmisión que se desconecta?

Un final limpio entrega un evento de parada adecuado después de que el modelo termina de generar. Una desconexión genera un error de conexión a mitad de camino, antes de que llegue ese evento de parada, y necesita un manejo de recuperación explícito en lugar de ser tratado como una finalización normal.

¿Cómo sé si una herramienta corre el riesgo de causar desbordamiento de contexto?

Cualquier herramienta cuyo tamaño de salida no esté limitado, como la lectura de un archivo, un conjunto de resultados de búsqueda, una consulta a base de datos, es candidata. Limita o resume su salida antes de que se añada de nuevo a la conversación, en lugar de asumir que siempre será pequeña.

¿Es la reconexión a una transmisión caída lo mismo que reintentar una llamada no-streaming fallida?

La disciplina de retroceso debe ser la misma (retroceso exponencial con jitter), pero la decisión de qué enviar en la reconexión es diferente: un reintento no-streaming generalmente reenvía la misma solicitud sin cambios, mientras que una reconexión de transmisión debe decidir si reenviar el prompt completo o continuar desde la salida parcial.

¿Debo alertar solo cuando ocurre el desbordamiento de contexto, o antes?

Antes. Alerta en un umbral por debajo de tu punto de recorte (por ejemplo, el 80% de él) para que tengas tiempo de investigar por qué una conversación específica está creciendo inusualmente rápido, en lugar de enterarte solo cuando el recorte o una falla directa ya han ocurrido.

¿Cómo pruebo que mi lógica de recorte realmente funciona?

Construye deliberadamente una conversación de prueba larga que exceda tu umbral de recorte y verifica que el recorte se active en el punto esperado. Una conversación corta en un conjunto de pruebas típico nunca ejercitará esta ruta.

¿Importa fragmentar la salida para mi propia UI si Claude ya transmite token por token?

Sí, son preocupaciones independientes. La transmisión a nivel de token de Claude no garantiza que tu consumidor downstream, un navegador, un cliente móvil, otro servicio, pueda manejar una transmisión ilimitada o no fragmentada; fragmenta lo que reenvías según lo que ese consumidor realmente necesita.

¿Qué debo registrar cuando una transmisión se desconecta a mitad de camino?

La cantidad de salida ya entregada (conteo de tokens o bytes) antes de la desconexión. Ese número te dice si el usuario vio una respuesta casi completa que vale la pena conservar, o casi nada, lo que cambia si la recuperación correcta es mostrar la salida parcial o descartarla y reintentar.

¿Es el desbordamiento de contexto más probable en bucles de uso de herramientas de agente que en chat simple?

Sí. Cada llamada a herramienta y su resultado se suman al contexto acumulado, y los bucles de agente a menudo ejecutan muchos turnos seguidos sin una pausa natural, por lo que el contexto puede crecer más rápido y de manera menos predecible que en una conversación directa de ida y vuelta.

Relacionado

Entendiendo Por Qué los Agentes Claude Fallan en Producción - dónde encajan las fallas del ciclo de vida en la taxonomía general de fallas.
Fundamentos de Solución de Problemas y Fiabilidad - la base de registro que esta lista de verificación asume que ya está implementada.
Estrategias de Reintento y Retroceso Exponencial para Fallas Transitorias de la API de Claude - la disciplina de retroceso a aplicar al reconectar una transmisión caída.
Tormentas de Fallos de Caché de Prompts: Diagnóstico de Picos Repentinos de Costo y Latencia - cómo las elecciones de recorte de contexto también pueden afectar la estabilidad de la caché.
Mejores Prácticas de Solución de Problemas y Fiabilidad - dónde encaja esta lista de verificación en el conjunto más amplio de prácticas.

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial anthropic de Python (última versión 0.x). Los nombres de modelos, precios y versiones del SDK cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.