System-Nachrichten und Tool-Änderungen mitten in der Konversation

Systemanweisungen befinden sich normalerweise im Top-Level-Feld system, vor jeder Nachricht in der Konversation. Diese Position ist ideal für Prompt-Caching: Der System-Prompt ist Teil des stabilen Präfixes, sodass nachfolgende Turns den Cache treffen. Es ist jedoch eine schlechte Position für Anweisungen, von denen du erst mitten in einer Sitzung feststellst, dass du sie brauchst, denn das Bearbeiten des Top-Level-Felds system ändert den Anfang des Prompts und invalidiert den Cache für alles, was danach folgt.

System-Nachrichten mitten in der Konversation schließen diese Lücke. Du hängst eine {"role": "system"}-Nachricht an der Stelle in der Konversation an, an der die neue Anweisung relevant wird, anstatt das Top-Level-Feld system zu bearbeiten. Das gecachte Präfix bleibt gleich, sodass die nächste Anfrage es weiterhin aus dem Cache liest, und die neue Anweisung wird trotzdem als Systemanweisung angewendet und nicht als gewöhnlicher Benutzertext.

Diese Seite behandelt zwei Features: System-Nachrichten mitten in der Konversation, die allgemein verfügbar sind, und Tool-Änderungen mitten in der Konversation, eine mit Claude Opus 5 eingeführte Beta, die denselben Ansatz auf das tools-Array anwendet.



Tool-Änderungen mitten in der Konversation

Das tools-Array steht im gehashten Anfragepräfix noch vor dem Top-Level-Feld system, sodass eine Bearbeitung den Prompt-Cache für die gesamte Konversation invalidiert. Tool-Änderungen mitten in der Konversation, eine mit Claude Opus 5 eingeführte Beta, sind das Tool-Gegenstück zu System-Nachrichten mitten in der Konversation. Anstatt die Tool-Liste für die gesamte Lebensdauer der Konversation festzulegen, änderst du zwischen den Turns, welche Tools dem Modell angeboten werden: Deklariere den vollständigen Tool-Satz vorab in tools und verwende dann tool_addition- und tool_removal-Blöcke, um dem Modell ab einem bestimmten Punkt in der Konversation ein Tool anzubieten oder es zurückzuziehen. Das tools-Array selbst ändert sich nie, sodass das gecachte Präfix intakt bleibt.

tool_addition und tool_removal sind Content-Blöcke im content-Array einer role: "system"-Nachricht und können mit text-Blöcken in derselben Nachricht gemischt werden. Die Nachricht folgt denselben Platzierungsregeln wie jede System-Nachricht mitten in der Konversation (siehe Einschränkungen), und die Änderung gilt ab diesem Punkt in der Konversation. Das tool-Feld jedes Blocks referenziert ein Tool, anstatt eines zu definieren: {"type": "tool_reference", "name": "..."} benennt ein im tools-Array der Anfrage deklariertes Tool, und MCP-Connector-Tools können einzeln mit mcp_tool_reference (server_name und name) oder als gesamtes Toolset mit mcp_toolset_reference (server_name) referenziert werden. Das Referenzieren eines Namens, der nicht in tools deklariert ist, gibt einen 400-Fehler zurück.

