AIREITERPour les agents qui manipulent 500K à 1M tokens de contexte, les Message Threads d’Anthropic peuvent réduire le délai médian avant le premier token d’environ 35 %. Attention toutefois au raccourci : la facture de tokens ne baisse pas. Lancée en bêta publique le 2 novembre 2026, cette fonction règle surtout le transport des très longues conversations, avec une contrainte stricte : 5 minutes d’inactivité suffisent à perdre le thread.
Des requêtes plus légères, pas des tokens moins chers
Les Message Threads sont un état de conversation temporaire, maintenu côté serveur pour l’API Messages et disponible en bêta publique depuis le 2 novembre 2026. Lors de la création, vous envoyez l’historique complet avec thread: { "type": "create" }. Ensuite, chaque appel ne contient plus que les nouveaux messages et previous_message_id, avec thread: { "type": "continue" }. D’après l’annonce d’Anthropic et la documentation de la plateforme, cet état réside en mémoire chiffrée, n’est jamais écrit sur disque, expire après 5 minutes sans activité et est supprimé au plus tard 1 heure après sa dernière utilisation.
Chaque requête d’un thread doit inclure le header bêta anthropic-beta: message-threads-2026-08-12. Les tarifs et les limites de débit restent identiques : Claude relit l’intégralité de la conversation à chaque tour. Vous transmettez donc beaucoup moins d’octets, mais payez le même nombre de tokens en entrée et en sortie.
"Yeah nice, but it doesn't reduce tokens cost :( Claude still reads the entire conversation on every turn & token consumption remains unchanged" — @_navicstein, en réponse au thread officiel de lancement
L’annonce officielle évoque une baisse d’environ 35 % du TTFT médian sur les requêtes de 500K à 1M tokens, sans remise sur les tokens.
Threads et prompt caching : deux gains différents
Les threads réduisent ce que vous envoyez ; le prompt caching réduit la part que vous payez au tarif plein. Les threads n’activent aucun cache automatiquement : vous devez toujours définir vos points de coupure cache_control. Selon cette analyse d’implémentation, conservez un cache_control de premier niveau à chaque continuation ; les lectures de cache sont facturées à 0,1x du tarif d’entrée de base, ou 0,05x sur Claude Opus 5.5 et Sonnet 5.5.
Ne pas confondre avec les session threads des managed agents
Les résultats de recherche mélangent souvent deux notions de « threads ». Les Message Threads de l’API Messages, dont il est question ici, sont une optimisation éphémère de taille de requête, sans API pour lister, lire ou supprimer les threads. Les session threads des managed agents (GET /v1/sessions/{session_id}/threads/{thread_id}) sont des fils d’exécution au sein de l’API managed-agents d’Anthropic, avec des endpoints de liste, de récupération et d’archivage. Si la documentation parle de child threads, de flux d’événements ou d’archivage, vous n’êtes pas sur la bonne API. Consultez la référence API des session threads pour identifier l’interface dont vous avez besoin.
Cycle de vie d’un thread : création, suite et expiration
Un thread fonctionne en ajout uniquement : création avec le contexte complet, continuations avec les deltas, puis replay si l’état disparaît. Il n’existe ni branchement, ni modification, ni retour en arrière, ni API d’inspection. Chaque réponse renvoie un nouvel id, et chaque id ne peut servir qu’à une seule continuation. Les règles de champs et d’erreurs présentées ici suivent la documentation de la plateforme, détaillée dans cette analyse d’implémentation.
La création contient tout le contexte : messages, system et tools, ainsi que :
{
"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" }
}Une continuation ne transporte que les nouveautés, généralement un message utilisateur ou des blocs 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" }
}N’envoyez pas system ni tools lors d’une continuation : même "system": null provoque une erreur 400. En streaming, attendez message_stop avant de continuer ; l’ID de continuation exploitable arrive avec message_start.
Les champs modifiables, et ceux qui ne le sont pas
Anthropic calcule une empreinte sur une partie de la requête de création. Toute modification d’une valeur concernée renvoie thread_fingerprint_mismatch et impose de créer un nouveau thread.
| Catégorie | Exemples | Règle en continuation |
|---|---|---|
| Création uniquement | system, tools | Ne jamais les renvoyer ; null échoue également |
| Immuables | model, tool_choice, thinking, mcp_servers, context_management, output_config, container skills, gestion de cache_control au niveau supérieur | Doivent rester identiques |
| Libres | max_tokens, stop_sequences, stream, metadata, service_tier | Peuvent changer à chaque tour |
| À renvoyer systématiquement | URL / tokens d’authentification de serveur MCP, ID container | Non conservés côté serveur : incluez-les à chaque utilisation |
Les modèles avec extended thinking demandent une vigilance supplémentaire : modifier system ou tools peut invalider les blocs thinking / redacted_thinking précédents. Si un replay complet après expiration renvoie une erreur 400, retirez ces blocs thinking obsolètes de l’historique rejoué plutôt que de répéter la requête à l’identique.
La limite des 5 minutes et le replay à prévoir
Considérez les threads comme un mécanisme best effort : conservez localement l’historique complet, le system prompt, les outils et les références de fichiers. L’état n’est confirmé qu’après une continuation réussie. Les fichiers sont conservés par référence : supprimer un fichier pendant la vie du thread casse la continuation.
Le compteur d’expiration est réinitialisé à chaque réponse stockée. Après 5 minutes d’inactivité, la prochaine continuation renvoie 404 ; vous devez alors rejouer la conversation complète via un nouveau create. Les données sont supprimées au plus tard 1 heure après la dernière utilisation.
| HTTP | Code | Cause | Action |
|---|---|---|---|
| 404 | thread_not_found | Thread expiré, non stocké, mauvaise clé ou mauvais workspace, première image ajoutée à un thread texte seul, réponse servie par un modèle de fallback, ou réponse encore en cours de génération | Vérifiez clé, workspace et configuration, puis rejouez l’historique complet avec un nouveau create |
| 400 | thread_fingerprint_mismatch | Un champ immuable a changé | Rétablissez la valeur initiale ou démarrez un nouveau thread |
| 400 | thread_already_continued | Ce previous_message_id a déjà été utilisé | Partez du dernier id |
| 400 | thread_continue_in_flight | Continuation concurrente sur le même ID | Attendez sa fin, puis utilisez son nouvel ID ; sinon, rejouez |
| 400 | thread_unsupported_request | Paramètre non pris en charge, par exemple plus de 4 breakpoints de cache ou les batches | Retirez ce paramètre ou envoyez la requête sans thread |
D’après le résumé de la documentation, les requêtes de thread en échec sont traitées avant l’exécution du modèle : elles ne consomment donc aucun token et ne réinitialisent pas le délai d’expiration. Enregistrez de façon atomique le dernier ID de réponse réussi avant d’accepter le tour suivant, et rendez les replays idempotents lorsque les appels d’outils ont des effets de bord.
Structure de replay en Python : ne gérez ici que le thread_not_found vérifié ; les erreurs d’empreinte, de concurrence et de requête non prise en charge nécessitent chacune leur propre branche.
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"},
)Attention aux proxys qui font tourner les clés API
Comportement rapporté par des opérateurs, mais pas encore documenté officiellement : un thread est lié à l’organisation, au workspace et au credential qui l’a créé. Un relais qui alterne les clés API à chaque requête créera le thread avec la clé A puis tentera de le continuer avec la clé B. Le symptôme est identique à une expiration : 404 en boucle, suivi d’un replay complet, sans gain de latence.
"thread 绑定创建它的 key 和 workspace，换 key 会 404 thread_not_found。中转站轮换 key 会先吃 404 再全量重发。" — @ak12kpoot (note d’un développeur chinois sur le comportement des proxys)
Associez un thread à une seule clé, ou désactivez les threads sur les routes mutualisées.
Compatibilité, limites et intérêt de l’adoption immédiate
Les Message Threads sont disponibles sur la Claude API, Claude Platform on AWS, Anthropic-managed Google Cloud Claude Models et Claude in Microsoft Foundry. Tous les modèles couverts par la bêta sont compatibles ; aucune liste distincte de modèles autorisés ni liste d’attente n’est annoncée.
Pour planifier le déploiement, les exclusions sont plus importantes :
| Domaine | Statut |
|---|---|
| Amazon Bedrock | Non pris en charge |
| Message Batches | Non pris en charge : les éléments de thread batchés échouent |
| Endpoint de comptage des tokens | Non pris en charge : comptez vous-même l’historique complet |
| Compaction / context editing | Non pris en charge, sauf clear_thinking avec keep all |
| Zero data retention, HIPAA-ready, inference hooks | Non éligibles |
| API de gestion des threads | Aucune : impossible de lister, lire ou supprimer les threads |
Faut-il l’activer ?
- À utiliser dès maintenant : les agents de code actifs, les boucles computer-use avec captures d’écran, ou les flux riches en documents qui enchaînent des dizaines de tours avec moins de 5 minutes entre eux. Combinez-les au prompt caching et prévoyez un chemin de replay.
- À éviter pour l’instant : le chat au rythme humain, les workflows en pause, les pipelines batch, les charges ZDR/HIPAA ou les déploiements Bedrock.
- À combiner avec précaution : un
cache_controlau niveau supérieur sur chaque requête compte dans la limite de 4 breakpoints ; les breakpoints desystem/toolsdéfinis à la création sont de nouveau comptés à chaque continuation. Au-delà, vous obtenezthread_unsupported_request: consolidez vos breakpoints avant d’activer les deux mécanismes.
À lire aussi : guide des tarifs de l’API Claude 2026, guide de l’API Claude Skills.
FAQ
Quel header bêta et quel paramètre faut-il envoyer ?
Envoyez anthropic-beta: message-threads-2026-08-12 sur chaque requête du thread, ainsi que thread: { "type": "create" } au premier appel puis thread: { "type": "continue", "previous_message_id": "<last response id>" } pour les suivants.
Que se passe-t-il à l’expiration d’un thread ?
La continuation suivante renvoie 404 thread_not_found. Renvoyez l’ensemble des messages, avec les system/tools initiaux, dans un nouveau create. L’expiration intervient après 5 minutes d’inactivité et la suppression a lieu au plus tard 1 heure après la dernière utilisation.
Peut-on lister, inspecter ou supprimer des threads ?
Non. Les threads de l’API Messages n’ont aucune API de gestion. Votre historique local est le seul enregistrement durable.
Est-ce compatible avec Amazon Bedrock ?
Non. Les surfaces prises en charge sont la Claude API, AWS Claude Platform, Microsoft Foundry et Anthropic-managed Google Cloud. Les requêtes Bedrock doivent continuer à envoyer l’historique complet.
Peut-on modifier le system prompt ou les outils en cours de thread ?
Non. Créez un nouveau thread avec les nouveaux system/tools. Envoyer des valeurs modifiées lors d’une continuation déclenche thread_fingerprint_mismatch. Cela vaut aussi pour model, tool_choice et la configuration thinking.
Est-ce compatible avec le streaming, les outils et MCP ?
Oui, sous certaines conditions : attendez message_stop avant toute continuation, renvoyez les URL/tokens MCP et les ID container à chaque tour, et envoyez fallbacks à chaque requête ou à aucune. Une réponse produite par un modèle de fallback n’est pas stockée et doit être rejouée.