AIREITERPara agentes con historiales enormes, Message Threads elimina buena parte del tráfico repetido hacia la API. Anthropic lo lanzó en beta pública el 2 de noviembre de 2026 y cifra en torno al 35% la reducción mediana del tiempo hasta el primer token en solicitudes de 500K a 1M de tokens. La contrapartida importante: Claude sigue procesando toda la conversación en cada turno, así que el coste de tokens permanece intacto. Es una mejora de transporte, no de facturación, y tiene un límite estricto de 5 minutos de inactividad.
Menos datos enviados, misma factura de tokens
Message Threads añade estado temporal de conversación en el servidor para la Messages API. En la primera llamada envías el historial completo mediante thread: { "type": "create" }; después, basta con mandar los mensajes nuevos y previous_message_id usando thread: { "type": "continue" }. Según el anuncio de Anthropic y la documentación de la plataforma, el estado se mantiene en memoria cifrada, nunca se escribe en disco, caduca tras 5 minutos sin actividad y se elimina como máximo 1 hora después del último uso.
Todas las solicitudes de un hilo deben incluir la cabecera beta anthropic-beta: message-threads-2026-08-12. Los precios y límites de tasa no cambian: Claude sigue leyendo la conversación completa en cada turno. En otras palabras, subes muchos menos bytes, pero pagas los mismos tokens de entrada y salida.
"Sí, muy bien, pero no reduce el coste de tokens :( Claude sigue leyendo toda la conversación en cada turno y el consumo de tokens no cambia" — @_navicstein, en respuesta al hilo oficial del lanzamiento
El anuncio oficial habla de aproximadamente un 35% menos de TTFT mediano en solicitudes de 500K a 1M de tokens, sin descuento alguno en tokens.
En qué se diferencia de prompt caching
Los threads reducen lo que envías; el prompt caching reduce la parte por la que pagas el precio completo. Un thread no activa la caché automáticamente: sigues necesitando definir los puntos de corte con cache_control. La interacción detallada con la caché, basada en este desglose de implementación, exige mantener un cache_control de nivel superior en cada continuación. Las lecturas de caché cuestan 0,1 veces la entrada base, o 0,05 veces en Claude Opus 5.5 y Sonnet 5.5.
No confundirlos con los session threads de agentes gestionados
En los resultados de búsqueda aparecen dos conceptos distintos llamados «threads». Los message threads de la Messages API —los de este artículo— son una optimización efímera del tamaño de las solicitudes y no tienen API para listar, leer ni eliminar. Los session threads de agentes gestionados (GET /v1/sessions/{session_id}/threads/{thread_id}) son hilos de ejecución dentro de la API managed-agents de Anthropic, con endpoints para listar, recuperar y archivar. Si la documentación habla de hilos secundarios, streams de eventos o archivado, estás consultando la API equivocada. Revisa la referencia de la API de session threads para identificar cuál necesitas.
El ciclo de vida de un hilo: crear, continuar y reconstruir
En la práctica, un hilo solo admite anexar contenido: lo creas con todo el contexto, lo continúas con cambios incrementales y lo reproduces por completo si se pierde. No existe API para bifurcar, editar, rebobinar ni inspeccionar. Cada respuesta devuelve un nuevo id, y cada id solo puede usarse una vez para continuar. Las reglas de campos y errores de esta sección siguen la documentación de la plataforma, desarrollada en este análisis de implementación.
La creación incluye todo el contexto: messages, system y tools completos, además de:
{
"model": "claude-opus-5-5",
"system": "You are a support agent for Acme. Keep replies short.",
"messages": [{ "role": "user", "content": "Hi! I have a question about an order." }],
"thread": { "type": "create" }
}Una continuación solo incorpora lo nuevo, normalmente un mensaje del usuario o bloques tool_result:
{
"model": "claude-opus-5-5",
"messages": [{ "role": "user", "content": "How long does standard shipping usually take?" }],
"thread": { "type": "continue", "previous_message_id": "msg_xxx_from_create" }
}No incluyas system ni tools al continuar: incluso "system": null provoca un error 400. En respuestas por streaming, espera a message_stop antes de continuar; el ID válido para continuar llega en message_start.
Campos que puedes modificar durante un hilo
Anthropic genera una huella de parte de la solicitud de creación. Si modificas un valor incluido en esa huella, recibirás thread_fingerprint_mismatch y tendrás que abrir un hilo nuevo.
| Grupo | Ejemplos | Regla al continuar |
|---|---|---|
| Solo al crear | system, tools | No los reenvíes; null también falla |
| Fijos | model, tool_choice, thinking, mcp_servers, context_management, output_config, habilidades de contenedor, gestión de cache_control de nivel superior | Deben permanecer idénticos |
| Flexibles | max_tokens, stop_sequences, stream, metadata, service_tier | Pueden cambiar en cada turno |
| Reenviar siempre | URL y tokens de autenticación de servidores MCP, ID de container | No se guardan en el servidor; inclúyelos cada vez que los uses |
Los modelos con pensamiento extendido requieren especial cuidado: modificar system o tools puede invalidar bloques previos de thinking / redacted_thinking. Si una reproducción completa tras la caducidad devuelve un 400, elimina de ese historial los bloques de pensamiento obsoletos en lugar de reintentar el envío sin cambios.
La regla de los 5 minutos y el replay obligatorio
Trata los threads como una optimización de mejor esfuerzo: conserva localmente el historial completo, el system prompt, las herramientas y las referencias a archivos. El almacenamiento solo queda confirmado cuando la siguiente continuación se realiza correctamente. Los archivos se guardan por referencia; si eliminas uno a mitad del hilo, la continuación fallará.
El contador de caducidad se reinicia con cada respuesta almacenada. Tras 5 minutos de inactividad, la siguiente continuación devuelve 404 y debes reproducir la conversación completa con un nuevo create. Los datos se eliminan, como tarde, 1 hora después del último uso.
| HTTP | Código | Qué ha ocurrido | Qué hacer |
|---|---|---|---|
| 404 | thread_not_found | Ha caducado, no se almacenó, se usó una clave o workspace distinto, se añadió la primera imagen a un hilo solo de texto, lo atendió un modelo fallback o la respuesta aún se está generando | Comprueba clave/workspace y configuración; después reproduce el historial completo con un nuevo create |
| 400 | thread_fingerprint_mismatch | Ha cambiado un campo fijo | Restaura el valor original o inicia un hilo nuevo |
| 400 | thread_already_continued | Ese previous_message_id ya se utilizó | Continúa desde el id más reciente |
| 400 | thread_continue_in_flight | Hay una continuación concurrente sobre el mismo ID | Espera a que termine y usa su nuevo ID; si no, reproduce el hilo |
| 400 | thread_unsupported_request | Configuración no compatible, como más de 4 puntos de corte de caché o batches | Elimina esa configuración o envía la solicitud sin thread |
Según el resumen de la documentación, las solicitudes fallidas de threads se resuelven antes de ejecutar el modelo: no consumen tokens ni reinician el temporizador de caducidad. Guarda de forma atómica el ID de la última respuesta correcta antes de aceptar el siguiente turno y protege los replays con idempotencia cuando las acciones de herramientas tengan efectos secundarios.
Esquema de replay en Python: gestiona solo thread_not_found verificado; los errores de huella, concurrencia y solicitud no compatible requieren ramas independientes:
try:
resp = client.beta.messages.create(
model="claude-opus-5-5",
messages=[new_msg], # delta only
thread={"type": "continue", "previous_message_id": last_id},
extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
)
except NotFoundError: # thread_not_found after checking identity/config
resp = client.beta.messages.create(
model="claude-opus-5-5",
system=SYSTEM, tools=TOOLS,
messages=full_history + [new_msg], # you stored this
thread={"type": "create"},
extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
)El problema de los 404 con proxies y rotación de claves
Este comportamiento procede de informes de operadores y todavía no aparece en la documentación oficial: un thread queda vinculado a la organización, el workspace y la credencial que lo creó. Un relay que rota claves de API en cada solicitud creará el hilo con la clave A y tratará de continuarlo con la clave B. El resultado se parece exactamente a una caducidad: 404 continuos y reenvío completo del historial, sin ganancia de latencia.
"Un thread queda vinculado a la key y al workspace que lo crearon; al cambiar de key devuelve 404 thread_not_found. Los servicios de retransmisión que rotan keys primero reciben un 404 y luego reenvían todo el historial." — @ak12kpoot (nota de un desarrollador chino sobre el comportamiento de proxies)
Fija cada hilo a una única clave o prescinde de threads en rutas con un pool de credenciales.
Compatibilidad, limitaciones y cuándo conviene activarlos
Message Threads está disponible en la Claude API, Claude Platform on AWS, Anthropic-managed Google Cloud Claude Models y Claude in Microsoft Foundry. Todos los modelos incluidos en la beta son compatibles; no hay una lista de modelos separada ni una lista de espera anunciada.
Para planificar el lanzamiento, las exclusiones son aún más relevantes:
| Área | Estado |
|---|---|
| Amazon Bedrock | No compatible |
| Message Batches | No compatible: los elementos de thread en lote fallan |
| Endpoint de conteo de tokens | No compatible: debes contar tú mismo el historial completo |
| Compaction / edición de contexto | No compatible, salvo clear_thinking con keep all |
| Retención cero de datos, HIPAA-ready, inference hooks | No elegible |
| API de gestión de threads | No existe: no puedes listar, leer ni eliminar threads |
Checklist para decidir
- Actívalos ya: en agentes de programación activos, bucles de computer use con capturas de pantalla o flujos con muchos documentos que realizan decenas de turnos sin pausas de más de 5 minutos. Combínalos con prompt caching y una ruta de replay.
- Mejor esperar: en chats al ritmo de una persona, flujos pausados, pipelines por lotes, cargas ZDR/HIPAA o despliegues sobre Bedrock.
- Combínalos solo si compensa: el
cache_controlde nivel superior de cada solicitud cuenta para el límite de 4 puntos de corte. Los puntos de corte desystem/toolsdurante la creación vuelven a contar en cada continuación. Si superas el límite, recibirásthread_unsupported_request; consolida los puntos de corte antes de activar ambas funciones.
Consulta también: guía de precios de la API de Claude 2026, guía de la API Claude Skills.
Preguntas frecuentes
¿Qué cabecera beta y qué parámetro necesito?
Envía anthropic-beta: message-threads-2026-08-12 en cada solicitud del hilo. En la primera llamada, añade thread: { "type": "create" }; en las posteriores, usa thread: { "type": "continue", "previous_message_id": "<last response id>" }.
¿Qué ocurre cuando caduca un thread?
La siguiente continuación devuelve 404 thread_not_found. Reenvía todos los messages junto con los system/tools originales mediante un nuevo create. La caducidad llega tras 5 minutos de inactividad y los datos se eliminan como máximo 1 hora después del último uso.
¿Puedo listar, inspeccionar o eliminar threads?
No. No existe una API de gestión para los threads de la Messages API. El historial que guardes localmente es el único registro persistente.
¿Funciona en Amazon Bedrock?
No. Las superficies compatibles son la Claude API, AWS Claude Platform, Microsoft Foundry y Google Cloud gestionado por Anthropic. Las solicitudes de Bedrock deben seguir enviando el historial completo.
¿Puedo cambiar el system prompt o las herramientas a mitad del hilo?
No. Crea un hilo nuevo con los nuevos system/tools. Enviar valores modificados en una continuación provoca thread_fingerprint_mismatch. Lo mismo se aplica a model, tool_choice y la configuración de pensamiento.
¿Es compatible con streaming, herramientas y MCP?
Sí, con algunas reglas: espera a message_stop antes de continuar, reenvía en cada turno las URL/tokens MCP y los ID de container, y envía fallbacks en todas las solicitudes o en ninguna. Una respuesta de un modelo fallback no se almacena y debe reproducirse.