Messages système en milieu de conversation et modifications d'outils

Les instructions système se trouvent normalement dans le champ system de niveau supérieur, avant chaque message de la conversation. Cette position est idéale pour le « prompt caching » (mise en cache des prompts) : l'invite système fait partie du préfixe stable, de sorte que les tours suivants atteignent le cache. C'est une mauvaise position pour les instructions dont vous ne découvrez le besoin qu'en cours de session, car modifier le champ system de niveau supérieur change le tout début du prompt et invalide le cache pour tout ce qui suit.

Les messages système en milieu de conversation comblent cette lacune. Vous ajoutez un message {"role": "system"} au point de la conversation où la nouvelle instruction devient pertinente, au lieu de modifier le champ system de niveau supérieur. Le préfixe mis en cache reste le même, de sorte que la requête suivante le lit toujours depuis le cache, et la nouvelle instruction est toujours appliquée en tant qu'instruction système plutôt que comme du texte utilisateur ordinaire.

Cette page couvre deux fonctionnalités : les messages système en milieu de conversation, qui sont disponibles de manière générale, et les modifications d'outils en milieu de conversation, une bêta introduite avec Claude Opus 5 qui applique la même approche au tableau tools.



Modifications d'outils en milieu de conversation

Le tableau tools se situe encore plus tôt dans le préfixe haché de la requête que le champ system de niveau supérieur, donc le modifier invalide le cache de prompts pour l'ensemble de la conversation. Les modifications d'outils en milieu de conversation, une bêta introduite avec Claude Opus 5, sont l'équivalent pour les outils des messages système en milieu de conversation. Au lieu de figer la liste d'outils pour toute la durée de vie de la conversation, vous changez quels outils sont proposés au modèle entre les tours : déclarez l'ensemble complet des outils dans tools dès le départ, puis utilisez des blocs tool_addition et tool_removal pour proposer un outil au modèle, ou le retirer, à partir d'un point spécifique de la conversation. Le tableau tools lui-même ne change jamais, donc le préfixe mis en cache reste intact.

tool_addition et tool_removal sont des blocs de contenu dans le tableau content d'un message role: "system", et ils peuvent être mélangés avec des blocs text dans le même message. Le message suit les mêmes règles de placement que tout message système en milieu de conversation (voir Limitations), et la modification s'applique à partir de ce point de la conversation. Le champ tool de chaque bloc référence un outil plutôt que d'en définir un : {"type": "tool_reference", "name": "..."} nomme un outil déclaré dans le tableau tools de la requête, et les outils du connecteur MCP peuvent être référencés individuellement avec mcp_tool_reference (server_name et name) ou en tant qu'ensemble d'outils complet avec mcp_toolset_reference (server_name). Référencer un nom qui n'est pas déclaré dans tools renvoie une erreur 400.

Chaque outil déclaré dans tools est proposé au modèle dès le début de la conversation, sauf s'il est déclaré avec defer_loading: true, ce qui le maintient en retrait jusqu'à ce qu'un bloc tool_addition le fasse apparaître. tool_addition propose également à nouveau un outil qu'un tool_removal antérieur avait retiré.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    # L'ensemble complet d'outils est déclaré dès le départ et ne change jamais, donc le
    # préfixe mis en cache reste intact.
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                },
                "required": ["location"],
            },
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Say OK.",
        },
        # Retire get_weather à partir de ce point. Le bloc référence
        # l'outil par son nom au lieu de modifier `tools`, donc les tours précédents restent
        # identiques octet pour octet et le cache fonctionne toujours.
        {
            "role": "system",
            "content": [
                {
                    "type": "tool_removal",
                    "tool": {"type": "tool_reference", "name": "get_weather"},
                },
            ],
        },
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Les modifications d'outils en milieu de conversation sont en bêta. Pour les utiliser, incluez l'en-tête bêta mid-conversation-tool-changes-2026-07-01 dans vos requêtes. Elles sont disponibles sur Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 et Claude Opus 5, sur l'API Claude, Amazon Bedrock et Google Cloud.



Quand utiliser un message système en milieu de conversation

La mise en cache des prompts hache le préfixe de la requête dans l'ordre : tools, puis system, puis messages. Un succès de cache (cache hit) exige que le préfixe corresponde exactement à une requête récente, octet par octet, jusqu'au point de rupture du cache.

Cet ordre signifie que le champ system de niveau supérieur se situe tout près du début du préfixe haché. Toute modification de celui-ci, même l'ajout d'une phrase, produit un hachage différent, et la requête manque le cache pour l'invite système et chaque message mis en cache qui la suit.

Les messages système en milieu de conversation vous permettent d'ajouter l'instruction à la fin de l'historique des messages à la place. Tout ce qui précède la nouvelle instruction est inchangé, donc l'entrée de cache existante correspond toujours, et seul le nouveau message est traité comme une entrée fraîche.

