Changer les outils en cours de conversation
avec l'API Claude : le guide complet
La nouvelle bêta mid-conversation tool changes d'Anthropic permet d'ajouter ou retirer des outils entre les tours sans invalider le cache de prompt. Voici comment l'implémenter en Python.
La bêta mid-conversation tool changes de l'API Claude permet d'ajouter ou de retirer des outils entre les tours d'une conversation, sans invalider le cache de prompt. Il suffit d'inclure le header mid-conversation-tool-changes-2026-07-01 dans vos requêtes bêta, puis d'envoyer des messages système avec des blocs tool_addition ou tool_removal. La fonctionnalité est disponible sur Claude Fable 5, Mythos 5, Opus 4.8 et Opus 5, via l'API Anthropic, Amazon Bedrock et Google Cloud.
Avant cette bêta, modifier la liste des outils obligeait à reformuler la conversation entière et invalidait tout le cache de prompt, ce qui faisait exploser les coûts sur les agents longs. Ce nouveau mécanisme change la donne pour tous ceux qui construisent des workflows IA en plusieurs phases.
Il y a quelques semaines, je construisais un agent de veille SEO pour un client e-commerce toulousain. L'agent devait d'abord explorer les données Google Search Console, puis switcher vers des outils de rédaction pour produire des recommandations. Le problème : chaque fois que je changeais la liste des tools entre les phases, l'intégralité du cache de prompt sautait, et je payais trois fois le coût normal. J'avais contourné le problème avec un hack moche : je gardais tous les outils chargés en permanence, même ceux inutiles. Résultat : un contexte pollué et une latence en hausse.
Anthropic a depuis sorti une bêta qui résout exactement ce problème : les mid-conversation tool changes. Dans ce guide, je vous explique comment activer la bêta, structurer vos messages système avec les blocs tool_addition et tool_removal, préserver le cache, et éviter les pièges que j'ai rencontrés en production.
Pourquoi changer les outils en cours de conversation posait un problème coûteux ?
Dans l'API Claude classique, la liste des outils disponibles est déclarée une fois au moment de l'appel, dans le paramètre tools. Elle reste fixe pour toute la durée de la conversation. Si vous voulez en ajouter ou en retirer, la seule option était de relancer l'appel avec une nouvelle liste complète.
Ce n'est pas grave pour une conversation courte. Mais sur un agent qui gère 40 tours de conversation avec du contexte accumulé, c'est catastrophique. Tout changement dans les outils invalide le cache de prompt, ce qui force Claude à retokeniser l'historique entier. Sur un contexte de 100 000 tokens, le surcoût de tokenisation dépasse facilement 0,50 € par requête. Multipliez par 200 appels quotidiens : vous brûlez 100 € par jour pour rien.
Il y avait aussi un problème de qualité : garder des outils chargés alors qu'ils ne sont plus pertinents dans la phase courante bruite le raisonnement de Claude. Un outil « send_email » présent alors qu'on est en phase d'analyse peut provoquer des appels inopportuns. La solution propre était complexe : soit on sérialisait l'historique entre deux instances distinctes, soit on construisait des orchestrateurs maison. Bref, un vrai casse-tête d'ingénierie.
Ce que la bêta mid-conversation tool changes change concrètement
La bêta introduite par Anthropic en juillet 2026 résout le problème à la racine. Au lieu de modifier le paramètre tools de niveau supérieur (ce qui casse le cache), vous insérez des messages de type role: "system" dans le fil de conversation. Ces messages contiennent des blocs spéciaux : tool_addition pour ajouter un outil et tool_removal pour en retirer un.
Le principe fondamental : vous déclarez tous vos outils possibles au départ dans le paramètre tools initial. Ensuite, vous pilotez dynamiquement leur disponibilité via ces blocs mid-conversation. Claude lit les blocs dans l'ordre chronologique : un outil ajouté puis retiré n'est plus disponible. Un outil retiré puis réajouté est disponible à nouveau. La logique est cumulative et prévisible.
Du côté du cache, c'est la révolution silencieuse : puisque le paramètre tools de haut niveau ne change plus, le cache de prompt sur l'historique de la conversation est totalement préservé. Vous ne payez la tokenisation que pour les nouveaux tokens, pas pour l'historique existant. Sur un agent long, les économies sont substantielles. J'ai mesuré une réduction de 60 à 70% du coût de tokenisation sur mon agent de veille SEO.
Activer la bêta : le header à inclure dans vos requêtes Python
La bêta mid-conversation tool changes nécessite un header spécifique. Vous devez passer la chaîne mid-conversation-tool-changes-2026-07-01 dans le paramètre betas de l'appel. Sans ce header, les blocs tool_addition et tool_removal seront simplement ignorés par Claude sans erreur explicite, ce qui peut provoquer des comportements inattendus très difficiles à déboguer.
Avec le SDK Python officiel d'Anthropic, l'appel se fait via client.beta.messages.create() et non client.messages.create(). La différence est subtile mais bloquante : le client standard n'accepte pas le paramètre betas. Si vous utilisez directement l'API HTTP via requests, ajoutez l'en-tête anthropic-beta avec la valeur correspondante.
Si vous êtes sur Amazon Bedrock ou Google Cloud Vertex AI, la fonctionnalité est également disponible mais la façon de passer les paramètres bêta dépend du wrapper de chaque plateforme. Référez-vous à la documentation de la plateforme concernée. Pour tout ce qui suit, je me base sur le SDK Python direct d'Anthropic, qui est la voie la plus directe.
Exemple Python complet : changer les outils entre deux phases
Voici un exemple concret avec deux phases : une phase d'analyse (outils lecture seule) et une phase d'action (outil d'envoi d'email activé). Le passage de l'une à l'autre se fait via un message système mid-conversation, sans invalider le cache.
Notez que le paramètre tools=all_tools ne change pas entre les deux appels. C'est là toute la magie : le cache de prompt sur l'historique de la conversation est totalement préservé, même si les outils disponibles changent d'une phase à l'autre.
La structure JSON exacte des blocs tool_addition et tool_removal
Les blocs tool_addition et tool_removal s'insèrent dans le tableau content d'un message de type role: "system". Voici la structure JSON précise à respecter pour chaque bloc :
Pour un ajout d'outil : {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "nom_de_l_outil"}}. Pour un retrait d'outil : {"type": "tool_removal", "tool": {"type": "tool_reference", "name": "nom_de_l_outil"}}.
Quelques règles critiques à retenir. D'abord, l'attribut name doit correspondre exactement au nom déclaré dans le tableau tools initial – toute différence de casse ou de caractère provoque une erreur silencieuse. Ensuite, vous pouvez inclure plusieurs blocs dans le même message système : les blocs sont traités dans l'ordre du tableau content. Enfin, les deux types de blocs supportent cache_control pour du prompt caching, ce qui vous donne un contrôle fin sur ce qui est mis en cache.
Il y a une limite à connaître : 512 blocs tool_addition maximum par requête. Dans la pratique, c'est largement suffisant pour les cas d'usage courants. Si vous avez besoin de gérer des centaines d'outils dynamiquement, la feature Tool Search d'Anthropic est une approche complémentaire.
Prompt cache et tool changes : le duo qui réduit vos coûts API
Le vrai gain de cette bêta, c'est l'économie sur le prompt caching. Pour comprendre pourquoi, il faut saisir comment fonctionne le cache de prompt dans l'API Claude. Le cache est invalidé quand l'une des entrées du hachage change : le modèle, le système prompt, ou le tableau tools. Avant cette bêta, ajouter un outil dans tools changeait le tableau, donc invalidait le cache sur l'historique entier.
Avec les mid-conversation tool changes, vous ne touchez plus au tableau tools de haut niveau. Ce tableau reste identique du premier au dernier appel. Seuls des messages mid-conversation sont ajoutés, et ces messages ne font pas partie du hachage utilisé pour le cache du préfixe. Résultat : chaque nouveau tour profite du cache accumulé depuis le début de la conversation.
Sur des agents avec de longs contextes, cela peut représenter des économies très significatives. Les tokens mis en cache coûtent environ 10 fois moins cher que les tokens frais sur Claude Opus 5 (0,50 € pour 1 million de tokens en cache contre 5 € pour 1 million de tokens frais). Retrouvez tous mes autres guides et ressources dans mon guide Claude IA, qui recense les techniques que j'utilise en production.
3 cas d'usage concrets pour les mid-conversation tool changes
Agent de recherche multi-phases
Vous construisez un agent qui explore en phase 1 (outils de lecture : APIs web, base de données), puis synthétise en phase 2 (outil de rédaction uniquement). Sans mid-conversation tool changes, chaque changement de phase vous coûtait une retokenisation complète du contexte. Désormais, un simple message système suffit à activer ou désactiver les outils selon la phase.
Sécurisation progressive des droits
Dans un agent de gestion de contenu, vous voulez que Claude puisse lire librement, mais qu'il demande confirmation avant d'écrire ou de supprimer. Implémentez ça avec un tool_addition de l'outil « write_to_db » uniquement après validation utilisateur, puis tool_removal immédiat après usage. Le cache reste intact tout au long.
Pipeline de traitement de documents
Pour un pipeline qui ingère des documents puis les classe, vous activez d'abord les outils de parsing et extraction, puis vous les désactivez pour n'autoriser que l'outil de classification finale. C'est beaucoup plus propre que de tout exposer simultanément : Claude ne peut pas confondre les phases et le raisonnement reste focalisé.
Modèles compatibles et disponibilité en juillet 2026
Au moment où j'écris ces lignes, la bêta mid-conversation tool changes est disponible sur quatre modèles : Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 et Claude Opus 5. Elle n'est pas disponible sur Claude Sonnet 5 ni sur les modèles Haiku. Si vous essayez d'utiliser la bêta avec un modèle non compatible, vous obtiendrez une erreur explicite au niveau de l'API.
Côté plateformes, la bêta est disponible directement via l'API Anthropic, sur Amazon Bedrock et sur Google Cloud Vertex AI. Pour Bedrock et Vertex, il peut y avoir un décalage de quelques jours entre l'annonce et la disponibilité effective. Si vous n'obtenez pas d'erreur explicite mais que les blocs semblent ignorés, vérifiez la version de l'API et la documentation de la plateforme.
Concernant l'évolution de la bêta : Anthropic a l'habitude de passer ses bêtas en GA (generally available) assez rapidement une fois qu'elles sont stables. Je m'attends à ce que cette fonctionnalité devienne standard dans les prochains mois. Cela dit, le header bêta continuera à fonctionner même après le passage en GA pour des raisons de compatibilité ascendante.
Comparatif : ancienne approche vs mid-conversation tool changes
Pour décider si cette bêta vaut la migration pour votre projet, voici une comparaison honnête des deux approches sur les critères qui comptent en production.
| Critère | Ancienne approche (relancer tools) | Mid-conversation tool changes |
|---|---|---|
| Cache de prompt | Invalidé à chaque changement d'outils | Totalement préservé tout au long |
| Coût par requête | Retokenisation complète à chaque phase | Réduit de 60 à 70% sur agents longs |
| Complexité du code | Gestion manuelle des instances / historiques | Un seul fil de conversation continu |
| Qualité du raisonnement | Contexte pollué par les outils hors phase | Outil unique actif selon la phase |
| Disponibilité | Tous les modèles | Fable 5, Mythos 5, Opus 4.8, Opus 5 |
| Statut | GA (generally available) | Bêta (header requis) |
Verdict : si vous construisez des agents multi-phases avec des contextes longs (plus de 20 000 tokens d'historique), la migration vaut clairement le coût. Pour des agents courts ou des scripts simples, l'ancienne approche est suffisante.
Ce que les mid-conversation system messages ajoutent au tableau
La bêta mid-conversation tool changes s'accompagne d'une feature complémentaire déjà en GA (generally available, aucun header requis) : les mid-conversation system messages. Cette seconde feature vous permet de modifier les instructions système en cours de conversation, sans invalider le cache non plus.
Jusqu'ici, le système prompt était également fixe pour toute la durée de la conversation. Vouloir changer le ton, le rôle ou les contraintes de Claude en cours de route impliquait là encore de relancer l'appel avec un nouveau system de haut niveau. Avec les mid-conversation system messages, vous insérez un role: "system" avec un bloc text directement dans le tableau des messages, et Claude applique ces nouvelles instructions à partir de ce point.
En pratique, vous pouvez combiner les deux fonctionnalités dans le même message système : un bloc tool_addition, un bloc tool_removal et un bloc text avec de nouvelles instructions, tout dans un seul message. Le résultat : une transition de phase propre, préservant le cache, et recalibrant à la fois les outils et les instructions de l'agent.
Les 6 règles à respecter pour éviter les pièges en production
- 1Déclarez tous les outils au premier appel : tous les outils possibles doivent figurer dans le tableau
toolsinitial, même ceux que vous n'activez que plus tard. La bêta ne permet pas d'ajouter un outil qui n'a pas été déclaré au départ. - 2Utilisez client.beta.messages.create() : si vous passez par le SDK Python, le client standard
client.messages.create()n'accepte pas le paramètrebetas. Toujours appeler la version bêta, même pour les appels qui ne font pas de changement d'outils. - 3Vérifiez la casse exacte des noms d'outils : le champ
namedans les blocstool_additionettool_removalest sensible à la casse. « Search_GSC » et « search_gsc » sont deux outils différents. Une erreur de casse ne déclenche aucune exception et se manifeste par un comportement erratique. - 4Combinez les deux bêtas prudemment : si vous utilisez simultanément mid-conversation tool changes et d'autres bêtas (effort control, Managed Agents), passez tous les headers dans le même tableau
betas. Certaines combinaisons de bêtas peuvent générer des comportements inattendus. - 5Testez avec un outil factice avant la production : avant de déployer en prod, testez le mécanisme avec un outil stub qui ne fait rien (input schema minimal, retourne toujours « OK »). Cela vous permet de valider le flux de contrôle sans risquer d'appels réels à vos APIs.
- 6Anticipez la GA : la bêta deviendra probablement disponible sans header d'ici quelques mois. Encapsulez l'appel dans une fonction utilitaire pour pouvoir supprimer le header bêta en un seul endroit quand ce sera le cas.
Comment planifier la migration de vos agents existants
Si vous avez des agents en production qui changent leurs outils entre les phases, la migration vers la nouvelle bêta est relativement simple mais demande une planification rigoureuse. La première étape est d'identifier dans votre code tous les endroits où vous reconstituez le tableau tools ou relancez une conversation avec une liste d'outils différente.
Pour chaque point de transition, la migration suit le même schéma : consolider les outils des deux phases dans un seul tableau déclaré au premier appel, puis remplacer la logique de relancement par l'insertion d'un message système mid-conversation avec les blocs appropriés. Dans la majorité des cas, la migration prend moins d'une heure de développement, mais le gain en coût est immédiat et permanent.
Une précaution importante : si votre agent a des logiques de sécurité basées sur l'absence d'un outil dans la liste, vérifiez que la logique fonctionne toujours. Le fait que tous les outils soient déclarés au départ (même s'ils sont retirés via tool_removal) peut tromper des systèmes de monitoring qui vérifient la présence d'un outil dans la définition de haut niveau plutôt que dans son état effectif mid-conversation.
Limites connues et ce qu'Anthropic ne peut pas encore faire
La bêta a quelques limites à connaître avant de l'adopter. Premièrement, vous ne pouvez pas ajouter en mid-conversation un outil qui n'est pas dans le tableau tools initial. Si vous découvrez en cours d'exécution qu'un outil supplémentaire serait utile, vous devez soit l'avoir prévu au départ, soit démarrer une nouvelle conversation. Cette contrainte est volontaire et liée à l'architecture du cache.
Deuxièmement, la bêta n'est pas disponible sur Claude Sonnet 5 ni sur les modèles Haiku. Si votre architecture de coût repose sur Sonnet 5 comme modèle principal, vous ne pourrez pas profiter des mid-conversation tool changes pour l'instant. Espérons qu'Anthropic étende la compatibilité dans les prochaines mises à jour.
Troisièmement, la limite de 512 blocs tool_addition par requête est théoriquement contraignante si vous avez un très grand nombre d'outils dynamiques, mais en pratique elle est largement suffisante pour la quasi-totalité des cas d'usage. Si vous approchez de cette limite, c'est souvent le signe que votre architecture mérite d'être repensée avec la feature Tool Search.
Questions fréquentes sur les mid-conversation tool changes avec l'API Claude
Qu'est-ce que la bêta mid-conversation tool changes de l'API Claude ?+
La bêta mid-conversation tool changes est une fonctionnalité de l'API Claude lancée en juillet 2026 qui permet d'ajouter ou de retirer des outils disponibles pour Claude en cours de conversation, sans invalider le cache de prompt sur l'historique déjà accumulé. Concrètement, vous insérez des messages de type role: "system" contenant des blocs tool_addition ou tool_removal au fil de la conversation.
Avant cette bêta, tout changement dans la liste des outils obligeait à reconstruire la conversation depuis le début, ce qui détruisait les bénéfices du prompt caching. La bêta résout ce problème en découplant la liste des outils disponibles (qui reste stable dans tools) de leur activation effective (gérée via des messages mid-conversation). Le résultat est une réduction sensible des coûts sur les agents longs et multi-phases.
Comment activer la bêta mid-conversation tool changes en Python ?+
Pour activer la bêta, vous devez utiliser client.beta.messages.create() (et non client.messages.create()) et inclure la chaîne "mid-conversation-tool-changes-2026-07-01" dans le paramètre betas, sous forme de liste. Par exemple : betas=["mid-conversation-tool-changes-2026-07-01"]. Si vous passez par l'API HTTP directement, ajoutez l'en-tête anthropic-beta: mid-conversation-tool-changes-2026-07-01.
Sans ce header, les blocs tool_addition et tool_removal dans vos messages sont silencieusement ignorés par Claude. Il n'y a pas d'erreur explicite, ce qui rend le débogage difficile. Vérifiez toujours que le header est bien présent si les changements d'outils ne semblent pas avoir d'effet.
Quelle est la structure JSON exacte d'un bloc tool_addition ?+
Un bloc tool_addition s'insère dans le tableau content d'un message role: "system". Sa structure est la suivante : {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "nom_de_l_outil"}}. De même pour un retrait : {"type": "tool_removal", "tool": {"type": "tool_reference", "name": "nom_de_l_outil"}}. Le champ name doit correspondre exactement au nom déclaré dans le tableau tools initial.
Vous pouvez combiner plusieurs blocs dans le même message, aux côtés de blocs text optionnels pour expliquer à Claude le changement de phase. Les blocs sont traités dans l'ordre du tableau. Vous pouvez également ajouter cache_control sur chaque bloc pour contrôler finement la mise en cache.
Sur quels modèles Claude la bêta est-elle disponible ?+
En juillet 2026, la bêta mid-conversation tool changes est disponible sur quatre modèles : Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 et Claude Opus 5. Elle n'est pas disponible sur Claude Sonnet 5, ni sur les modèles Haiku. Si vous tentez de l'utiliser avec un modèle non compatible, vous obtiendrez une erreur explicite au moment de la requête.
Les plateformes supportées sont l'API Anthropic directe, Amazon Bedrock et Google Cloud Vertex AI. Pour Bedrock et Vertex, un léger décalage peut exister entre l'annonce et la disponibilité effective. Consultez la documentation de la plateforme concernée pour vérifier la disponibilité à jour.
Peut-on ajouter un outil qui n'était pas dans la liste initiale ?+
Non. La bêta mid-conversation tool changes ne permet pas d'ajouter dynamiquement un outil qui n'est pas déclaré dans le tableau tools initial. Tous les outils susceptibles d'être utilisés à un moment ou l'autre de la conversation doivent être déclarés dès le premier appel. Vous pilotez ensuite leur disponibilité via les blocs tool_addition et tool_removal.
Cette contrainte est liée à l'architecture du cache de prompt : le hachage du cache inclut la définition complète des outils. Si vous ajoutiez une nouvelle définition d'outil mid-conversation, cela invaliderait le cache, annulant le principal bénéfice de la bêta. Si vous avez besoin d'un pool d'outils très dynamique, explorez plutôt la feature Tool Search d'Anthropic.
Quelle économie réelle peut-on espérer sur les coûts API ?+
Sur mon agent de veille SEO (contexte moyen de 80 000 tokens, 3 phases distinctes, 200 appels par jour), la migration a réduit le coût de tokenisation de 62%. Avec Claude Opus 5, les tokens mis en cache coûtent 0,50 € par million contre 5 € par million en tokens frais. Sur un contexte long, l'économie par requête est donc d'environ 4,50 € par million de tokens d'historique récupérés du cache.
L'économie effective dépend de la longueur de votre contexte et du nombre de changements de phases. Plus votre agent est long et plus il change souvent d'outils, plus le gain est important. Pour un agent court de moins de 5 tours et 10 000 tokens de contexte, le gain est marginal et ne justifie pas la complexité supplémentaire.
Les mid-conversation system messages et tool changes sont-ils liés ?+
Les deux fonctionnalités sont complémentaires mais indépendantes. Les mid-conversation system messages (modifications du prompt système en cours de conversation) sont déjà en GA et ne nécessitent aucun header bêta. Les mid-conversation tool changes (activation/désactivation d'outils) sont en bêta et nécessitent le header spécifique. Vous pouvez utiliser l'une sans l'autre.
En pratique, elles s'utilisent souvent ensemble : dans un message système mid-conversation, vous incluez à la fois un bloc text (nouvelles instructions) et des blocs tool_addition/tool_removal (nouveaux outils). Cela vous permet de piloter simultanément le comportement et les capacités de Claude d'une phase à l'autre, sans jamais invalider le cache.
La bêta va-t-elle passer en GA prochainement ?+
Anthropic n'a pas communiqué de date précise pour le passage en GA de cette bêta. Cela dit, l'historique des bêtas Anthropic est encourageant : la majorité des bêtas annoncées ces deux dernières années sont passées en GA dans un délai de 2 à 4 mois. Les mid-conversation system messages, fonctionnalité parallèle, sont passées en GA rapidement après leur bêta. Je m'attends à un calendrier similaire.
La bonne pratique pour anticiper le passage en GA est d'encapsuler tous vos appels bêta dans une fonction utilitaire avec le header bêta en paramètre optionnel. Quand Anthropic annoncera le passage en GA, une seule modification dans votre code suffira à retirer le header sans impact sur le comportement.
Comment debugger quand les changements d'outils ne semblent pas s'appliquer ?+
Si Claude continue d'appeler un outil que vous avez retiré, ou n'utilise pas un outil que vous avez ajouté, vérifiez ces points dans l'ordre. Premièrement : le header bêta est-il bien présent dans tous vos appels ? Deuxièmement : utilisez-vous bien client.beta.messages.create() et non client.messages.create() ? Troisièmement : le nom de l'outil dans le bloc correspond-il exactement au nom dans tools ?
Si les trois points sont corrects, ajoutez un outil factice très simple et vérifiez que son ajout mid-conversation fait bien apparaître des appels à cet outil dans la réponse suivante. Si même ça ne fonctionne pas, vérifiez la version du SDK Python : les bêtas récentes peuvent nécessiter une version mise à jour. La commande pip install --upgrade anthropic règle souvent le problème.
Peut-on utiliser cette bêta avec les Managed Agents d'Anthropic ?+
Oui, avec des précautions. Les Managed Agents d'Anthropic ont leur propre gestion du cycle de vie des outils et peuvent avoir des contraintes sur les headers bêta compatibles. En pratique, la combinaison fonctionne sur les modèles compatibles (Fable 5, Mythos 5, Opus 4.8, Opus 5), mais il est recommandé de tester d'abord en environnement de développement avant de déployer en production.
Une alternative dans l'écosystème Managed Agents est d'utiliser la configuration par session (agent_with_overrides) pour remplacer la liste d'outils d'un agent pour une session donnée, sans modifier la configuration de base de l'agent. Ces deux approches sont complémentaires et couvrent des besoins légèrement différents.
