Message threads en la API de Claude: cuándo usarlos

Hilos de luz que salen de un núcleo central y se alargan en capas, con un tramo final más brillante que el resto sobre fondo azul oscuro

Los message threads de la API de Claude compensan en bucles largos de agente cuyos turnos se encadenan en menos de 5 minutos: permiten enviar solo los mensajes nuevos y pueden reducir el tiempo hasta el primer token. Están en beta desde el 02/11/2026. No cambian la facturación de tokens y tu aplicación debe conservar el historial completo para recuperarse cuando el thread deje de estar disponible.

La forma más corta de probarlos es el helper del SDK de Python. El SDK requiere Python 3.10 o superior. La versión 2.2.0 añadió soporte para message threads; los ejemplos siguientes usan la 2.9.0, publicada el 16/11/2026.

python -m pip install "anthropic==2.9.0"
export ANTHROPIC_API_KEY="tu-clave-en-variable-de-entorno"

Este fragmento crea el helper y envía dos turnos. El primer envío crea el thread y el segundo intenta continuarlo enviando solo el mensaje nuevo. El helper conserva la conversación en memoria:

import anthropic

client = anthropic.Anthropic()  # lee ANTHROPIC_API_KEY del entorno

thread = client.beta.messages.thread(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    cache_control={"type": "ephemeral"},
    system="Eres un agente que revisa pull requests. Responde breve.",
    unsupported_request_behavior="continue_unthreaded",
)

thread.send({"role": "user", "content": "Resume este diff: ..."})
respuesta = thread.send({"role": "user", "content": "¿Qué test falta?"})

for bloque in respuesta.content:
    if bloque.type == "text":
        print(bloque.text)

Para todo el artículo se usa un escenario hipotético: un agente propio que revisa pull requests, llama a herramientas unas 30 veces por tarea y acumula un historial cada vez más grande. Es el tipo de conversación en el que la documentación de message threads sitúa su mayor utilidad. El fragmento anterior solo muestra el intercambio de mensajes; no implementa ese bucle de herramientas.

Qué cambia en cada petición cuando usas un thread

Con un thread, la API conserva temporalmente la conversación en el servidor y tú solo envías lo que falta. Sin thread, cada turno vuelve a subir todo el historial, que la API debe validar y tokenizar de nuevo. La documentación describe tres pasos:

  • Create: la primera petición lleva la conversación completa, los campos system y tools que utilices y "thread": {"type": "create"}.
  • Continue: las siguientes llevan solo los mensajes nuevos y "thread": {"type": "continue", "previous_message_id": first.id}, sin system ni tools. Se usa siempre el identificador de la última respuesta.
  • Replay: si la API ya no puede continuar el thread, vuelves a enviar la conversación completa en un nuevo create.

Para construir las peticiones a mano, hay que distinguir los campos que se omiten de los que se repiten. Esta tabla resume las reglas oficiales, consultadas el 17/11/2026:

GrupoCamposRegla
Solo en createsystem, toolsSi los envías en un continue, aunque sea como null, recibes un 400.
Fijosmodel, tool_choice, thinking, mcp_servers salvo sus tokens de autorización, context_management, output_config, las skills de container, cache_control de nivel superior y el conjunto de betasSe repiten con el mismo valor. Si cambian, recibes un 400 thread_fingerprint_mismatch.
Libresmax_tokens, stop_sequences, stream, metadata, service_tierPueden cambiar en cada turno.

Si usas mcp_servers o container, envíalos en cada petición: el servidor no conserva las URL de MCP, sus tokens de autorización ni el identificador del contenedor. Los tokens de autorización de MCP pueden cambiar entre peticiones.

En el agente de ejemplo, eso implica que no puedes cambiar de modelo ni añadir una herramienta a mitad de la tarea sin abrir otro thread. Además, el thread solo admite añadir mensajes: cada id de respuesta se continúa una sola vez. Para editar o ramificar un mensaje anterior necesitas otro create.

El thread no ahorra tokens: el ahorro viene de la caché

Usar un thread no reduce por sí mismo la factura. La documentación es explícita: los threads no cambian los precios ni los límites de uso. El modelo sigue recibiendo la conversación completa en cada turno. Lo que se reduce es el tamaño de la petición y parte del trabajo de preparación del servidor.

