Anti-Pattern: Text auf Abschluss prüfen

Sie entwickeln einen Agenten. Er führt Tools aus, denkt nach und antwortet. Nun müssen Sie wissen, wann er fertig ist. Eine verlockende Abkürzung: Durchsuchen Sie den Text des Modells nach einem Wort wie done, finished oder complete und beenden Sie die Schleife, sobald Sie es sehen.

Dies ist das Anti-Pattern Text auf Abschluss analysieren. Es wirkt intuitiv, ist aber fragil und falsch. Die Claude API liefert Ihnen bereits ein präzises, strukturiertes Abschlusssignal. In dieser Lektion erfahren Sie, warum das Durchsuchen von Text fehlschlägt und was Sie stattdessen verwenden sollten.

Die agentische Schleife wird durch ein Feld in der Antwort gesteuert: stop_reason. Die Schleife ist einfach und deterministisch:

• Senden Sie die Anfrage (in jedem Durchlauf mit dem vollständigen Nachrichtenverlauf).
• Prüfen Sie stop_reason.
• Wenn der Wert tool_use lautet, führen Sie die Tools aus, fügen Sie die Ergebnisse zum Verlauf hinzu und wiederholen Sie den Vorgang.
• Wenn der Wert end_turn lautet, ist die Aufgabe abgeschlossen. Beenden Sie die Schleife.

Das Modell teilt Ihnen über strukturierte Metadaten selbst mit, ob es fortfahren möchte oder fertig ist. Sie müssen niemals durch das Lesen von Text vermuten, was gemeint ist.

Beenden Sie die Schleife anhand des Signals, nicht anhand der Worte. Claude gibt einen von vier Stoppgründen zurück:

• end_turn — Claude ist auf natürlichem Weg fertig geworden. Die Aufgabe ist abgeschlossen.
• tool_use — Claude möchte ein Tool ausführen lassen; führen Sie es aus und setzen Sie die Schleife fort.
• max_tokens — die Ausgabe wurde durch das Token-Limit abgeschnitten.
• stop_sequence — eine konfigurierte Stoppsequenz wurde erreicht.

Jeder dieser Gründe ist eindeutig und maschinenlesbar. Vergleichen Sie das mit dem Durchsuchen von Freitext, bei dem die Bedeutung vollständig davon abhängt, wie das Modell sich diesmal zufällig ausgedrückt hat.

Natürliche Sprache ist kein Steuerungsprotokoll. Dieselbe abgeschlossene Aufgabe kann auf ein Dutzend verschiedene Arten enden:

• "Alles erledigt!"
• "Damit ist die Migration abgeschlossen."
• "Ich habe die Analyse abgeschlossen."
• "Jetzt ist alles eingerichtet."

Ihre Schlüsselwortprüfung auf done findet das erste Beispiel, vielleicht auch das zweite, und übersieht die übrigen stillschweigend. Die Schleife endet nie. Sie verbrauchen Tokens und Zeit oder stoßen bei einer Aufgabe, die bereits vor mehreren Durchläufen abgeschlossen war, an ein hartes Limit.

Wenn Sie das Signal verpassen, verschwenden Sie Ressourcen. Der umgekehrte Fehler ist gefährlicher: zu früh zu stoppen.

Nehmen Sie an, der Benutzer bittet Claude zu prüfen, ob die Bereitstellung abgeschlossen ist. Claude könnte mitten in der Untersuchung antworten: "Ich überprüfe, ob die Bereitstellung abgeschlossen ist, bevor ich fortfahre." Ihr Scanner findet done und beendet die Schleife — die Aufgabe wird auf halbem Weg abgebrochen, bevor ein Tool ausgeführt oder eine Antwort erzeugt wurde.

Das Modell verwendet Wörter wie done im Gespräch. Ein Schlüsselwortvergleich kann erzählerische Aussagen nicht von einem echten Abschlusssignal unterscheiden. stop_reason kann das.

Hier liegt der tiefere Grund dafür, dass das Durchsuchen von Text auf der falschen Ebene ansetzt. Die Claude API ist zustandslos: Das Modell speichert zwischen Anfragen keine Informationen. Sie senden bei jedem einzelnen Aufruf die gesamte Unterhaltung — system, alle bisherigen messages-Durchläufe und Tool-Ergebnisse.

Die Frage "Ist der Agent fertig?" bezieht sich also auf die von Ihnen gesteuerte Schleife. Beantwortet wird sie durch den strukturierten Wert stop_reason, den die API zurückgibt — nicht durch Rückschlüsse aus dem Fließtext. Die Steuerungsebene (Ihre Schleife) und die Inhaltsebene (der Text des Modells) sind getrennt. Belassen Sie die Abschlusslogik auf der Steuerungsebene.