Quelques situations où cela compte :

• Changements de politique ou de persona en cours de session. Une longue session agentique a besoin d'une nouvelle contrainte (« à partir de maintenant, écrivez toutes les requêtes SQL sous forme de requêtes paramétrées ») après des dizaines de tours mis en cache. L'ajouter au champ system de niveau supérieur retraiterait l'historique entier.
• Contexte par tour qui doit faire autorité. Vous voulez injecter une note de fraîcheur, une échéance de session ou un changement de disponibilité d'outil avec un poids de niveau système, et cela change trop souvent pour résider dans le préfixe mis en cache.
• Changements d'état que votre application observe. Votre application remarque quelque chose que Claude devrait traiter comme un fait de niveau opérateur : des fichiers ont changé sur le disque, l'utilisateur a basculé un paramètre d'approbation automatique, les outils disponibles ont changé, ou le budget de tokens restant est passé sous un seuil.
• Entrée utilisateur qui ne devrait pas interrompre une boucle agentique. Un utilisateur tape un suivi pendant que Claude exécute encore des outils pour la requête précédente. Le relayer en tant que message système après le prochain résultat d'outil permet à Claude d'intégrer la nouvelle entrée dans le travail qu'il effectue déjà, au lieu de la traiter comme une nouvelle requête vers laquelle basculer. Voir Placement après les résultats d'outils ci-dessous.
• Changements de mode qui accordent des permissions permanentes. Un mode au niveau de la session peut utiliser un message système en milieu de conversation pour accorder un consentement permanent à une capacité coûteuse, comme le lancement automatique de flux de travail multi-agents, avec un bref rappel tous les quelques tours et un avis de sortie lorsque le mode est désactivé. Pour un exemple détaillé, voir Construire un mode d'orchestration.

Dans tous ces cas, vous pourriez placer l'instruction dans un message user ordinaire, et Claude suit effectivement les instructions qui arrivent dans les tours utilisateur. La différence est la priorité : un message user est traité comme provenant de l'utilisateur final, tandis qu'un message system est traité comme provenant de vous, l'opérateur de l'application. Lorsque les deux entrent en conflit, les instructions système ont la priorité, donc utilisez le rôle system pour les faits et contraintes de niveau opérateur qui doivent tenir même si l'utilisateur final demande quelque chose de différent. Un message système en milieu de conversation conserve cette priorité de niveau opérateur sans payer le coût d'un échec de cache lié à la modification du champ system de niveau supérieur.



Comment ça fonctionne

Ajoutez un message avec "role": "system" au tableau messages. Utilisez une chaîne simple ou des blocs de contenu pour content, de la même manière qu'un tour user ou assistant. L'instruction s'applique à partir de ce point de la conversation. Lorsque des instructions entrent en conflit, les messages système ultérieurs ont la priorité sur les précédents, et les messages système en milieu de conversation ont la priorité sur le champ system de niveau supérieur pour les tours qui les suivent.

