Modifier les outils ou les instructions sans échouer à la vérification du préfixe

Pour mettre à jour des outils, des instructions ou tout autre contexte, laissez tout ce que vous avez envoyé tel quel, et ajoutez la mise à jour à la fin, où elle reste. Sur les modèles dotés de la « preserved thinking » (réflexion préservée), modifier ce que vous avez envoyé peut rendre invalide la réflexion qui suit, et la requête peut échouer.

Les modèles dotés de la « preserved thinking » (Réflexion préservée) sont Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5.

Renvoyer les tours de l’assistant à l’identique

Renvoyez l’intégralité du tableau content de chaque réponse, dans l’ordre, y compris les blocs de réflexion dont le texte est vide. Un bloc dont le texte est vide est complet, car sa signature contient le raisonnement, chiffré. Un tour qui contient un bloc fallback obéit à sa propre règle.

Les sérialiseurs, les filtres et les analyseurs de flux peuvent compromettre cela.

Modifier les instructions

Gardez system identique à chaque requête. Placez vos propres instructions dans un message role: "system" à la fin, et n’en envoyez un que lorsque quelque chose a changé. Claude le traite comme une instruction de votre part, en tant qu’opérateur. Laissez-le en place pour le reste de la conversation, car le supprimer ou le reformuler plus tard rend invalide la réflexion qui le suit. Les propos de votre utilisateur obéissent à leur propre règle.

Un rappel qui doit accompagner chaque tour est différent : envoyez-en un qui s’efface de lui-même.

Le message système se place après le message utilisateur le plus récent, même s’il contient des résultats d’outils. Un message système contenant du texte ou des blocs d’outils reçoit une erreur 400 juste après le tour de Claude ou juste avant un message utilisateur. Ainsi, lorsque le tour de Claude est le dernier, attendez que le message utilisateur suivant soit en place.

Un message système ne garantit pas que Claude suive une instruction ; appliquez donc les limites telles que le mode lecture seule dans le code qui exécute vos outils. Certains modèles n’acceptent pas les messages système.

Texte que d’autres personnes peuvent modifier

Demandez-vous si votre utilisateur s’attendrait à ce que Claude fasse confiance à un fichier, tel qu’un AGENTS.md ou un CLAUDE.md que d’autres personnes peuvent modifier, ou à une mémoire stockée. Si ce n’est pas le cas, n’envoyez son texte que dans un bloc tool_result, y compris la première version. Pour en savoir plus sur les raisons, consultez Injection de prompts indirecte.

Ne placez pas un tel texte dans un message système ni dans le texte d’un message utilisateur, et, dans les nouvelles conversations, ne le placez pas dans system.

Lorsque vous chargez un tel fichier ou qu’il change, demandez à Claude de le lire avec un outil, et n’incluez pas son texte. Ou bien, après le message utilisateur suivant, ajoutez vous-même l’appel d’outil et son résultat : un message assistant avec un bloc tool_use, puis un message user dont le bloc tool_result contient le texte. Pour les étapes, consultez Écrire l’appel d’outil vous-même.

Un fichier que votre utilisateur s’attend à ce que Claude suive peut aller dans un message utilisateur. Un fichier d’instructions que vous seul contrôlez peut aller dans un message système : chargez-le une fois, et ajoutez chaque version mise à jour.

Mettre à jour la date, les fichiers ou tout autre contexte

Construisez system et le premier message une seule fois, et envoyez-les inchangés à chaque requête.

Placez une valeur mise à jour dans son propre bloc de texte du message utilisateur que vous êtes sur le point d’envoyer, après les éventuels résultats d’outils :

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Environment update: the current branch is now release-2." },
    { "type": "text", "text": "Run the tests again." }
  ]
}

Indiquez-la uniquement lorsqu’elle change, et laissez-la en place.

Stockez tout contexte que votre code ajoute à un message avec ce message. Sinon, la requête suivante envoie quelque chose de différent avant la même réflexion.

Ajouter, supprimer ou désactiver des outils

Gardez tools identique à chaque requête. Ajouter, modifier ou supprimer un outil à cet endroit, autre qu’un outil différé, rend invalide la réflexion déjà présente dans la conversation, car tools précède l’ensemble de celle-ci. Une seule phrase reformulée dans une description suffit.

Pour ajouter ou supprimer un outil, ajoutez un message système avec un bloc tool_addition ou tool_removal et l’en-tête bêta correspondant à votre cas. Faites de même lorsqu’un serveur MCP ou un plugin se connecte.