Steuern Sie die Schleife ausschließlich über stop_reason. Wenn der Wert tool_use lautet, führen Sie die angeforderten Tools aus und fügen Sie ihre Ergebnisse zusammen mit der passenden tool_use_id zum Verlauf hinzu. Wenn der Wert end_turn lautet, sind Sie fertig.

Das funktioniert unabhängig davon, wie Claude seine abschließende Nachricht formuliert — "Alles erledigt", "Fertig" oder überhaupt nichts. Die Entscheidung basiert auf vertrauenswürdigen Metadaten und nicht auf einem Zeichenfolgenvergleich, den Sie ständig überwachen müssen.

Ein wichtiges Architekturprinzip: In einer agentischen Schleife wird der Ablauf vom Modell entschieden und über stop_reason sichtbar gemacht. Sie schreiben nicht vor: "Nach 3 Tools musst du fertig sein." Claude signalisiert, wann es ein weiteres Tool benötigt und wann es fertig ist.

Verwenden Sie fest codierte Steuerung nur für Dinge, die eine Garantie benötigen — eine deterministische Invariante, die Ihr Geschäftsprozess voraussetzt. Die Erkennung des Abschlusses gehört nicht dazu; die API stellt sie bereits sauber bereit. Eine selbst entwickelte Lösung mit Textanalyse ersetzt ein zuverlässiges Signal durch eine Vermutung.

"Gut", sagen Sie, "dann beende ich die Schleife einfach nach N Iterationen." Vorsicht: Ein Iterationslimit ist ein Sicherheitsnetz, nicht der primäre Mechanismus zum Beenden. Es soll endlos laufende Schleifen begrenzen und vor Fehlern schützen — nicht entscheiden, dass die Arbeit abgeschlossen ist.

Wenn Ihre Schleife darauf angewiesen ist, dass das Limit sie normal beendet, haben Sie dasselbe Problem wie beim Durchsuchen von Text: Sie ersetzen das echte, modellgesteuerte Signal durch eine willkürliche Heuristik. Beenden Sie die Schleife zuerst anhand von stop_reason; lassen Sie das Limit nur den Ausnahmefall abfangen.

Eine robuste Schleife verzweigt bei jedem Stoppgrund, nicht nur im Erfolgsfall. Insbesondere bedeutet max_tokens, dass die Antwort abgeschnitten wurde — es bedeutet nicht, dass sie abgeschlossen ist. Wenn Sie einen abgeschnittenen Durchlauf als "fertig" behandeln, liefern Sie stillschweigend eine halbe Antwort aus.

Wenn Sie max_tokens sehen, erhöhen Sie max_tokens oder wechseln Sie bei großen Ausgaben zu Streaming und setzen Sie anschließend die Schleife fort — beenden Sie sie niemals so, als wäre die Aufgabe erfolgreich abgeschlossen.

Manchmal soll das Modell beim Abschluss tatsächlich ein strukturiertes Ergebnis melden — etwa einen Status, eine Konfidenz oder eine Zusammenfassung. Die Lösung besteht auch dann nicht darin, Fließtext zu analysieren. Geben Sie Claude ein Tool (oder ein JSON Schema über strukturierte Ausgaben) und lassen Sie es ein typisiertes Ergebnis ausgeben.

Mit tool_choice: "any" können Sie das Modell zwingen, irgendein Tool aufzurufen, und so strukturierte Ausgaben statt Freitext sicherstellen. Die Schleife wird weiterhin anhand von stop_reason beendet; das Tool überträgt lediglich das maschinenlesbare Ergebnis. Struktur ersetzt überall dort, wo es darauf ankommt, den Zeichenfolgenvergleich.

Sie wissen nun, warum das Durchsuchen der Ausgabe nach einem Abschluss das falsche Werkzeug für diese Aufgabe ist:

• Beenden Sie die Schleife anhand von stop_reason, niemals anhand von Text. end_turn = abgeschlossen; tool_use = Tools ausführen und fortfahren.
• Das Durchsuchen von Text ist in beide Richtungen fehleranfällig — es übersieht echte Abschlüsse (unterschiedliche Formulierungen) und erzeugt falsch positive Treffer (die Verwendung von "done" im Gespräch).
• Die API ist zustandslos und modellgesteuert. Senden Sie in jedem Durchlauf den vollständigen Verlauf; lassen Sie das strukturierte Signal und nicht den Fließtext die Schleife steuern.
• Iterationslimits sind ein Sicherheitsnetz, nicht der primäre Mechanismus zum Beenden. Behandeln Sie max_tokens als Abbruch der Ausgabe, nicht als Erfolg.
• Benötigen Sie ein strukturiertes Ergebnis? Verwenden Sie ein Tool oder ein JSON Schema (erzwingen Sie es mit tool_choice: "any") — analysieren Sie niemals Freitext.