Para reducir el coste del contexto repetido puedes usar prompt caching; el thread no lo activa por ti. Por eso el ejemplo lleva cache_control={"type": "ephemeral"} en el nivel superior. Ese campo solicita caché automática en cada turno. La reutilización depende de que exista un prefijo cacheado válido y de que se alcance la longitud mínima cacheable. Activarlo no garantiza un ahorro en cualquier conversación.

Los puntos de caché, o breakpoints, tienen estas reglas en los threads:

  • Una petición con thread admite como mucho 4 breakpoints de cache_control, y el de nivel superior cuenta como uno.
  • Los breakpoints de system y tools del create vuelven a contar en cada continue. Los de mensajes anteriores almacenados no cuentan para ese límite en un continue.
  • No puedes mover ni quitar un breakpoint ya almacenado mediante un continue, porque esa petición no reenvía los mensajes anteriores.
  • Al hacer replay, los breakpoints del historial vuelven a formar parte de la petición y pueden superar el límite. El helper elimina los de turnos anteriores cuando los reenvía.

Según las notas de versión de la plataforma, el 07/10/2026 la lectura de caché de Claude Sonnet 5.5 pasó de 0,20 USD a 0,10 USD por millón de tokens. La tarifa estándar del modelo también distingue las escrituras de caché, que tienen su propio coste. En el bucle hipotético de 30 turnos, el ahorro dependerá de cuánto contexto se reutilice y de cuántas escrituras y lecturas se facturen.

Cómo recuperarte del 404 thread_not_found con tu propia copia

Tu aplicación es la fuente de verdad, no el thread. Ninguna respuesta confirma si la API guardó ese turno: lo descubres en el siguiente continue. Según la documentación de recuperación, el error 404 con error.details.error_code igual a thread_not_found puede tener varias causas:

  • El thread ha caducado. La ventana es de 5 minutos y cada respuesta almacenada la reinicia.
  • La respuesta anterior acababa en una llamada a herramienta cortada por max_tokens y no se guardó.
  • Escribió la respuesta un modelo de fallback.
  • La respuesta anterior todavía se está generando.
  • La petición llega desde otra organización, otro workspace u otro usuario o cuenta de servicio. Los threads creados con una clave de workspace heredada quedan vinculados a esa clave.
  • El mensaje nuevo añade algo que la conversación almacenada no admite, como la primera imagen de una conversación que no tenía ninguna.

El error no identifica cuál de esas causas se ha producido. El helper hace un replay automáticamente. Si construyes las peticiones tú, esta función intenta el continue y, ante ese 404 concreto, reenvía la conversación completa en un create nuevo. Un modelo inexistente también devuelve 404, así que no basta con comprobar el estado HTTP.

from copy import deepcopy
import anthropic

BETA = ["message-threads-2026-08-12"]

def continuar(client, historial, nuevos, prev_id, comunes, solo_create):
    try:
        return client.beta.messages.create(
            **comunes,
            messages=nuevos,
            betas=BETA,
            thread={"type": "continue", "previous_message_id": prev_id},
        )
    except anthropic.NotFoundError as e:
        if e.error_code != "thread_not_found":
            raise

        replay = deepcopy(historial)
        for mensaje in replay:
            contenido = mensaje.get("content")
            if isinstance(contenido, list):
                for bloque in contenido:
                    if isinstance(bloque, dict):
                        bloque.pop("cache_control", None)

        return client.beta.messages.create(
            **comunes,
            **solo_create,
            messages=replay + nuevos,
            betas=BETA,
            thread={"type": "create"},
        )

En este código, historial y nuevos son listas de mensajes serializados como diccionarios. El historial contiene todos los mensajes anteriores, incluida la última respuesta del asistente, y excluye los mensajes nuevos. comunes contiene model, max_tokens y el cache_control de nivel superior; solo_create contiene system y tools. Aunque aquí se repita, max_tokens sigue siendo un campo libre.

La función elimina los breakpoints de los mensajes antiguos en una copia, sin modificar el historial original. Los de system, tools, los mensajes nuevos y el nivel superior deben seguir sumando como mucho 4. Después de una respuesta correcta, tu aplicación debe guardar los mensajes nuevos y la respuesta, y usar su id en el siguiente turno. Los resultados de herramientas también forman parte del historial.

El atributo e.error_code está disponible en el SDK 2.9.0 utilizado aquí. Esta función solo cubre la recuperación de ese 404. Si el primer continue después de un replay vuelve a devolver thread_not_found, envía la conversación completa sin thread. El helper aplica esa salida cuando se crea con unsupported_request_behavior="continue_unthreaded".

