Message threads en la API de Claude: solo se envían los mensajes nuevos

Anthropic ha lanzado en beta los message threads de la API de Claude: la conversación se queda un rato en el servidor y cada petición siguiente envía solo los mensajes nuevos. La novedad apareció en las Claude Release Notes el 2 de noviembre y funciona con la cabecera beta message-threads-2026-08-12.

¿Cómo funcionan los message threads en la API de Claude?

Hasta ahora, cada turno de una conversación con la Messages API obligaba a enviar todo el historial de nuevo: el prompt de sistema, las herramientas y todos los mensajes. Según la documentación de message threads, la API tenía que validarlo y tokenizarlo todo cada vez. Con un thread, la mayor parte de ese trabajo afecta solo al turno nuevo.

Todo el mecanismo es un parámetro nuevo, thread:

1. La primera petición se envía como siempre, con la conversación completa, system y tools, más "thread": {"type": "create"}. La API guarda la conversación junto con la respuesta de Claude bajo el id de esa respuesta.
2. Las peticiones siguientes llevan "thread": {"type": "continue", "previous_message_id": "<id>"} y solo los mensajes nuevos, por ejemplo el siguiente mensaje del usuario o los resultados de herramientas (tool_result).
3. system y tools se omiten, porque el thread ya los recuerda. Enviarlos en una petición continue devuelve un error 400.

Según Anthropic, el resultado son peticiones más pequeñas y un tiempo hasta el primer token más corto y estable, incluso cuando la conversación crece. Los que más ganan son los bucles de agentes largos, en los que el agente hace decenas de llamadas a herramientas y antes tenía que reenviar un historial cada vez mayor (más sobre cómo funcionan estos bucles en qué es un agente de IA).

¿Qué hace el SDK por nosotros?

El SDK incluye un nuevo ayudante, client.beta.messages.thread(...). Se crea con los mismos campos que una petición normal y luego cada turno se envía con thread.send(...). El ayudante añade la cabecera beta, crea el thread en el primer turno y lo continúa en los siguientes.

Lo curioso es que el tool runner beta del SDK usa threads por defecto, así que los agentes construidos sobre él pueden ganar velocidad sin cambiar el código (se puede desactivar al crear el runner).

El ayudante también gestiona los fallos: si un thread caduca, vuelve a enviar toda la conversación en una nueva petición create. Eso sí, guarda la copia completa solo en memoria, mientras exista el objeto del ayudante.

¿Qué hay que tener en cuenta?

Primero, su vida corta. Un thread caduca 5 minutos después de la última petición, y la API lo borra como máximo una hora después de su último uso. La documentación los define como „best-effort”: nuestra aplicación debe seguir siendo la fuente de verdad de la conversación y gestionar desde el principio el reenvío completo tras un error 404 thread_not_found.

Segundo, lo que no se puede cambiar. Campos como model, thinking, tool_choice o context_management deben mantener los mismos valores en todo el thread; si no, la API devuelve el error thread_fingerprint_mismatch. Un thread solo puede crecer, y cada id de respuesta se puede continuar una sola vez. Para editar un mensaje anterior o cambiar el prompt de sistema hay que empezar un thread nuevo.

Tercero, el prompt caching. Un thread no cachea nada por sí solo. La caché funciona como hasta ahora, y una petición con thread admite como máximo 4 puntos cache_control. Lo más sencillo es enviar en cada turno el mismo cache_control en el nivel superior de la petición.

Cuarto, las funciones con las que los threads no funcionan:

1. Message Batches y Token Counting.
2. Compaction, incluida la compactación bajo demanda, y context editing (con una excepción descrita en la documentación).
3. Organizaciones con HIPAA readiness o Inference hooks activados.

Quinto, los datos. Los threads no son compatibles con ZDR (zero data retention). Según la documentación, la conversación, el prompt de sistema y las herramientas se guardan en memoria, cifrados con una clave gestionada por el servidor, y nunca se escriben en disco persistente.

¿Dónde y con qué modelos funciona?

Los message threads están en beta en la API de Claude, Claude Platform on AWS, Claude Models on Google Cloud (gestionados por Anthropic) y Microsoft Foundry. Entre los modelos compatibles están Claude Fable 5.1 y Mythos 5.1, Opus 5.5, Sonnet 5.5 y Haiku 5.5, y de los anteriores también Opus 4.5, Sonnet 4.5 y Haiku 4.5.

Los threads no cambian los precios ni los límites de peticiones. Los tokens se pagan igual que antes, así que el ahorro está en tiempo y tamaño de las peticiones, y conviene seguir vigilando los costes, por ejemplo con la nueva API de análisis de costes de Claude. Es otro cambio en la propia API en los últimos días, tras la subida del límite de petición a 128 MB.

(No hay que confundirlos con los „session threads” de Claude Managed Agents. Es una función distinta, como recuerda la documentación.)

Preguntas frecuentes

¿Qué son los message threads de la API de Claude?

Una función beta en la que la API guarda la conversación en el servidor durante poco tiempo. Tras la primera petición se envían solo los mensajes nuevos y el id de la respuesta anterior.

¿Los message threads reducen los costes de la API de Claude?

No directamente. Según la documentación, los threads no cambian los precios ni los límites de peticiones. La ventaja son peticiones más pequeñas y un tiempo hasta el primer token más corto.

¿Cuánto tiempo guarda la API de Claude un thread?

Un thread caduca 5 minutos después de la última petición, y la API lo borra como máximo una hora después de su último uso. Después hay que enviar toda la conversación otra vez.

¿Funcionan los message threads en Amazon Bedrock?

La documentación menciona la API de Claude, Claude Platform on AWS, Claude Models on Google Cloud (gestionados por Anthropic) y Microsoft Foundry. Amazon Bedrock no aparece en la lista.