Messages système et changements d'outils en cours de conversation

Les instructions système résident normalement dans le champ system de premier niveau, 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 en revanche une mauvaise position pour les instructions dont vous ne découvrez le besoin qu'au milieu d'une session, car modifier le champ system de premier niveau change le tout début du prompt et invalide le cache pour tout ce qui suit.

Les « mid-conversation system messages » (messages système en cours de conversation) comblent cette lacune. Vous ajoutez un message {"role": "system"} à l'endroit de la conversation où la nouvelle instruction devient pertinente, au lieu de modifier le champ system de premier niveau. Le préfixe mis en cache reste identique, de sorte que la requête suivante le lit toujours depuis le cache, et la nouvelle instruction est tout de même appliquée en tant qu'instruction système plutôt qu'en tant que texte utilisateur ordinaire.

Changements d'outils en cours de conversation

Le tableau tools se situe encore plus tôt dans le préfixe de requête haché que le champ system de premier niveau, de sorte que le modifier invalide le cache de prompts pour l'ensemble de la conversation. Les « mid-conversation tool changes » (changements d'outils en cours de conversation) sont l'équivalent, pour les outils, des messages système en cours de conversation. Au lieu de figer la liste d'outils pour toute la durée de la conversation, vous modifiez les outils 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 précis de la conversation. Le tableau tools lui-même ne change jamais, de sorte que 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 combiné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 cours de conversation (voir Limitations), et le changement s'applique à partir de ce point de la conversation. Le champ tool de chaque bloc référence un outil plutôt que de le définir : {"type": "tool_reference", "name": "..."} désigne 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 des 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.",
        },
        # Retirer 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 par 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 changements d'outils en cours 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.

Quand utiliser un message système en cours 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 exige que le préfixe corresponde exactement, octet par octet, à une requête récente, jusqu'au point d'arrêt du cache.

Cet ordre signifie que le champ system de premier niveau se trouve 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 pour chaque message mis en cache après elle.

Les messages système en cours 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 reste inchangé, de sorte que l'entrée de cache existante correspond toujours, et seul le nouveau message est traité comme une entrée nouvelle.

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 tout le SQL sous forme de requêtes paramétrées ») après des dizaines de tours mis en cache. L'ajouter au champ system de premier niveau retraiterait l'intégralité de l'historique.
• Contexte par tour qui doit faire autorité. Vous souhaitez injecter une note de fraîcheur, une échéance de session ou un changement de disponibilité d'outils avec un poids de niveau système, et cela change trop souvent pour résider dans le préfixe mis en cache.
• Rappels par tour qui ne doivent pas s'accumuler. Un harnais relance le modèle après chaque lot de résultats d'outils (« demandez les lectures indépendantes ensemble », « l'utilisateur n'a pas eu de nouvelles de vous depuis un moment ») et souhaite que le modèle ne voie que la copie la plus récente. Un message système limité au tour s'affiche pendant un tour puis ne coûte plus rien, sans rien supprimer de l'historique.
• Changements d'état observés par votre application. 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 jetons restant est passé sous un seuil.
• Saisie utilisateur qui ne doit pas interrompre une boucle agentique. Un utilisateur saisit une relance alors que Claude exécute encore des outils pour la requête précédente. La relayer sous forme de message système après le prochain résultat d'outil permet à Claude d'intégrer la nouvelle saisie au 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.
• Changements de mode qui accordent des autorisations permanentes. Un mode de niveau session peut utiliser un message système en cours 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é, consultez 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 tient à 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 sont en conflit, les instructions système prévalent ; utilisez donc le rôle system pour les faits et contraintes de niveau opérateur qui doivent tenir même si l'utilisateur final demande autre chose. Un message système en cours de conversation conserve cette priorité de niveau opérateur sans payer le coût d'échec de cache lié à la modification du champ system de premier niveau.

Fonctionnement