Jedes in tools deklarierte Tool wird dem Modell vom Beginn der Konversation an angeboten, es sei denn, es ist mit defer_loading: true deklariert, wodurch es zurückgehalten wird, bis ein tool_addition-Block es verfügbar macht. tool_addition bietet auch ein Tool erneut an, das ein früheres tool_removal zurückgezogen hat.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    # Das vollständige Tool-Set wird vorab deklariert und ändert sich nie, sodass
    # das gecachte Präfix intakt bleibt.
    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.",
        },
        # Ziehe get_weather ab diesem Punkt zurück. Der Block referenziert
        # das Tool per Name, statt `tools` zu bearbeiten, sodass frühere Turns
        # byte-identisch bleiben und der Cache weiterhin greift.
        {
            "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)

Tool-Änderungen mitten in der Konversation befinden sich in der Beta. Um sie zu verwenden, füge den Beta-Header mid-conversation-tool-changes-2026-07-01 in deine Anfragen ein. Sie sind auf Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 und Claude Opus 5 verfügbar, über die Claude API, Amazon Bedrock und Google Cloud.



Wann du eine System-Nachricht mitten in der Konversation verwenden solltest

Prompt-Caching hasht das Anfragepräfix in dieser Reihenfolge: tools, dann system, dann messages. Ein Cache-Treffer erfordert, dass das Präfix Byte für Byte exakt mit einer kürzlich gesendeten Anfrage übereinstimmt, bis zum Cache-Breakpoint.

Diese Reihenfolge bedeutet, dass das Top-Level-Feld system ganz am Anfang des gehashten Präfixes steht. Jede Änderung daran, selbst das Anhängen eines Satzes, erzeugt einen anderen Hash, und die Anfrage verfehlt den Cache für den System-Prompt und jede gecachte Nachricht danach.

System-Nachrichten mitten in der Konversation ermöglichen es dir, die Anweisung stattdessen am Ende des Nachrichtenverlaufs hinzuzufügen. Alles vor der neuen Anweisung bleibt unverändert, sodass der bestehende Cache-Eintrag weiterhin passt und nur die neue Nachricht als frische Eingabe verarbeitet wird.

Einige Situationen, in denen das wichtig ist:

• Richtlinien- oder Persona-Änderungen mitten in der Sitzung. Eine lange agentische Sitzung benötigt nach Dutzenden gecachter Turns eine neue Einschränkung („schreibe ab jetzt alle SQL-Abfragen als parametrisierte Queries"). Das Hinzufügen zum Top-Level-Feld system würde den gesamten Verlauf neu verarbeiten.
• Turn-spezifischer Kontext, der autoritativ sein muss. Du möchtest einen Aktualitätshinweis, eine Sitzungsfrist oder eine Änderung der Tool-Verfügbarkeit mit System-Level-Gewicht einfügen, und das ändert sich zu häufig, um im gecachten Präfix zu stehen.
• Zustandsänderungen, die deine Anwendung beobachtet. Deine Anwendung bemerkt etwas, das Claude als Operator-Level-Fakt behandeln sollte: Dateien auf der Festplatte haben sich geändert, der Benutzer hat eine Auto-Approve-Einstellung umgeschaltet, verfügbare Tools haben sich geändert oder das verbleibende Token-Budget ist unter einen Schwellenwert gefallen.
• Benutzereingaben, die eine agentische Schleife nicht unterbrechen sollen. Ein Benutzer tippt eine Folgeanfrage, während Claude noch Tools für die vorherige Anfrage ausführt. Wenn du sie als System-Nachricht nach dem nächsten Tool-Ergebnis weiterleitest, kann Claude die neue Eingabe in die bereits laufende Arbeit einfließen lassen, anstatt sie als neue Anfrage zu behandeln, zu der gewechselt werden muss. Siehe Platzierung nach Tool-Ergebnissen unten.
• Moduswechsel, die dauerhafte Berechtigungen erteilen. Ein Modus auf Sitzungsebene kann eine System-Nachricht mitten in der Konversation verwenden, um eine dauerhafte Zustimmung zu einer aufwendigen Fähigkeit zu erteilen, etwa dem automatischen Starten von Multi-Agenten-Workflows, mit einer kurzen Auffrischung alle paar Turns und einem Beendigungshinweis, wenn der Modus ausgeschaltet wird. Ein ausgearbeitetes Beispiel findest du unter Einen Orchestrierungsmodus erstellen.

In all diesen Fällen könntest du die Anweisung in eine reguläre user-Nachricht setzen, und Claude befolgt durchaus Anweisungen, die in User-Turns ankommen. Der Unterschied liegt in der Priorität: Eine user-Nachricht wird so behandelt, als käme sie vom Endbenutzer, während eine system-Nachricht so behandelt wird, als käme sie von dir, dem Anwendungsbetreiber. Wenn beide in Konflikt stehen, haben Systemanweisungen Vorrang. Verwende daher die system-Rolle für Operator-Level-Fakten und -Einschränkungen, die auch dann gelten sollen, wenn der Endbenutzer etwas anderes verlangt. Eine System-Nachricht mitten in der Konversation behält diese Operator-Level-Priorität bei, ohne die Cache-Miss-Kosten für das Bearbeiten des Top-Level-Felds system zu verursachen.



So funktioniert es

Füge dem messages-Array eine Nachricht mit "role": "system" hinzu. Verwende für content einen einfachen String oder Content-Blöcke, genau wie bei einem user- oder assistant-Turn. Die Anweisung gilt ab diesem Punkt in der Konversation. Wenn Anweisungen in Konflikt stehen, haben spätere System-Nachrichten Vorrang vor früheren, und System-Nachrichten mitten in der Konversation haben für die nachfolgenden Turns Vorrang vor dem Top-Level-Feld system.

Du kannst das Top-Level-Feld system weiterhin für Anweisungen setzen, die für die gesamte Konversation gelten sollen. Reserviere System-Nachrichten mitten in der Konversation für Anweisungen, die erst später relevant werden oder die du hinzufügen möchtest, ohne das gecachte Präfix zu invalidieren.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # Automatisches Prompt-Caching: jede Anfrage cacht die bisherige Konversation,
    # und die nächste Anfrage liest das unveränderte Präfix aus dem 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().",
        },
        # Der Reviewer merkt mitten in der Sitzung, dass alle Vorschläge auch
        # die strenge Typisierungsrichtlinie des Teams erfüllen müssen. Das Anhängen
        # der Anweisung hier hält frühere Turns byte-identisch, sodass das
        # von der vorherigen Anfrage gecachte Präfix weiterhin aus dem Cache gelesen wird.
        {
            "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)

Dieses Beispiel aktiviert automatisches Caching mit dem Top-Level-Feld cache_control. Prompt-Caching ist Opt-in: Wenn eine Anfrage kein cache_control-Feld hat (weder automatisch noch ein expliziter Breakpoint), wird nichts gecacht und jede Anfrage zahlt den regulären Input-Token-Preis für die gesamte Konversation. Mit aktiviertem Caching lässt das Anhängen der System-Nachricht die bereits gecachten Turns unverändert, sodass die Anfrage, die die neue Anweisung enthält, sie weiterhin aus dem Cache liest, anstatt sie erneut zu verarbeiten. Caching erfordert außerdem, dass die Konversation die minimale cachebare Prompt-Länge erreicht; ein so kurzes Beispiel wie dieses liegt darunter, sodass cache_creation_input_tokens und cache_read_input_tokens bei 0 bleiben, bis die Konversation wächst.

Eine System-Nachricht mitten in der Konversation muss unmittelbar auf einen user-Turn folgen (oder auf einen assistant-Turn, der mit einem Server-Tool-Ergebnis endet) und muss entweder der letzte Eintrag in messages sein oder unmittelbar von einem assistant-Turn gefolgt werden. Eine user-Nachricht, die tool_result-Blöcke enthält, zählt: In einer agentischen Schleife kannst du die System-Nachricht direkt nach den Tool-Ergebnissen platzieren, vor Claudes nächstem Turn. Jede andere Position, einschließlich zwischen einem assistant-tool_use-Block und dem tool_result, das ihn beantwortet, gibt einen 400-Fehler zurück.



Platzierung nach Tool-Ergebnissen

In einer agentischen Schleife kommt die System-Nachricht nach der user-Nachricht, die die Tool-Ergebnisse liefert. Hier kann deine Anwendung auch Eingaben weiterleiten, die der Benutzer getippt hat, während Claude gearbeitet hat, sodass der neue Kontext aufgenommen wird, ohne den Turn neu zu starten:

[
  { "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."
  }
]

Formuliere den System-Inhalt als Kontext und nicht als Befehl, der den Benutzer überstimmt. Nenne den Fakt („neue Eingabe vom Benutzer eingetroffen: X", „das verbleibende Token-Budget beträgt jetzt Y") und lass Claude darauf reagieren. Claude ist darauf trainiert, Anweisungen zu widerstehen, die gegen den Benutzer zu arbeiten scheinen, und dieser Schutz gilt auch für die System-Rolle. Formulierungen wie „ignoriere, was der Benutzer gesagt hat" sind daher weniger effektiv, als einfach anzugeben, was sich geändert hat.

Dieses Muster dient dazu, Eingaben vom eigenen Endbenutzer der Konversation weiterzuleiten. Verwende es nicht, um Tool-Ausgaben, abgerufene Dokumente oder andere Inhalte von Drittanbietern zu übergeben; belasse diese Inhalte in tool_result-Blöcken (siehe Einschränkungen).



Kombination mit Prompt-Caching

System-Nachrichten mitten in der Konversation und Prompt-Caching sind dafür konzipiert, zusammen verwendet zu werden:

• Aktiviere Caching explizit. Caching findet nur statt, wenn die Anfrage cache_control enthält, entweder das Top-Level-Feld für automatisches Caching oder einen expliziten Breakpoint auf einem Content-Block. Eine System-Nachricht mitten in der Konversation erstellt von sich aus keinen Cache-Eintrag, und ohne aktiviertes Caching gibt es keine Einsparungen zu bewahren.
• Cache das stabile Präfix wie gewohnt. Platziere cache_control auf dem letzten Block, der über Anfragen hinweg gleich bleibt, sei es das Ende des Top-Level-Felds system, das Ende deiner Tool-Definitionen oder ein stabiler Punkt im Nachrichtenverlauf.
• Hänge die System-Nachricht nach dem Breakpoint an. Da sie nach dem gecachten Präfix kommt, ändert sie den Präfix-Hash nicht und der Cache trifft weiterhin.
• Eine System-Nachricht mitten in der Konversation ist selbst cachebar. Sobald sie in der Konversation ist, wird sie Teil des stabilen Verlaufs. Beim nächsten Turn kannst du deinen Cache-Breakpoint hinter sie verschieben (oder dich auf automatisches Caching verlassen, das dies übernimmt), und die System-Nachricht wird wie jeder andere Turn aus dem Cache gelesen.

Vermeide es, eine bereits gesendete System-Nachricht mitten in der Konversation zu bearbeiten oder zu entfernen. Wie jede andere Änderung an früheren Nachrichten invalidiert das den Cache ab diesem Punkt. Wenn sich die Anweisung weiterentwickeln muss, hänge eine neue System-Nachricht an, anstatt die alte umzuschreiben. Aufeinanderfolgende System-Nachrichten werden akzeptiert und als ein einziger System-Abschnitt behandelt, der als Ganzes derselben Platzierungsregel folgt.



Einschränkungen

• Nicht für die erste Nachricht. Eine system-Nachricht kann nicht der erste Eintrag in messages sein. Verwende das Top-Level-Feld system für Anweisungen, die von Anfang an gelten.
• Die Platzierung ist eingeschränkt. Eine system-Nachricht muss unmittelbar auf einen user-Turn folgen (einschließlich eines user-Turns, der tool_result-Blöcke enthält) oder auf einen assistant-Turn, der mit einem Server-Tool-Ergebnis endet, und muss einem assistant-Turn vorausgehen oder das Array beenden. Sie kann nicht zwischen einem tool_use-Block und seinem tool_result stehen. Eine Platzierung an anderer Stelle gibt einen 400-Fehler zurück.
• Kein Ort für nicht vertrauenswürdige Inhalte. Claude behandelt System-Inhalte als Operator-Anweisungen und befolgt sie. Platziere keinen Text von außerhalb der Konversation, wie rohe Tool-Ausgaben, abgerufene Dokumente oder Web-Inhalte, direkt in einer System-Nachricht; das verleiht diesem Text Operator-Level-Autorität. Belasse solche Daten in tool_result-Blöcken und befolge weiterhin Jailbreaks und Prompt-Injections abschwächen.



Verwandte Themen