Pour désactiver les outils pour une requête, définissez tool_choice: {"type": "none"}, et gardez tools tel quel.

Raccourcir ou résumer les tours plus anciens

Pour conserver les tours récents avec leur réflexion, laissez l’API rédiger le résumé grâce à la compaction à la demande, dans le respect des conditions de la réflexion conservée. Commencez messages par le bloc de compaction qu’elle renvoie, et supprimez les messages qu’il résume.

Si votre propre code rédige le résumé, ou coupe les tours plus anciens sans résumé, supprimez la réflexion des tours conservés ou envoyez "drop_block". Chaque nouvelle coupe rend à nouveau invalide la réflexion des tours conservés ; coupez donc rarement, par grandes étapes. Pour effacer plutôt les anciens résultats d’outils, utilisez l’édition du contexte.

Enregistrer, reprendre ou dupliquer une conversation

Stockez ce que vous avez envoyé et ce que vous avez reçu, et envoyez exactement cela. Une conversation reprise est une requête suivante ordinaire : system, tools et les messages antérieurs doivent avoir les valeurs qu’ils avaient. Pour une duplication, placez l’instruction de la branche dans son premier nouveau message utilisateur, ou dans un message système après celui-ci. La réflexion ne peut pas passer à une conversation dont l’historique est différent : démarrez plutôt cette conversation à partir d’un résumé.

Une version qui modifie votre invite système ou vos outils constitue une modification des conversations déjà en cours. Le correctif qui rend votre code « append-only » (en ajout seul) peut en être une aussi. Continuez d’envoyer à chaque conversation en cours le system et les tools de sa dernière requête réussie, car sa réflexion la plus récente a été produite après cette version. Revenir à une version antérieure rendrait cette réflexion invalide.

Utilisez le system et les tools mis à jour dans les nouvelles conversations. Si la version supprime un outil ou modifie une instruction pour des raisons de sécurité, appliquez-la également aux conversations en cours. Ajoutez un bloc tool_removal ou un message système.

Supprimer des secrets, des données personnelles ou du texte injecté

La sécurité et la confidentialité passent avant le maintien de la validité de la réflexion. Si un message contient un secret ou des données personnelles que vous devez supprimer, supprimez ce texte. Supprimez-le également de chaque message et résumé qui le reprend.

Pour un résultat d’outil contenant des instructions injectées, remplacez son contenu par une courte note telle que « Supprimé. ». Conservez le bloc tool_result lui-même, car son tool_use en a besoin. Si un bloc de compaction contient le texte, supprimez le bloc, et repartez de votre propre résumé.

Supprimez ensuite chaque bloc thinking et redacted_thinking situé après le premier endroit où le texte est apparu. S’il se trouvait dans system ou tools, cela les concerne tous. Chaque bloc peut reprendre le texte, et vous ne pouvez ni lire ni modifier ce qu’il contient. Envoyer "drop_block" ne suffit pas ici, car cela laisse ces blocs dans votre historique stocké. La conversation se poursuit sans ce raisonnement.

Après un résultat injecté, les tours suivants ont peut-être déjà agi en conséquence. Vérifiez les appels d’outils effectués depuis, et annulez ce qui doit l’être.

Détails techniques

Comment le code modifie les tours de l’assistant

• Un sérialiseur écarte les types de blocs qu’il ne connaît pas, ou réordonne, fusionne ou scinde des blocs. Cela modifie ce qui précède chaque bloc ultérieur.
• Le code ignore les blocs de réflexion qui semblent vides. S’il les ignore tous, Claude perd ce raisonnement. S’il n’en ignore que certains, le trou rend invalide la réflexion qui le suit.
• Un analyseur de flux que vous avez écrit vous-même écarte un bloc de réflexion qui n’a reçu aucun texte. Les utilitaires de streaming du SDK le conservent.

Omettre la réflexion

Claude perd le raisonnement que vous omettez. Omettez les blocs les plus anciens, les plus récents ou tous, mais aucun au milieu. Chaque bloc enregistre celui après lequel il a été produit ; un trou rend donc invalides les blocs qui le suivent. Les blocs de réflexion qu’aucun autre bloc ne sépare dans un tour sont soumis ensemble à la vérification du préfixe ; omettez-les donc tous ou aucun. Une fois qu’un bloc est omis, maintenez-le omis.

Tant qu’un appel d’outil est ouvert, renvoyez la réflexion de ce tour, afin que Claude termine le cycle avec son raisonnement.

