System-Nachrichten und Tool-Änderungen mitten im Gespräch

Systemanweisungen stehen normalerweise im Top-Level-Feld system, vor jeder Nachricht im Gespräch. 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 verändert den Anfang des Prompts und invalidiert den Cache für alles, was danach folgt.

System-Nachrichten mitten im Gespräch schließen diese Lücke. Du hängst eine {"role": "system"}-Nachricht an der Stelle im Gespräch an, an der die neue Anweisung relevant wird, anstatt das Top-Level-Feld system zu bearbeiten. Der zwischengespeicherte Präfix bleibt gleich, sodass die nächste Anfrage ihn 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 im Gespräch, die allgemein verfügbar sind, und Tool-Änderungen mitten im Gespräch, eine Beta, die mit Claude Opus 5 eingeführt wurde und denselben Ansatz auf das tools-Array anwendet.



Tool-Änderungen mitten im Gespräch

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

tool_addition und tool_removal sind Content-Blöcke im content-Array einer role: "system"-Nachricht und können in derselben Nachricht mit text-Blöcken gemischt werden. Die Nachricht folgt denselben Platzierungsregeln wie jede System-Nachricht mitten im Gespräch (siehe Einschränkungen), und die Änderung gilt ab diesem Punkt im Gespräch. Das tool-Feld jedes Blocks referenziert ein Tool, anstatt eines zu definieren: {"type": "tool_reference", "name": "..."} benennt ein Tool, das im tools-Array der Anfrage deklariert ist, und MCP-Connector-Tools können einzeln mit mcp_tool_reference (server_name und name) oder als ganzes 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 von Beginn des Gesprächs an angeboten, es sei denn, es wird mit defer_loading: true deklariert, wodurch es zurückgehalten wird, bis ein tool_addition-Block es freigibt. tool_addition bietet auch ein Tool erneut an, das ein früherer tool_removal-Block 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 über den Namen, 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 im Gespräch 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, auf der Claude API, Amazon Bedrock und Google Cloud.



Wann du eine System-Nachricht mitten im Gespräch verwenden solltest

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

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 zwischengespeicherte Nachricht danach.

System-Nachrichten mitten im Gespräch 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 zwischengespeicherter Turns eine neue Einschränkung („schreibe ab jetzt alle SQL-Abfragen als parametrisierte Queries"). Sie dem Top-Level-Feld system hinzuzufügen würde den gesamten Verlauf neu verarbeiten.
• Kontext pro Turn, der autoritativ sein muss. Du möchtest einen Aktualitätshinweis, eine Sitzungsfrist oder eine Änderung der Tool-Verfügbarkeit mit System-Gewichtung einfügen, und sie ändert sich zu oft, um im zwischengespeicherten Präfix zu stehen.
• Zustandsänderungen, die deine Anwendung beobachtet. Deine Anwendung bemerkt etwas, das Claude als Fakt auf Operator-Ebene behandeln sollte: Dateien auf der Festplatte haben sich geändert, der Benutzer hat eine Auto-Genehmigungs-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 Nachfrage, während Claude noch Tools für die vorherige Anfrage ausführt. Sie als System-Nachricht nach dem nächsten Tool-Ergebnis weiterzugeben, ermöglicht es Claude, die neue Eingabe in die bereits laufende Arbeit einzubeziehen, anstatt sie als neue Anfrage zu behandeln, zu der gewechselt werden soll. Siehe Platzierung nach Tool-Ergebnissen unten.
• Moduswechsel, die dauerhafte Berechtigungen erteilen. Ein Modus auf Sitzungsebene kann eine System-Nachricht mitten im Gespräch verwenden, um eine dauerhafte Zustimmung zu einer teuren Fähigkeit zu erteilen, wie etwa dem automatischen Starten von Multiagenten-Workflows, mit einer kurzen Auffrischung alle paar Turns und einem Hinweis beim Beenden, 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 packen, und Claude befolgt Anweisungen, die in Benutzer-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 die beiden in Konflikt stehen, haben Systemanweisungen Vorrang. Verwende daher die system-Rolle für Fakten und Einschränkungen auf Operator-Ebene, die auch dann gelten sollen, wenn der Endbenutzer etwas anderes verlangt. Eine System-Nachricht mitten im Gespräch behält diese Priorität auf Operator-Ebene bei, ohne die Cache-Miss-Kosten zu zahlen, die das Bearbeiten des Top-Level-Felds system verursacht.



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 im Gespräch. Wenn Anweisungen in Konflikt stehen, haben spätere System-Nachrichten Vorrang vor früheren, und System-Nachrichten mitten im Gespräch haben für die darauffolgenden Turns Vorrang vor dem Top-Level-Feld system.

Du kannst das Top-Level-Feld system weiterhin für Anweisungen setzen, die für das gesamte Gespräch gelten sollen. Reserviere System-Nachrichten mitten im Gespräch für Anweisungen, die erst später relevant werden oder die du hinzufügen möchtest, ohne den zwischengespeicherten 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 Session, dass alle Vorschläge
        # auch die strikte 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 (automatisch oder als expliziter Breakpoint), wird nichts zwischengespeichert und jede Anfrage zahlt den regulären Input-Token-Preis für das gesamte Gespräch. Mit aktiviertem Caching lässt das Anhängen der System-Nachricht die bereits zwischengespeicherten Turns unverändert, sodass die Anfrage, die die neue Anweisung trägt, sie weiterhin aus dem Cache liest, anstatt sie erneut zu verarbeiten. Caching erfordert außerdem, dass das Gespräch die minimale zwischenspeicherbare 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 das Gespräch wächst.

Eine System-Nachricht mitten im Gespräch 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 weitergeben, 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 übersteuert. 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 die Angabe dessen, was sich geändert hat.

Dieses Muster dient dazu, Eingaben vom eigenen Endbenutzer des Gesprächs weiterzugeben. Verwende es nicht, um Tool-Ausgaben, abgerufene Dokumente oder andere Inhalte von Dritten weiterzugeben; behalte diese Inhalte in tool_result-Blöcken (siehe Einschränkungen).



Kombination mit Prompt-Caching

System-Nachrichten mitten im Gespräch 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 im Gespräch erstellt von sich aus keinen Cache-Eintrag, und ohne aktiviertes Caching gibt es keine Einsparungen zu bewahren.
• Cache den stabilen 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 zwischengespeicherten Präfix kommt, ändert sie den Präfix-Hash nicht und der Cache trifft weiterhin.
• Eine System-Nachricht mitten im Gespräch ist selbst zwischenspeicherbar. Sobald sie im Gespräch ist, wird sie Teil des stabilen Verlaufs. Im nächsten Turn kannst du deinen Cache-Breakpoint hinter sie verschieben (oder dich auf automatisches Caching verlassen), und die System-Nachricht wird wie jeder andere Turn aus dem Cache gelesen.

Vermeide es, eine bereits gesendete System-Nachricht mitten im Gespräch 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 des Gesprächs, wie rohe Tool-Ausgaben, abgerufene Dokumente oder Web-Inhalte, direkt in einer System-Nachricht; das würde diesem Text Autorität auf Operator-Ebene verleihen. Behalte diese Daten in tool_result-Blöcken und befolge weiterhin Jailbreaks und Prompt-Injections abschwächen.



Verwandte Themen