Ajoutez un message avec "role": "system" au tableau messages. Utilisez une chaîne simple ou des blocs de contenu pour content, comme pour un tour user ou assistant. L'instruction s'applique à partir de ce point de la conversation. Lorsque des instructions sont en conflit, les messages système ultérieurs prévalent sur les précédents, et les messages système en cours de conversation prévalent sur le champ system de premier niveau pour les tours qui les suivent.

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

Un message role: "system" peut également porter output_config.effort pour modifier le niveau d'effort à partir du prochain tour user. Ceci est en bêta sur Claude Fable 5.1, Claude Mythos 5.1 et Claude Opus 5 sur la Claude API et nécessite l'en-tête bêta mid-conversation-output-config-2026-07-01. Voir Effort par message.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # Mise en cache des prompts automatique : chaque requête met en cache la conversation jusqu'ici,
    # 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 réalise 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 premier niveau. La mise en cache des prompts est facultative : si une requête ne comporte aucun champ cache_control (automatique ou un point d'arrêt explicite), rien n'est mis en cache et chaque requête paie le prix normal des jetons d'entrée pour l'intégralité de la conversation. 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, de sorte que cache_creation_input_tokens et cache_read_input_tokens restent à 0 jusqu'à ce que la conversation s'allonge.

Un message système en cours de conversation doit suivre immédiatement 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 de 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'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 se place après le message user qui fournit les résultats d'outils. C'est également là que votre application peut relayer une saisie que l'utilisateur a tapée pendant que Claude travaillait, afin que le nouveau contexte soit 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 un contexte plutôt que comme une commande qui passe outre l'utilisateur. Énoncez le fait (« une nouvelle saisie est arrivée de l'utilisateur : X », « le budget de jetons restant est maintenant de 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, de sorte qu'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 la saisie 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).

Messages système limités au tour

Pour limiter un message role: "system" au tour en cours, définissez son champ clear_at. Il prend l'une de deux valeurs :

• "never" (la valeur par défaut) : le message s'affiche à sa position sur chaque requête qui l'inclut. Omettre le champ est identique.
• "next_user_message" : le message est « turn-scoped » (limité au tour). Son texte ne s'affiche que tant qu'aucun message role: "user" ne vient après lui dans messages. Un message utilisateur qui ne porte que des blocs tool_result compte ici comme un message utilisateur. Dès qu'un message utilisateur ultérieur existe, le message est effacé : il reste dans le tableau mais n'affiche rien et ne coûte aucun jeton d'entrée, sur cette requête et sur toutes les suivantes.

Les messages système limités au tour sont en bêta. Incluez l'en-tête bêta mid-conversation-system-clear-at-2026-08-21. Sans lui, clear_at est rejeté comme champ inconnu.

{
  "role": "system",
  "clear_at": "next_user_message",
  "content": "First privately list what you need next; then request every item that doesn't depend on another's result in this one response."
}

L'usage principal est un rappel par tour dans une boucle d'outils. Ajoutez le rappel après le message tool_result chaque fois que vous souhaitez que le modèle le voie, et laissez chaque copie antérieure là où elle se trouve. Le modèle ne voit que les copies qui viennent après le dernier message utilisateur, de sorte que le rappel ne s'accumule jamais. Rien de ce qui précède dans messages ne change, de sorte que le cache de prompts continue de correspondre. Sur Claude Fable 5.1, cela maintient également la validité des blocs de réflexion ultérieurs : supprimer un rappel antérieur modifierait la conversation avant ces blocs et ferait échouer la vérification de conversation, tandis qu'un message effacé reste dans le tableau et laisse cette conversation inchangée.