Cuándo no usar message threads: veredicto por caso

El thread compensa sobre todo en bucles rápidos y largos. Esta tabla recoge los casos prácticos y las incompatibilidades documentadas a 17/11/2026:

CondiciónVeredicto
Agente con muchas llamadas a herramientas encadenadas en segundosEs un buen candidato. Mide la latencia en tu aplicación.
Chat con una persona que suele tardar más de 5 minutos en responderAporta poco en esos intervalos: el thread caduca y el siguiente turno necesita replay.
Procesos con Message BatchesNo se admite. Cada elemento con thread termina en invalid_request_error.
Necesitas Token CountingCuenta la conversación completa, con system y tools, en una petición sin thread.
Necesitas compaction o context editingLa compactación bajo demanda no está disponible con threads. Puedes construir un resumen fuera del thread y abrir otro. De context editing solo se admite clear_thinking_20251015 con keep: "all".
Tu organización exige ZDR o tiene HIPAA readiness o Inference hooks activadosLos threads no son elegibles para ZDR. HIPAA readiness e Inference hooks son incompatibles y pueden producir thread_unsupported_request.
Editas o ramificas turnos anteriores a menudoNecesitas otro create con el historial correspondiente. fork() copia la conversación completa; no selecciona un punto anterior.
Cambias de modelo o de herramientas a mitad de la tareaAbre otro thread con los parámetros nuevos y revisa la validez de los bloques de razonamiento conservados.

En concreto, si cambias system o tools usando Sonnet 5.5, la documentación indica que debes quitar todos los bloques thinking y redacted_thinking del historial que envíes al nuevo create. La misma regla se aplica a los otros modelos enumerados en la sección sobre cambios de campos. No es una regla general que obligue a borrar el razonamiento ante cualquier cambio de modelo.

Ten en cuenta también la retención: la API conserva el thread en memoria, cifrado con una clave gestionada por el servidor, no lo escribe en almacenamiento duradero y lo borra como mucho una hora después de su último uso. Esa ventana de borrado no amplía los 5 minutos disponibles para continuarlo. Los ficheros se guardan por referencia, así que deben seguir disponibles mientras uses el thread. No hay ninguna API para listar, leer ni borrar threads.

Comprobaciones para activar threads en tu agente

  1. Usa una versión del SDK compatible. Los ejemplos de este artículo fijan anthropic==2.9.0 y requieren Python 3.10 o superior.
  2. Guarda el historial completo en tu aplicación. El helper solo lo conserva en memoria mientras exista el objeto.
  3. Repite los campos fijos con el mismo valor y deja fuera system y tools en los continue.
  4. Añade cache_control si quieres reutilizar el contexto mediante caché y respeta el límite de 4 breakpoints.
  5. Usa la misma API key y el mismo workspace durante el thread para evitar cambios de propietario.
  6. Con streaming, continúa solo después del evento message_stop.
  7. Después de stop_reason: "refusal", abre otro thread omitiendo o reformulando el turno que provocó el rechazo. Quitar solo la respuesta rechazada no resuelve ese caso.
  8. Recupera thread_not_found mediante replay. Ante thread_fingerprint_mismatch, conserva los campos fijos o crea otro thread. Ante thread_unsupported_request, revisa error.details.unsupported: puede señalar una función o una configuración de la organización incompatible. Retira esa función o envía la conversación completa sin thread.

El artículo describe la beta message-threads-2026-08-12 tal como está documentada a 17/11/2026. No cubre en detalle los fallbacks del servidor ni los session threads de Claude Managed Agents, que son una función distinta.

Preguntas frecuentes

¿Los threads funcionan fuera de la API directa de Anthropic?

Sí, en beta en Claude Platform on AWS, Claude Models on Google Cloud gestionado por Anthropic y Claude in Microsoft Foundry, según la página oficial. En Claude Platform on AWS, firma todas las peticiones del thread con las credenciales del rol o usuario IAM que lo creó. Esa disponibilidad no implica soporte en todas las demás modalidades de acceso a Claude en esos proveedores.

¿El tool runner del SDK usa threads sin que se lo pidas?

Sí. La documentación del helper indica que el tool runner beta del SDK usa un thread por defecto. En Python puedes desactivarlo con thread=False al crear el runner. Es un ajuste que debes revisar si tu entorno exige ZDR, porque los message threads no son elegibles.

Compartir

X LinkedIn
Volver al blog