Vous pouvez toujours définir le champ system de niveau supérieur pour les instructions qui doivent s'appliquer à l'ensemble de la conversation. Réservez les messages système en milieu de conversation aux instructions qui ne deviennent pertinentes que plus tard, ou que vous souhaitez ajouter sans invalider le préfixe mis en cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # Mise en cache automatique des prompts : chaque requête met en cache la conversation en cours,
    # et la requête suivante lit le préfixe inchangé depuis le cache.
    cache_control={"type": "ephemeral"},
    system="You are a code review assistant. Be concise.",
    messages=[
        {
            "role": "user",
            "content": "Review process() in utils.py for performance issues.",
        },
        {
            "role": "assistant",
            "content": "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.",
        },
        {
            "role": "user",
            "content": "Now review the calling code that invokes process().",
        },
        # Le relecteur se rend compte en cours de session que toutes les suggestions doivent
        # aussi respecter la politique de typage strict de l'équipe. Ajouter
        # l'instruction ici garde les tours précédents identiques à l'octet près, donc le
        # préfixe mis en cache par la requête précédente est toujours lu depuis le cache.
        {
            "role": "system",
            "content": "From now on, every suggestion must include explicit type annotations.",
        },
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Cet exemple active la mise en cache automatique avec le champ cache_control de niveau supérieur. La mise en cache des prompts est optionnelle : si une requête n'a pas de champ cache_control (automatique ou un point de rupture explicite), rien n'est mis en cache et chaque requête paie le prix normal des tokens d'entrée pour la conversation complète. Avec la mise en cache activée, l'ajout du message système laisse les tours déjà mis en cache inchangés, de sorte que la requête qui porte la nouvelle instruction les lit toujours depuis le cache au lieu de les traiter à nouveau. La mise en cache exige également que la conversation atteigne la longueur minimale de prompt pouvant être mise en cache ; un exemple aussi court que celui-ci se situe en dessous, donc cache_creation_input_tokens et cache_read_input_tokens restent à 0 jusqu'à ce que la conversation grandisse.

Un message système en milieu de conversation doit immédiatement suivre un tour user (ou un tour assistant se terminant par un résultat d'outil serveur), et doit soit être la dernière entrée dans messages, soit être immédiatement suivi d'un tour assistant. Un message user qui porte des blocs tool_result compte : dans une boucle agentique, vous pouvez placer le message système juste après les résultats d'outils, avant le prochain tour de Claude. Toute autre position, y compris entre un bloc tool_use d'un assistant et le tool_result qui y répond, renvoie une erreur 400.



Placement après les résultats d'outils

Dans une boucle agentique, le message système va après le message user qui livre les résultats d'outils. C'est aussi là que votre application peut relayer une entrée que l'utilisateur a tapée pendant que Claude travaillait, de sorte que le nouveau contexte est absorbé sans redémarrer le tour :

[
  { "role": "user", "content": "Run the test suite and fix any failures." },
  {
    "role": "assistant",
    "content": [{ "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 passed, 0 failed" }
    ]
  },
  {
    "role": "system",
    "content": "The user sent the following message while you were working: also update the changelog before you finish."
  }
]

Formulez le contenu système comme du contexte plutôt que comme une commande qui outrepasse l'utilisateur. Énoncez le fait (« une nouvelle entrée est arrivée de l'utilisateur : X », « le budget de tokens restant est maintenant Y ») et laissez Claude agir en conséquence. Claude est entraîné à résister aux instructions qui semblent aller à l'encontre de l'utilisateur, et cette protection s'applique toujours au rôle système, donc un langage tel que « ignorez ce que l'utilisateur a dit » est moins efficace que d'énoncer ce qui a changé.

Ce modèle sert à relayer l'entrée de l'utilisateur final de la conversation elle-même. Ne l'utilisez pas pour transmettre des sorties d'outils, des documents récupérés ou d'autres contenus tiers ; conservez ce contenu dans des blocs tool_result (voir Limitations).



Combinaison avec la mise en cache des prompts

Les messages système en milieu de conversation et la mise en cache des prompts sont conçus pour être utilisés ensemble :

• Activez la mise en cache explicitement. La mise en cache ne se produit que lorsque la requête inclut cache_control, soit le champ de mise en cache automatique de niveau supérieur, soit un point de rupture explicite sur un bloc de contenu. Un message système en milieu de conversation ne crée pas d'entrée de cache par lui-même, et sans mise en cache activée, il n'y a pas d'économies à préserver.
• Mettez en cache le préfixe stable comme d'habitude. Placez cache_control sur le dernier bloc qui reste identique d'une requête à l'autre, que ce soit la fin du champ system de niveau supérieur, la fin de vos définitions d'outils, ou un point stable dans l'historique des messages.
• Ajoutez le message système après le point de rupture. Parce qu'il vient après le préfixe mis en cache, il ne change pas le hachage du préfixe et le cache est toujours atteint.
• Un message système en milieu de conversation est lui-même pouvant être mis en cache. Une fois qu'il est dans la conversation, il devient partie intégrante de l'historique stable. Au tour suivant, vous pouvez déplacer votre point de rupture de cache au-delà de celui-ci (ou vous fier à la mise en cache automatique pour le faire) et le message système est lu depuis le cache comme tout autre tour.

Évitez de modifier ou de supprimer un message système en milieu de conversation qui a déjà été envoyé. Comme tout autre changement apporté à des messages antérieurs, cela invalide le cache à partir de ce point. Si l'instruction doit évoluer, ajoutez un nouveau message système plutôt que de réécrire l'ancien. Les messages système consécutifs sont acceptés et traités comme une seule section système, qui suit la même règle de placement dans son ensemble.



Limitations

• Pas pour le premier message. Un message system ne peut pas être la première entrée dans messages. Utilisez le champ system de niveau supérieur pour les instructions qui s'appliquent dès le tout début.
• Le placement est contraint. Un message system doit immédiatement suivre un tour user (y compris un tour user qui porte des blocs tool_result) ou un tour assistant se terminant par un résultat d'outil serveur, et doit précéder un tour assistant ou terminer le tableau. Il ne peut pas se situer entre un bloc tool_use et son tool_result. Le placer ailleurs renvoie une erreur 400.
• Pas un endroit pour du contenu non fiable. Claude traite le contenu système comme des instructions d'opérateur et les suit. Ne placez pas de texte provenant de l'extérieur de la conversation, tel que des sorties d'outils brutes, des documents récupérés ou du contenu web, directement dans un message système ; cela donnerait à ce texte une autorité de niveau opérateur. Conservez ces données dans des blocs tool_result et continuez à suivre Atténuer les jailbreaks et les injections de prompts.



Ressources connexes