Vos instructions dans une boucle d’outils

Les messages se placent dans cet ordre :

[
  {
    "role": "assistant",
    "content": [
      { "type": "thinking", "thinking": "", "signature": "..." },
      {
        "type": "tool_use",
        "id": "toolu_01",
        "name": "run_tests",
        "input": { "path": "tests/" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "2 failed, 48 passed" }
    ]
  },
  {
    "role": "system",
    "content": "Plan mode is off. You can edit files."
  }
]

Écrire l’appel d’outil vous-même

Déclarez un outil qui lit des fichiers dès la première requête, ou ajoutez-le plus tard dans un message système, et faites en sorte que votre code réponde aux appels que Claude lui adresse. Après le message utilisateur suivant, ajoutez un message assistant avec un bloc tool_use pour cet outil. Juste après, ajoutez un message user dont le bloc tool_result porte le tool_use_id correspondant et contient le texte du fichier. Claude répond après cela :

[
  { "role": "user", "content": "Run the tests again." },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_app_agents_md_1",
        "name": "read_file",
        "input": { "path": "AGENTS.md" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_app_agents_md_1",
        "content": "The file's text"
      }
    ]
  }
]

Laissez les deux en place, et ajoutez une nouvelle paire, avec un nouvel id, pour chaque nouvelle version.

Les propos de votre utilisateur, et les valeurs mises à jour, dans une boucle d’outils

Si vous transmettez ce que votre utilisateur a saisi pendant que Claude travaillait, ajoutez-le avant d’envoyer le message utilisateur qui porte les blocs tool_result. Faites-en un bloc de texte après le dernier tool_result.

Une valeur qui provient de vous peut plutôt aller dans un message système. Après des résultats d’outils, Claude Sonnet 5.5 et Claude Haiku 5.5 peuvent ignorer les propos d’un utilisateur placés dans un message système en les considérant comme une « prompt injection » (injection de prompt). Claude Sonnet 5.5 peut faire de même avec vos propres instructions et rappels s’ils viennent après chaque résultat d’outil.

Le message utilisateur contenant les résultats d’outils ne doit contenir que des blocs tool_result lorsque le tour a également appelé un outil serveur qui n’a pas encore de résultat, ou a utilisé l’appel d’outils programmatique. Ajoutez alors le texte au message utilisateur suivant.

Modèles qui n’acceptent pas les messages système

Sur la Claude API, chaque modèle doté de la réflexion préservée accepte les messages système. Pour un modèle qui ne les accepte pas, consultez Lorsqu’un modèle n’accepte pas les messages système.

Envoyer un rappel pour un seul tour

Envoyez un rappel sous la forme d’un message système limité au tour : définissez clear_at: "next_user_message", et envoyez l’en-tête bêta mid-conversation-system-clear-at-2026-08-21. Il se place après le message utilisateur qui porte les blocs tool_result :

{
  "role": "system",
  "clear_at": "next_user_message",
  "content": "Run the linter before you report that a task is done."
}

Au message utilisateur suivant, même s’il ne contient que des blocs tool_result, l’API l’efface, de sorte que Claude cesse de le lire. Sur Claude Sonnet 5.5, n’en envoyez pas après chaque résultat d’outil. Conservez chaque rappel dans vos messages, effacé ou non, sauf s’il contient quelque chose que vous devez supprimer. Supprimer ou reformuler un rappel rend invalide la réflexion qui le suit.

Sans l’en-tête, envoyez un message système ordinaire et laissez-le en place. Il ne s’efface jamais, donc les rappels s’accumulent. Sur un modèle qui n’accepte pas de messages système, utilisez un bloc de texte dans le message utilisateur.

Quel bloc et quel en-tête bêta une modification d’outil nécessite

Pour connaître les plateformes qui acceptent chaque en-tête, consultez Messages système et changements d’outils en cours de conversation.

