Messages système en milieu de conversation

Les instructions système résident normalement dans le champ system de niveau supérieur, avant tous les messages de la conversation. Cette position est idéale pour la mise en cache des prompts : l'invite système fait partie du préfixe stable, de sorte que les tours suivants bénéficient du cache. C'est en revanche 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"} à l'endroit 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 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 comme une instruction système plutôt que comme du texte utilisateur ordinaire.



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 exige que le préfixe corresponde exactement à une requête récente, octet par octet, jusqu'au point d'arrêt 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 ce champ, 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 tous les messages mis en cache qui la suivent.

Les messages système en milieu de conversation vous permettent d'ajouter l'instruction à la fin de l'historique des messages. 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 fraîche.

Quelques situations où cela est important :

• Changements de politique ou de persona en cours de session. Une longue session agentique nécessite une nouvelle contrainte (« à partir de maintenant, écris 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'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'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 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 activé ou désactivé 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 doit pas interrompre une boucle agentique. Un utilisateur saisit un message de suivi pendant que Claude exécute encore des outils pour la requête précédente. Le relayer sous forme de message système après le prochain résultat d'outil permet à Claude d'intégrer la nouvelle entrée au travail qu'il est déjà en train d'effectuer, 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 workflows 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 Créer 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 réside dans 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. En cas de conflit entre les deux, les instructions système ont la priorité ; utilisez donc le rôle system pour les faits et contraintes de niveau opérateur qui doivent s'appliquer 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.



Fonctionnement

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 que pour un tour user ou assistant. L'instruction s'applique à partir de ce point de la conversation. En cas de conflit entre instructions, 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-4-8",
    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.",
        },
    ],
)

print(response.content[0].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 ne comporte aucun champ cache_control (automatique ou point d'arrêt explicite), rien n'est mis en cache et chaque requête paie le prix normal des tokens d'entrée pour l'intégralité de la conversation. Avec la mise en cache activée, l'ajout du message système laisse inchangés les tours déjà mis en cache, de sorte que la requête qui porte la nouvelle instruction les lit toujours depuis le cache au lieu de les retraiter. 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 ce seuil, 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 milieu de conversation doit suivre immédiatement un tour user (ou un tour assistant se terminant par une utilisation d'outil serveur), et doit être soit la dernière entrée de messages, soit 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. La seule position non autorisée est entre un bloc tool_use de l'assistant et le tool_result qui y répond.



Placement après les résultats d'outils

Dans une boucle agentique, le message système se place après le message user qui livre les résultats d'outils. C'est également là que votre application peut relayer une entrée que l'utilisateur a saisie 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 du contexte plutôt que comme une commande qui supplante l'utilisateur. Énoncez le fait (« nouvelle entrée reçue de l'utilisateur : X », « le budget de tokens 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 également au rôle système ; une formulation telle que « ignore ce que l'utilisateur a dit » est donc moins efficace que d'énoncer ce qui a changé.

Ce schéma 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 explicitement la mise en cache. 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 d'arrêt explicite sur un bloc de contenu. Un message système en milieu 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 niveau supérieur, de la fin de vos définitions d'outils ou d'un point stable dans 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 milieu de conversation est lui-même 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 d'arrêt de cache au-delà de celui-ci (ou laisser la mise en cache automatique 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 milieu de conversation qui a déjà été envoyé. Comme toute autre modification de 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 ne sont pas autorisés ; fusionnez les instructions en un seul message ou attendez le prochain tour utilisateur avant d'en ajouter un.



Limitations

• Pas pour le premier message. Un message system ne peut pas être la première entrée de 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 suivre immédiatement un tour user (y compris un tour user qui porte des blocs tool_result) ou un tour assistant se terminant par une utilisation 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 emplacement 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 brutes d'outils, des documents récupérés ou du contenu web, directement dans un message système ; cela confère à 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