La requête suivante est une étape ultérieure d'une boucle d'agent. messages[3] s'est affiché lors de la requête précédente, lorsqu'il était le dernier message du tableau. Dès que messages[5] (un message utilisateur ultérieur) existe, messages[3] est effacé : le message effacé reste dans le tableau, de sorte que la conversation avant le bloc de réflexion dans messages[4] est inchangée, mais le modèle ne voit plus son texte. messages[6] et messages[7] s'affichent tous deux, dans l'ordre.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "messages": [
    { "role": "user", "content": "Fix the failing test." },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "", "signature": "..." },
        {
          "type": "tool_use",
          "id": "toolu_01",
          "name": "read_file",
          "input": { "path": "test_auth.py" }
        }
      ]
    },
    {
      "role": "user",
      "content": [{ "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." }]
    },
    {
      "role": "system",
      "clear_at": "next_user_message",
      "content": "Request independent reads in one turn."
    },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "", "signature": "..." },
        {
          "type": "tool_use",
          "id": "toolu_02",
          "name": "read_file",
          "input": { "path": "auth.py" }
        },
        {
          "type": "tool_use",
          "id": "toolu_03",
          "name": "read_file",
          "input": { "path": "tokens.py" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        { "type": "tool_result", "tool_use_id": "toolu_02", "content": "..." },
        {
          "type": "tool_result",
          "tool_use_id": "toolu_03",
          "content": "...",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    {
      "role": "system",
      "clear_at": "next_user_message",
      "content": "Request independent reads in one turn."
    },
    {
      "role": "system",
      "clear_at": "next_user_message",
      "content": "The shell exited with status 137."
    }
  ]
}

Règles pour les messages limités au tour :

• Renvoyez les messages effacés à l'identique. Un message effacé fait toujours partie de l'historique de la conversation. Le reconstruire à partir de l'état actuel (un nouveau décompte de jetons, un horodatage), le supprimer comme redondant ou modifier sa valeur clear_at constitue une modification d'un message antérieur. Le cache de prompts échoue à partir de ce point, et sur Claude Fable 5.1, chaque bloc de réflexion produit après lui échoue à la vérification de conversation.
• Texte uniquement. content est un ou plusieurs blocs text (ou une chaîne). Les blocs tool_addition et tool_removal renvoient une erreur 400 sur un message limité au tour, de même que output_config. Utilisez un message role: "system" distinct sans clear_at pour ceux-ci.
• Pas de cache_control sur ses blocs. Un message effacé ne fait jamais partie d'une clé de cache, de sorte qu'un point d'arrêt placé dessus ne pourrait jamais correspondre. Placez plutôt le point d'arrêt sur le dernier bloc du tour utilisateur précédent, comme le fait l'exemple. Le champ de mise en cache automatique de premier niveau ignore les messages limités au tour lorsqu'il choisit un point d'arrêt. Sur la requête qui efface un message, le préfixe mis en cache réutilisable se termine au tour utilisateur qui le précède, de sorte que seul le tour assistant situé entre ce message et le nouveau message utilisateur est retraité.
• Les règles de placement s'appliquent toujours, effacé ou non. Un message limité au tour doit suivre un tour user (ou un tour assistant se terminant par un résultat d'outil serveur) et précéder un tour assistant ou terminer le tableau, comme tout message système en cours de conversation. Un message qui termine le tableau s'affiche toujours. Un message suivi directement d'un autre message user est une erreur 400, et non un message effacé : placez tous les résultats d'un cycle d'outils dans un seul message utilisateur et les rappels après celui-ci.
• Les tours assistant ne l'effacent pas. Un tour assistant prérempli ou mis en pause après le message, ou une boucle d'outils côté serveur, n'ajoute aucun message utilisateur, de sorte que le message s'affiche toujours sur cette continuation. Pour garder un rappel visible tout au long d'une boucle d'outils côté client, ajoutez-le à nouveau après chaque message tool_result.
• Le comptage des jetons suit ce qui s'affiche. Un message effacé n'ajoute rien à usage.input_tokens ni à un décompte de jetons.
• Historique importé. Dans une transcription que vous construisez en une seule étape (exemples few-shot, conversation migrée), un message limité au tour qui a déjà un tour assistant et un message utilisateur après lui est effacé dès la première requête et ne s'affiche jamais. C'est l'état correct pour un rappel par tour que vous reportez. Ne laissez clear_at non défini que sur un message que le modèle doit voir à chaque requête.

Les erreurs de validation sont :