• Si vous connaissez tous les outils dès le début : Déclarez-les tous dès la première requête, avec defer_loading: true sur ceux que vous proposez plus tard. Nommez ensuite l’outil dans un bloc tool_addition ou tool_removal d’un message système. En-tête bêta : inline-tools-2026-09-15 ou mid-conversation-tool-changes-2026-07-01.
• Si vous découvrez un outil plus tard, ou si vous en avez un dont le schéma change : Définissez l’outil dans un bloc tool_addition d’un message système. En-tête bêta : inline-tools-2026-09-15.
• Si vous découvrez un outil plus tard, sur une plateforme sans l’en-tête inline-tools-2026-09-15 : Ajoutez l’outil à la fin de tools avec defer_loading: true, ce qui ne constitue pas une modification, puis proposez-le par son nom. En-tête bêta : mid-conversation-tool-changes-2026-07-01.
• Si vous connectez tardivement un serveur MCP via le connecteur MCP, sur la Claude API : Définissez son mcp_toolset dans un bloc tool_addition. En-têtes bêta : inline-tools-2026-09-15 et mcp-client-2026-09-15.

Si la liste d’outils d’un serveur MCP peut changer, consultez Épingler la liste d’outils d’un serveur MCP.

Ce message système propose un outil déclaré par son nom et en définit un autre, ce qui nécessite inline-tools-2026-09-15 :

{
  "role": "system",
  "content": [
    {
      "type": "tool_addition",
      "tool": { "type": "tool_reference", "name": "search_tickets" }
    },
    {
      "type": "tool_addition",
      "tool": {
        "type": "tool_definition",
        "definition": {
          "name": "get_weather",
          "description": "Get the current weather in a city.",
          "input_schema": {
            "type": "object",
            "properties": { "city": { "type": "string" } },
            "required": ["city"]
          }
        }
      }
    }
  ]
}

Outils avec defer_loading, et l’erreur 400 qui le mentionne

Un outil avec defer_loading: true reste hors du contexte de Claude et de la « prefix check » (vérification du préfixe) jusqu’à ce qu’un message ou un résultat de recherche d’outils y fasse référence. Jusque-là, l’ajouter, le mettre à jour ou le supprimer ne constitue pas une modification. Par la suite, si. Activer ou désactiver defer_loading compte également comme une modification de tools.

Déclarez au moins un outil qui n’est pas différé, sinon la requête peut recevoir une erreur 400 qui mentionne defer_loading.

Raccourcir ou effacer les anciens résultats et images

Raccourcissez ou réduisez la résolution d’un résultat d’outil ou d’une image avant de l’envoyer pour la première fois. Si votre code efface, raccourcit ou réencode quelque chose qu’il a déjà envoyé, la réflexion qui le suit devient invalide. Pour effacer ultérieurement les anciens résultats d’outils, y compris les éventuelles images qu’ils contiennent, utilisez la « context editing » (édition du contexte). Envoyez context_management avec une modification de type clear_tool_uses_20250919, et l’en-tête bêta context-management-2025-06-27. Pour la requête complète et ses options, consultez Édition du contexte.

Fichiers que vous envoyez par URL

Pour un fichier envoyé par URL, l’API compare les octets qu’elle a récupérés. Ainsi, lorsqu’une URL signée expire, une nouvelle URL pour le même fichier convient. Si le contenu derrière une URL peut changer, envoyez un file_id ou du base64 dès la première requête.

Si votre propre code résume ou coupe les tours plus anciens

Après votre propre résumé ou votre propre coupe, la réflexion d’un tour conservé échoue à la vérification du préfixe, car les messages qu’elle suivait ont disparu. Supprimez cette réflexion, ou envoyez "drop_block". Claude lit toujours le tour sans elle.

Bibliothèques, proxys et passerelles

Si les requêtes d’autres personnes transitent par votre code, vos réécritures modifient leur historique, et elles pourraient ne pas être en mesure de voir ou de corriger ces modifications. Ne masquez pas l’erreur 400. Si vous effectuez une récupération pour le compte de l’appelant, signalez-le, car son historique contient toujours la modification.

• Transmettez les valeurs anthropic-beta et thinking.block_binding telles qu’elles ont été envoyées. Si votre passerelle n’autorise que les champs connus, ajoutez thinking.block_binding et la valeur d’en-tête thinking-binding-controls-2026-08-01, sinon vos utilisateurs ne pourront pas choisir "drop_block".
• Ne supprimez pas l’en-tête bêta tout en transmettant le réglage. Cette requête reçoit une erreur 400.
• Renvoyez à l’appelant les blocs de réflexion dont le texte est vide, ainsi que le tableau input_transformations.
• Laissez un message role: "system" là où il se trouve. Le déplacer dans system rend invalide la réflexion déjà présente dans la conversation.
• Testez avec le réglage prefix_mismatch_behavior défini sur "error", ce qui produit l’erreur sur chaque modèle doté de la réflexion préservée.

Étapes suivantes