Claude message threads: qué son y cómo usarlos

Qué son los message threads

Sin un hilo, cada turno del bucle de un agente vuelve a subir la conversación completa, y la API vuelve a validarla y tokenizarla entera. Un agente de programación hace cientos de peticiones en una sesión, así que cuando la conversación llega a cientos de miles de tokens, ese reenvío retrasa el comienzo de la respuesta de Claude. Con un hilo, la API conserva la conversación entre turnos y la mayor parte de ese trabajo afecta solo al turno nuevo.

• Primer token más rápido: Anthropic midió una bajada de la mediana de un 35 % aproximadamente en peticiones de Claude Code de 500 000 a 1 M de tokens. Cuanto más larga es la conversación, más ayuda.
• Peticiones más pequeñas: cada turno lleva solo mensajes nuevos, resultados de herramientas o capturas de pantalla.
• Mismos tokens y mismo precio: Claude sigue leyendo la conversación completa en cada turno, y ni los precios ni los límites de uso cambian.
• De corta duración: un hilo caduca 5 minutos después de su última petición y se guarda en memoria, cifrado, sin escribirse nunca en disco.
• Dónde: la API de Claude, Claude Platform en AWS, Claude Models en Google Cloud (gestionado por Anthropic) y Microsoft Foundry, con todos los modelos.

Con y sin hilo

Cómo usar los message threads en tu propio agente

Claude Code ya lo hace por ti. Para usar hilos en un agente que construyes sobre la Messages API, el helper de hilos del SDK es el camino más corto.

1. Crea un helper de hilo

   Pasa los mismos campos que en una petición de Messages. El helper añade la cabecera beta message-threads-2026-08-12, crea el hilo en el primer turno, envía solo mensajes nuevos después y mantiene la conversación completa en memoria.

   import anthropic
   
   client = anthropic.Anthropic()
   
   # Crea el helper. Esta llamada no envía ninguna petición.
   thread = client.beta.messages.thread(
       model="claude-opus-5-5",
       max_tokens=1024,
       cache_control={"type": "ephemeral"},
       system="You are a coding agent. Keep replies short.",
   )
   
   # El turno 1 crea el hilo y envía la conversación completa
   thread.send({"role": "user", "content": "Read the failing test and explain it."})
   
   # El turno 2 envía solo el mensaje nuevo
   reply = thread.send({"role": "user", "content": "Now fix it."})

2. O envía tú mismo el campo thread

   Con cURL o una llamada create normal, añade thread a cada petición y envía la cabecera beta en todas. Continúa siempre desde el id de la última respuesta; cada id solo se puede continuar una vez.

   # Turno 1: la conversación completa, más
   "thread": {"type": "create"}
   
   # Todos los turnos siguientes: solo los mensajes nuevos, sin system ni tools, más
   "thread": {"type": "continue", "previous_message_id": "<id of the last response>"}
   
   # En cada petición del hilo
   anthropic-beta: message-threads-2026-08-12

3. Mantén fijos el modelo y los ajustes

   system y tools van solo en la primera petición. model, thinking, tool_choice, el cache_control de nivel superior y las cabeceras beta deben ser los mismos en todos los turnos; un cambio devuelve un error 400 con thread_fingerprint_mismatch. Para cambiarlos, empieza un hilo nuevo.

4. Guarda tu propia copia y reenvía ante un 404

   Los hilos funcionan en la medida de lo posible (best-effort). Cuando una petición de continuación devuelve 404 con thread_not_found (el hilo caducó, el último turno no se guardó o lo escribió un modelo de respaldo), envía de nuevo la conversación completa en una petición create nueva. El helper del SDK lo hace una vez por sí solo.

5. Activa el prompt caching

   Un hilo no pone tu prompt en caché por ti. Envía un cache_control de nivel superior en cada petición para que cada turno lea la conversación anterior desde la caché; una petición con thread puede llevar como máximo 4 puntos de corte (breakpoints).

Fuente: la documentación de message threads de Anthropic

Límites y lo que los hilos no admiten

• No funcionan con Message Batches, el recuento de tokens, la compactación bajo demanda ni la edición de contexto (salvo clear_thinking_20251015 con keep: "all").
• No están disponibles para organizaciones con HIPAA readiness ni con Inference hooks; esas peticiones devuelven un error 400 con thread_unsupported_request.
• No son compatibles con la retención cero de datos: la API guarda el hilo en memoria y lo elimina como máximo 1 hora después de su último uso.
• No hay API para listar, leer ni borrar un hilo, y un hilo solo admite añadir mensajes. Para compactar, empieza un hilo nuevo a partir de tu propio resumen.
• Tras una negativa (refusal), no continúes el hilo: empieza uno nuevo sin el turno que la provocó.
• Usa la misma clave de API y el mismo workspace en todas las peticiones de un hilo, o no se podrá continuar.

Qué significa para quienes usan Claude Code

No necesitas cambiar nada: Anthropic dice que los hilos están activados por defecto para la mayoría de los usuarios de Claude Code. La mejora se nota en las sesiones largas, donde un turno avanzado en una conversación grande empieza a responder antes. Tu consumo no baja, porque Claude sigue leyendo toda la conversación en cada turno.

Según la documentación de la API, un hilo caduca 5 minutos después de su última petición. Si retomas una sesión tras una pausa más larga, la primera petición vuelve a enviar la conversación completa y los turnos siguientes son rápidos. Es también lo que le pasa a una sesión proactiva de Claude Code que se despierta según un horario.

Haz que las sesiones largas de Claude Code trabajen solas

Los message threads hacen más rápidas las sesiones largas; Crewmark las hace proactivas. Da a una sesión de Claude Code, Codex, DeepSeek Harness u OpenCode un rol, un objetivo y un horario laboral, y la despierta con un latido (heartbeat) en la misma conversación, de modo que conserva su contexto y toma el siguiente issue de un tablero.

1. Convierte una sesión en un empleado

   Elige un rol, como ingeniero de software o especialista SEO, escribe su objetivo como un número y ejecuta el comando de configuración en Claude Code.

2. Deja que el latido inicie el trabajo

   Durante su horario laboral, el empleado se despierta cada 15, 30 o 60 minutos en la misma conversación; consulta cómo hacer proactivo a Claude Code. Pueden funcionar varios a la vez, como en varios agentes de Claude Code.

3. Asigna issues y responde a sus mensajes

   Pon trabajo en el tablero; el empleado lo toma, comenta sobre la marcha y te escribe cuando necesita una decisión. Lee qué es un empleado de IA.

Preguntas frecuentes sobre Claude message threads