Checkpointing einer langen Agent-Aufgabe: Fortschrittsdateien, idempotente Schritte und Wiederaufnahme

Ziel

Jede Unterbrechung einer langen Aufgabe soll höchstens einen Arbeitsschritt kosten und keinen doppelten Nebeneffekt verursachen – unabhängig davon, ob die Unterbrechung ein Prozessabsturz, ein zurückgesetztes Kontextfenster oder eine Übergabe an einen anderen Agenten ist.

Voraussetzungen

Eine Aufgabe, die sich als Abfolge von Schritten mit beobachtbaren Abschlusskriterien formulieren lässt, ein Ort zum Schreiben von Dateien, der die Unterbrechung übersteht, sowie externe Systeme, deren Schreiboperationen entweder einen Idempotenzschlüssel akzeptieren oder abgefragt werden können, was bereits geschehen ist.

Schritte

1. Vor dem ersten Nebeneffekt eine Plandatei schreiben: nummerierte Schritte, für jeden die Abschlussprüfung («Datei existiert und lässt sich parsen», «Datensatz 4711 hat Status sent», «Testsuite grün») sowie die Eingaben, von denen die Schritte abhängen.
2. Daneben eine Fortschrittsdatei führen und sie nach jedem abgeschlossenen Schritt aktualisieren, nicht davor: Schrittnummer, Zeitstempel, der Nachweis des Abschlusses (ein Hash, eine Kennung, der Exit-Status eines Befehls) sowie alles, was der nächste Schritt braucht und in diesem gelernt wurde.
3. Jedem externen Schreibvorgang einen aus Aufgabe und Schritt abgeleiteten Idempotenzschlüssel mitgeben, damit eine nach einem Absturz wiederholte Anfrage vom Empfänger erkannt statt doppelt ausgeführt wird; hat der Empfänger keinen solchen Mechanismus, zuerst die Wirkung abfragen und den Schreibvorgang überspringen, falls sie bereits vorliegt.
4. Jeden Schritt isoliert neu startbar machen: Er liest seine Eingaben aus Dateien oder Kennungen, nie aus dem Gespräch, und toleriert seine eigene unvollständige Ausgabe aus einem früheren Versuch (überschreiben oder bereinigen, nie blind anhängen).
5. Bei der Wiederaufnahme Plan und Fortschrittsdatei lesen, den Nachweis des letzten verzeichneten Schritts gegen den tatsächlichen Zustand prüfen (der Datensatz ist wirklich versendet, die Datei lässt sich wirklich parsen) und beim ersten ungeprüften Schritt fortfahren. Der Fortschrittsdatei allein nie vertrauen; erst prüfen, dann fortsetzen.
6. Unterwegs getroffene Entscheidungen samt Begründung in der Fortschrittsdatei festhalten, damit ein wiederaufgenommener Lauf sie nicht erneut aufrollt, und offene Unklarheiten ausdrücklich vermerken, damit sie nicht mit geklärten Punkten verwechselt werden.
7. Am Ende die Abschlusszusammenfassung aus der Fortschrittsdatei schreiben, die bis dahin jeden Schritt mit Nachweis enthält; danach beide Dateien mit der Kennung des Laufs archivieren.

Erwartetes Ergebnis

Ein an beliebiger Stelle unterbrochener Lauf lässt sich allein anhand der Dateien vom selben oder einem anderen Agenten wieder aufnehmen, wiederholt höchstens den gerade laufenden Schritt und erzeugt keinen doppelten externen Effekt.

Grenzen und Prüfbasis

Ein vorgeschlagenes Protokoll. Es setzt Schritte mit prüfbarem Abschluss voraus; Arbeit, deren einziges Artefakt Verständnis ist (Lesen, Erkunden), braucht eine schriftliche Notiz als Nachweis, was eine schwächere Prüfung darstellt. Idempotenz hängt davon ab, dass das empfangende System den Schlüssel respektiert.

Nicht abfragbare Effekte: Die Absicht zuerst festhalten

Bei einem Schritt, dessen Wirkung sich nachträglich nicht abfragen lässt (eine gesendete Nachricht, ein an Dritte zugestellter Webhook, eine erfasste Zahlung ohne Abfrage-Endpunkt), die Reihenfolge von Schritt 2 umkehren: vor der Wirkung einen Absichtsdatensatz mit dem reservierten Idempotenzschlüssel schreiben, die Wirkung ausführen, dann den Abschlussdatensatz schreiben. Ein wiederaufgenommener Lauf, der eine Absicht ohne Abschluss vorfindet, weiss, dass die Wirkung eingetreten sein kann oder nicht, und muss den Empfänger mit demselben Schlüssel befragen oder den Schritt an eine Person übergeben, statt ihn zu wiederholen. Beide Datensätze atomar schreiben (temporäre Datei, dann umbenennen), damit ein Absturz während des Schreibens keine halb geschriebene Fortschrittsdatei hinterlassen kann.