messages.3.clear_at: Extra inputs are not permitted
messages.3.clear_at: clear_at is only permitted on role 'system' messages
messages.3.clear_at: Input should be 'next_user_message' or 'never'
messages.3: a turn-scoped system message supports text blocks only (clear_at: 'next_user_message')
messages.3: output_config is not permitted on a turn-scoped system message (clear_at: 'next_user_message')
messages.3.content.0: cache_control is not permitted on a turn-scoped system message (clear_at: 'next_user_message')

La première est l'erreur renvoyée sans l'en-tête bêta. Sur Amazon Bedrock et Google Cloud, transmettez la valeur bêta comme décrit dans En-têtes bêta.

Via les SDK, définissez clear_at sur l'entrée role: "system" dans messages et envoyez l'en-tête bêta. L'exemple suivant ajoute un rappel limité au tour après le tour utilisateur ; lors de la requête suivante, dès qu'un message utilisateur ultérieur existe, le rappel reste dans le tableau mais ne s'affiche plus :

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Draft a short status update on the database migration for the team channel.",
        },
        # Rappel limité au tour : s'affiche pour ce tour, puis s'efface dès qu'un message utilisateur ultérieur existe.
        {
            "role": "system",
            "clear_at": "next_user_message",
            "content": "The reader is on call: keep this reply under 50 words.",
        },
    ],
    betas=["mid-conversation-system-clear-at-2026-08-21"],
)

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

Combinaison avec la mise en cache des prompts

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

• Activez explicitement la mise en cache. La mise en cache n'a lieu que lorsque la requête inclut cache_control, soit le champ de mise en cache automatique de premier niveau, soit un point d'arrêt explicite sur un bloc de contenu. Un message système en cours de conversation ne crée pas d'entrée de cache à lui seul, et sans mise en cache activée, il n'y a aucune économie à 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, qu'il s'agisse de la fin du champ system de premier niveau, de la fin de vos définitions d'outils ou d'un point stable de l'historique des messages.
• Ajoutez le message système après le point d'arrêt. Comme il vient après le préfixe mis en cache, il ne modifie pas le hachage du préfixe et le cache est toujours atteint.
• Un message système en cours de conversation peut lui-même être mis en cache. Une fois dans la conversation, il fait partie de l'historique stable. Au tour suivant, vous pouvez déplacer votre point d'arrêt de cache au-delà de lui (ou vous appuyer sur la mise en cache automatique pour le faire) et le message système est lu depuis le cache comme n'importe quel autre tour.

Évitez de modifier ou de supprimer un message système en cours de conversation qui a déjà été envoyé. Comme toute autre modification de messages antérieurs, cela invalide le cache à partir de ce point. Sur Claude Fable 5.1, cela invalide également les blocs de réflexion de chaque tour assistant ultérieur. Pour des consignes qui ne doivent s'appliquer qu'à un seul tour, utilisez un message système limité au tour et laissez-le en place. 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 qui porte du contenu ne peut pas être la première entrée de messages. Utilisez le champ system de premier niveau pour les instructions qui s'appliquent dès le tout début.
• Le placement est contraint. Un message system qui porte du contenu (blocs text, tool_addition ou tool_removal) doit suivre immédiatement 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 placer entre un bloc tool_use et son tool_result. Le placer ailleurs renvoie une erreur 400. Un message avec un content vide qui ne définit que output_config.effort n'affiche rien à sa position et est accepté n'importe où dans messages, y compris en premier ou entre un tour assistant et un tour user. Les messages system consécutifs sont évalués ensemble, de sorte qu'ajouter un message portant du texte à côté d'un message ne portant que l'effort fait suivre la règle de contenu à l'ensemble du groupe.
• Les messages limités au tour sont en texte uniquement et renvoyés à l'identique. Un message clear_at: "next_user_message" ne porte ni tool_addition, ni tool_removal, ni output_config, ni cache_control, et une fois effacé, il doit rester dans messages octet pour octet lors des requêtes ultérieures. Voir Messages système limités au tour.
• Pas un endroit pour du contenu non fiable. Claude traite le contenu système comme des instructions de l'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 conférerait à 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.

Voir aussi