System-Nachrichten 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. Sie 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.

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

Prompt-Caching hasht das Anfrage-Präfix in dieser Reihenfolge: tools, dann system, dann messages. Ein Cache-Treffer erfordert, dass das Präfix exakt mit einer kürzlichen Anfrage übereinstimmt, Byte für Byte, 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.
• Kontext pro Turn, 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 soll. 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 teuren Fähigkeit zu erteilen, etwa dem automatischen Starten von Multi-Agent-Workflows, mit einer kurzen Auffrischung alle paar Turns und einem Beendigungshinweis, wenn der Modus ausgeschaltet wird. Ein ausgearbeitetes Beispiel findest du unter Einen Orchestrierungsmodus bauen.

In all diesen Fällen könntest du die Anweisung auch in eine reguläre user-Nachricht packen, 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 also 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 zahlen.

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 weiterhin das Top-Level-Feld system 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-4-8",
    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.",
        },
    ],
)

print(response.content[0].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 als 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 einer Server-Tool-Nutzung 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. Die einzige Position, die nicht erlaubt ist, ist zwischen einem assistant-tool_use-Block und dem tool_result, das ihn beantwortet.

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 die Angabe dessen, 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 Dritten 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 tut), 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 sind nicht erlaubt; fasse Anweisungen in einer Nachricht zusammen oder warte auf den nächsten User-Turn, bevor du eine weitere anhängst.

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 Server-Tool-Nutzung 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