AI-Agent-State-Machine-Design: Warum komplexe Workflows nicht nur auf Prompts setzen können

Ein Reporting-Agent scheiterte kurz vor dem E-Mail-Versand in Schritt 5. Der Betrieb startete den Task erneut. Der Agent begann wieder bei Schritt 1, erzeugte einen neuen Report und überschrieb die bereits genehmigte Version. Der Approval-State ging verloren. Die Signatur des Freigebenden wurde durch das neue Ergebnis ersetzt, und kein Log konnte mehr beweisen, dass die erste Report-Version genehmigt war.

Das war kein Datenbank-Rollback-Problem und auch kein einfacher Queue-Retry. Im Prompt stand nur noch “weiterverarbeiten”. Das Modell leitete den gesamten Ablauf neu ab und wusste nicht, dass Schritt 1 bis 4 bereits Side Effects erzeugt hatten: Approval-API aufgerufen, Report generiert, temporäre Datei geschrieben. Der Fehler lag in Schritt 5, aber die Side Effects begannen schon in Schritt 2.

Das eigentliche Problem war nicht, ob das Modell stark genug war. Der Task-Fortschritt steckte als natürliche Sprache im Prompt, ohne wiederherstellbaren State Snapshot. Messages im Prompt sind Modellkontext, keine Ausführungsfakten.

Um so einen Incident zu beheben, reicht kein zusätzlicher Prompt-Satz wie “vor dem Fortfahren Fortschritt prüfen”. Stabiler ist es, aktuellen Node, bereits entstandene Side Effects, nächste Action und Failure Compensation in eine recoverbare State Table zu schreiben.

Kernpunkte des Incidents

Ausführungsfluss des Reporting-Agents:

Schritt	Operation	Side Effect	Idempotenz
Schritt 1	Datenabfrage	Ruft die Datenbank auf und liest User-Daten	Idempotent (Read Operation)
Schritt 2	Report-Erzeugung	Ruft das Report-Tool auf und erzeugt ein PDF	Nicht idempotent (überschreibt Datei)
Schritt 3	Approval-Wait	Sendet Approval Request und wartet auf menschliche Freigabe	Idempotent (API unterstützt es)
Schritt 4	Approval akzeptiert	Empfängt approve Event	Idempotent (Statusabfrage)
Schritt 5	E-Mail senden	Ruft E-Mail-API auf und sendet Report	Fehlgeschlagen (Timeout)

Fehlerursache: Der E-Mail-Versand in Schritt 5 lief wegen Rate Limiting der externen API in einen Timeout. Der Task wurde als FAILED markiert.

Rerun-Logik: “aktuellen Fortschritt” aus dem Prompt lesen. Der Prompt enthielt nur “genehmigt, weiterverarbeiten”. Tatsächliche Ausführung: wieder bei Schritt 1 starten -> in Schritt 2 Report neu erzeugen (genehmigte Version überschreiben) -> in Schritt 3 erneut Approval anfordern -> in Schritt 5 erfolgreich senden.

Business Impact: Der genehmigte Report wurde ersetzt, Approval-Record und ausgelieferter Report passten nicht mehr zusammen. Der User beschwerte sich, dass der genehmigte Report nicht dem empfangenen Report entsprach. Der Approval-Prozess wurde verschwendet: Zwei Versionen wurden genehmigt, aber nur eine wurde wirklich versendet.

Anti-Pattern-Erkennung

Prüfen Sie, ob Ihr Agent eines dieser Anti-Patterns trifft:

Anti-Pattern	Erscheinungsbild	Risiko	Korrektur
Fortschritt im Prompt	Natürliche Sprachzusammenfassung wie “aktuell bei Schritt 3”	Nach Neustart verloren, nicht recoverbar	Aktuellen Node in einem State-Feld speichern
Trace als State	Vollständiger Trace wird für State gehalten	Trace entscheidet nicht über den nächsten Schritt	State speichert, was als Nächstes passieren soll
Retry ohne Idempotenzprüfung	Bei Fehler von vorne rerunnen	Side Effects werden doppelt ausgeführt	Idempotency Key + Already-executed Check
Resume nach Approval ohne Prüfung	Direkt weiterlaufen	Falscher Ausführungspunkt	checkpoint + thread_id

1. State-Machine-Grundlagen: State, Event, Transition, Guard, Action

Eine State Machine ist nicht für jeden Agent nötig. Ein einfacher Customer-Support-Q&A kann mit einem messages-Array auskommen. Komplexe Tasks mit mehreren Schritten, Approval, externen Systemaufrufen und Recovery nach Fehlern müssen Fortschritt jedoch explizit machen.

1.1 Tabelle der Kernbegriffe

Die Grundbegriffe stammen aus der Stately-Dokumentation:

Begriff	Definition	Agent-Beispiel	Quelle
State	Modus, in dem sich die Maschine befindet, mit eindeutiger semantischer Absicht	INIT, PLAN_READY, TOOL_RUNNING, APPROVAL_PENDING, FAILED, COMPLETED	Stately state machines
Event	Externes Signal, das State-Wechsel auslöst	timeout, approve, reject, retry, resume, task_received	Stately state machines
Transition	Erlaubter Pfad zwischen States, als deterministische Zuordnung	INIT -> PLAN_READY (event: task_received)	Stately state machines
Guard/Condition	Vorbedingung für den Eintritt in einen State	Nur bei ausreichendem Budget nach TOOL_RUNNING wechseln	Stately state machines
Action	Operation, die während einer Transition ausgeführt wird	Beim Eintritt in TOOL_RUNNING ein Tool aufrufen	Stately state machines
Checkpoint	State Snapshot für Recovery	LangGraph checkpointer speichert graph state	LangGraph Persistence

Determinismus-Prinzip: Dieselbe Kombination aus State + Event sollte genau einen Next State ergeben, damit keine Mehrdeutigkeit entsteht. Endliche State-Menge: Eine State Machine ist kein unendliches Flowchart, sondern eine endliche Menge erreichbarer States plus klare Transition-Regeln.

1.2 Trace vs State vs Audit im Vergleich

Trace, Audit Log und State Snapshot lösen drei verschiedene Probleme:

Konzept	Gelöstes Problem	Business State?	Entscheidet nächsten Schritt?	Agent-Beispiel
Trace	Beobachtung und Diagnosegerüst	Nein	Nein	OpenAI Agents SDK trace (workflow_name, trace_id)
Audit Log	Compliance Record und Audit Trail	Nein	Nein	Audit-Felder im Permission Model (actor, traceId, action, result)
State Snapshot	Aktueller State, der den nächsten Schritt bestimmt	Ja	Ja	LangGraph checkpoint (aktueller Node, erledigte Schritte, was als Nächstes passieren soll)

Die Abgrenzung ist entscheidend: Ein Trace zeigt, was passiert ist, ist aber nicht der Business State selbst. Ein Audit Log hält Compliance-Historie fest. Ein State Snapshot bestimmt, was als Nächstes passieren soll, und ist damit der Kern der Recovery. Diese drei Dinge ersetzen einander nicht: Trace bedeutet nicht State, Audit bedeutet nicht Recovery.

2. Wie LangGraph State Persistence umsetzt

Ein Checkpoint ist keine natürliche Sprachzusammenfassung im Prompt, sondern ein wiederherstellbarer, prüfbarer und replay-fähiger State Snapshot. Die LangGraph-Persistence-Dokumentation definiert einen Checkpoint als graph state snapshot mit vollständigem State und den nächsten auszuführenden Nodes.

2.1 Checkpointer und Thread State

Kernmechanismen (laut LangGraph Persistence):

• Checkpointer: speichert thread-scoped State Snapshots (graph state snapshots)
• Store: speichert thread-übergreifende Langzeitdaten (application-defined store)
• Thread_id: eindeutiger Einstiegspunkt zur Recovery eines konkreten Thread State
• Vier Einsatzzwecke: conversation continuity, human-in-the-loop, time travel, fault tolerance

LangGraph Persistence legt kurzfristigen thread-scoped State in Checkpointern ab und thread-übergreifende Langzeitdaten in Stores. Ein Checkpoint enthält State Snapshot und application-defined store. Thread_id ist der Recovery-Einstieg; mit derselben thread_id kann am Pause Point weitergemacht werden.

Ein LangGraph-Checkpoint enthält graph state, Liste der nächsten auszuführenden Nodes, checkpoint_id, Zeitstempel und Version. Sensitive Daten gehören nicht blind in den Checkpoint: Manche graph-state-Felder können vertrauliche Informationen enthalten und müssen explizit vom Speichern ausgeschlossen werden.

2.2 Interrupts und Recovery-Mechanismus

Kernmechanismen (laut LangGraph Interrupts):

• interrupt(): pausiert Ausführung dynamisch innerhalb eines Graph-Node, speichert graph state und wartet auf externen Input
• Recovery-Methode: dieselbe thread_id und Command(resume=…) verwenden
• Übliche Muster: Approval, review/edit, tool call review, human input validation
• Warnung zu idempotenten Side Effects: Side Effects vor interrupt müssen idempotent sein, weil der Node beim Resume vom Anfang des interrupt-Node erneut läuft

Eine Approval-Pause muss ein Pause-State in der State Machine sein, nicht die Hoffnung, dass das Modell “sich merkt, auf Approval zu warten”. Recovery braucht denselben Thread Cursor.

Recovery nutzt dieselbe thread_id und Command(resume=…). Idempotente Side Effects sind Voraussetzung. Wenn vor dem Approval ein Side Effect liegt, etwa ein externer API-Call, muss dieser idempotent sein. Sonst ruft der wiederaufgenommene Node die API erneut auf.

3. Engineering-Analogie: Temporal Durable Execution

Zuverlässigkeit langer Tasks ist kein neues Problem. Temporal durable execution liefert eine reife Analogie.

3.1 Definition von Durable Execution

Kernkonzepte (laut Temporal Durable Execution):

• Durable Execution: workflow execution bewahrt state/progress bei Fehlern, Crashes oder Service-Unterbrechungen
• Event History: zeichnet jeden State-Schritt auf, damit nach Fehlern vom letzten aufgezeichneten Event recoveriert werden kann
• Drei Eigenschaften: Resumable, Recoverable, Reactive

Zuverlässigkeit langer Tasks entsteht durch event history und recoverbare Ausführung, nicht durch Speicher eines einzelnen Prozesses oder Prompt-Kontext. Eine Agent-State-Machine braucht etwas Ähnliches: checkpoint/event log + Business State, nicht nur erneute Modellinferenz.

Temporal Event History und LangGraph checkpoint sind konzeptionell verwandt: Beide zeichnen Ausführungshistorie auf und ermöglichen Recovery vom Fehlerpunkt. Der Unterschied: Temporal ist eine vollständige Workflow Engine, LangGraph ein Framework für Agent State Management. Die Lehre für Agent-Entwickler ist klar: Durable Execution braucht strukturierte State-History, nicht Prozessspeicher oder Modellkontext.

4. State-Table-Vorlage: Eine kopierbare Agent State Table

State-Machine-Konzepte sind abstrakt. Für die Umsetzung braucht es ein konkretes State Model. Die folgenden drei Vorlagen decken State Table, Event Table und einen incident-getriebenen State-Table-Fall ab.

4.1 State-Table-Vorlage (ausführbarer Schrittblock)

Vorlagenstruktur:

State	Event	Guard	Erforderliche Action	Next
INIT	task_received	Keine	Kontext initialisieren, Startzeit aufzeichnen	PLAN_READY
PLAN_READY	plan_generated	plan_valid	Ausführungsplan erzeugen, Tool-Sequenz speichern	TOOL_RUNNING
TOOL_RUNNING	tool_completed	budget_sufficient	Tool aufrufen, Ergebnis speichern, Budget aktualisieren	APPROVAL_PENDING oder COMPLETED
APPROVAL_PENDING	approve	approval_required	Approval Request senden, Freigebenden speichern	COMPLETED
APPROVAL_PENDING	reject	Keine	Ablehnungsgrund speichern, User benachrichtigen	FAILED
FAILED	retry	retry_count < max	Idempotenz prüfen, auf vorherigen Checkpoint zurückgehen	TOOL_RUNNING oder APPROVAL_PENDING
COMPLETED	Keine	Keine	Completion-Zeit speichern, Ressourcen aufräumen	Terminal

Erläuterung: Die State-Spalte definiert alle erreichbaren States (INIT, PLAN_READY, TOOL_RUNNING, APPROVAL_PENDING, FAILED, COMPLETED). Die Event-Spalte definiert auslösende Events (task_received, approve, reject, retry). Die Guard-Spalte definiert Vorbedingungen (budget_sufficient, retry_count < max). Die Action-Spalte definiert Pflichtoperationen während der Transition. Die Next-Spalte definiert den deterministischen Next State.

4.2 Event-Table-Vorlage (Ergänzung zur State Table)

Vorlagenstruktur:

Event-Name	Auslöser	Erforderlicher Vor-State	Nach-State	Erzeugt Side Effects?
task_received	User übermittelt Task	INIT	PLAN_READY	Nein
plan_generated	LLM erzeugt Ausführungsplan	PLAN_READY	TOOL_RUNNING	Nein
tool_completed	Tool-Ausführung abgeschlossen	TOOL_RUNNING	APPROVAL_PENDING oder COMPLETED	Ja (externer API-Call)
approve	Freigebender stimmt zu	APPROVAL_PENDING	COMPLETED	Ja (E-Mail senden, Budget abziehen)
reject	Freigebender lehnt ab	APPROVAL_PENDING	FAILED	Nein
retry	Retry Request nach Fehler	FAILED	TOOL_RUNNING oder APPROVAL_PENDING	Idempotenzprüfung nötig
timeout	Ausführung läuft in Timeout	TOOL_RUNNING	FAILED	Nein

Erläuterung: Der erforderliche Vor-State macht explizit, in welchen States ein Event akzeptiert werden darf. Die Side-Effect-Spalte markiert, welche Events Idempotenz oder Compensation brauchen.

4.3 Incident-getriebenes State-Table-Beispiel (aus dem Report-Overwrite-Fall)

Vollständiges Beispiel: State Table für den Reporting-Agent aus dem Einstieg

State	Event	Guard	Action	Next	Idempotenz-/Compensation-Prüfung
INIT	task_received	Keine	thread_id initialisieren, Startzeit speichern	QUERY_RUNNING	Nicht nötig
QUERY_RUNNING	query_completed	Keine	Daten abfragen, Ergebnis in State speichern	REPORT_GENERATING	Nicht nötig
REPORT_GENERATING	report_generated	Keine	Report erzeugen, Report-ID in State speichern	APPROVAL_PENDING	Idempotenzcheck: Wenn Report existiert, Generation überspringen
APPROVAL_PENDING	approve	Keine	Freigebenden und Approval-Zeit speichern	EMAIL_SENDING	Nicht nötig
APPROVAL_PENDING	reject	Keine	Ablehnungsgrund speichern	FAILED	Nicht nötig
EMAIL_SENDING	email_sent	Keine	E-Mail senden, E-Mail-ID speichern	COMPLETED	Idempotenzcheck: Wenn E-Mail schon gesendet wurde, überspringen
EMAIL_SENDING	timeout	retry_count < 3	Fehler speichern, Idempotenz prüfen	EMAIL_SENDING (Retry) oder FAILED	Idempotency Key: email_id + thread_id
FAILED	retry	retry_count < max	Idempotenz prüfen, aus vorherigem Checkpoint recovern	QUERY_RUNNING oder REPORT_GENERATING oder EMAIL_SENDING	Recovery Point per Checkpoint bestimmen
COMPLETED	Keine	Keine	Completion-Zeit speichern, Ressourcen aufräumen	Terminal	Nicht nötig

Korrektur des Incidents: Wenn Schritt 5 fehlschlägt (EMAIL_SENDING -> timeout), sollte Recovery bei EMAIL_SENDING beginnen, nicht bei QUERY_RUNNING. Der Checkpoint muss aktuellen Node (EMAIL_SENDING), erledigte Schritte (QUERY, REPORT_GENERATED, APPROVAL_APPROVED) und nächste Action (EMAIL_SENDING) speichern. Report-Erzeugung und E-Mail-Versand brauchen Idempotency Keys, damit Side Effects nicht doppelt laufen.

5. Idempotenz und Compensation: Recovery ist mehr als Checkpoint

Ein Checkpoint bedeutet nicht, dass alle Side Effects sicher recoverbar sind. Recovery braucht außerdem Idempotenz, Transaktionen, Compensation und Prüfungen des externen Systemzustands.

5.1 Konzepte von Idempotenz und Compensation

Definitionen:

• Idempotent: Mehrfache Ausführung führt zum gleichen Ergebnis und erzeugt keine doppelten Side Effects
• Compensation: Bereits eingetretene Side Effects rückgängig machen und Konsistenz wiederherstellen
• Transaction Rollback: Atomare Operation rollt bei Fehler automatisch zurück
• Externe Zustandsprüfung: Vor Recovery den externen Systemzustand prüfen, um doppelte Operationen zu vermeiden

Drei Säulen der State Consistency: Idempotenz-Identität (action_id + schema_hash), State-Snapshot-Chain (snapshot + prev_hash + delta) und registrierte Compensation Action (undo_op).

5.2 Checkliste für Idempotenz und Compensation

So entscheiden Sie, welche Operationen Idempotenz und welche Compensation brauchen:

Operationstyp	Braucht Idempotenz?	Braucht Compensation?	Idempotency-Key-Design	Compensation-Plan
Datenabfrage (kein Side Effect)	Nein	Nein	-	-
Report-Erzeugung (überschreibt Datei)	Ja	Ja	report_id + thread_id	Neuen Report löschen, genehmigte Version wiederherstellen
E-Mail-Versand (externe API)	Ja	Schwierig	email_id + thread_id	In manchen Fällen Korrektur- oder Widerrufs-Mail senden
Lagerbestand abziehen (Datenbank)	Ja	Ja	inventory_id + order_id	Bestand wieder erhöhen
Ticket erstellen (externes System)	Ja	Ja	ticket_id + thread_id	Ticket schließen
Budget abziehen (interner State)	Ja	Ja	budget_id + thread_id	Budget wieder erhöhen
Approval Request senden (kein dauerhafter Side Effect)	Nein	Nein	-	-

Entscheidungslogik: Ob eine Operation externe Side Effects erzeugt, entscheidet über Idempotenzbedarf. Rückgängig machbare Operationen brauchen Compensation. Bei systemübergreifenden Calls sollte der Idempotency Key eine externe Systemkennung enthalten. Atomare Operationen können Transaction Rollback nutzen.

Recovery ist nicht nur Checkpoint. Sie braucht Idempotenz, Transaktionen, Compensation und externe Zustandsprüfungen. Die Aussage, ein Checkpoint könne alle Side Effects sicher recovern, ist ungenau.

6. Agent-Task-State-Checkliste: Recoverbar vs nicht recoverbar

Nicht jeder Checkpoint kann recovern. Terminal State ist der Endzustand einer workflow execution: abgeschlossen, fehlgeschlagen, timeout oder cancelled. Ein Terminal State kann nicht fortgesetzt werden, sondern nur neu ausgeführt oder kompensiert.

6.1 State-Klassifikationstabelle

State-Typ	Recoverbar?	Recovery-Bedingung	Recovery-Methode	Beispiel
Failed	Ja	retry_count < max	Aus vorherigem Checkpoint recovern	Tool-Call-Timeout
Retry	Ja	Idempotenzcheck bestanden	Vom Fehler-Node erneut ausführen	E-Mail-Versand fehlgeschlagen
Compensation	Teilweise	Compensation-Plan existiert	undo_op ausführen	Lagerabzug fehlgeschlagen
Approval Pause	Ja	approve/reject Event	Command(resume=…)	Warten auf Approval
Terminal	Nein	Keine	Kein Recovery-Pfad	COMPLETED, FAILED (retry_count = max)

Erläuterung: Ein Failed State kann per retry recovern, solange retry_count < max. Ein Retry State braucht eine Idempotenzprüfung und führt vom Fehler-Node erneut aus. Ein Compensation State ist teilweise recoverbar, wenn ein Compensation-Plan existiert. Approval Pause recoveriert durch approve/reject Event. Terminal State ist nicht recoverbar, etwa COMPLETED oder FAILED nach maximaler Retry-Anzahl.

7. Weiterführende Lektüre

State-Machine-Design ist nur der Anfang. State Modeling muss zum konkreten Business-Szenario passen; verschiedene Tasks brauchen unterschiedliche State-Granularität und Recovery-Strategien.

Navigation innerhalb der Serie

Artikel	Beziehung	Link
Human-in-the-loop Agent Design: Welche Schritte menschliches Approval brauchen	Details zu Approval Pause	/blog/de/posts/ai/20260707-human-in-the-loop-agent-approval-design/
Agent Cost Control: Model Routing, Tool Budgets und Failure Retry	Budget- und Retry-Strategie	/blog/de/posts/ai/20260707-agent-cost-control-model-routing-tool-budget-cache-retry/
LangGraph State Management in der Praxis: Agent-Architektur-Best-Practices 2026	LangGraph State Management	/blog/de/posts/ai/20260424-langgraph-agent-architecture/
AI-Agent Monitoring, Alerting und Failure Recovery: Von Logs zu State Machines	Monitoring und Recovery	/blog/de/posts/ai/20260527-ai-agent-monitoring-recovery/
LangGraph vs AutoGen State Tracking	Framework-Vergleich	/blog/de/posts/ai/20260526-langgraph-autogen-state-tracking/
Agent Evaluation Datasets und Regression Tests: Wie eine Änderung nicht das ganze System beschädigt	Evaluation und Regression Tests	Vorschau, nächster Artikel der Serie

Externe Referenzen

Quellen mit hoher Vertrauenswürdigkeit:

Quelle	Vertrauen	Thema	Link
LangGraph Persistence Dokumentation	high	Checkpointer, Store, Thread State, Checkpoint	https://docs.langchain.com/oss/python/langgraph/persistence
LangGraph Interrupts Dokumentation	high	interrupt(), Command(resume=…), thread_id	https://docs.langchain.com/oss/python/langgraph/interrupts
Temporal Durable Execution Dokumentation	high	Event History, Durable Execution, Resumable/Recoverable	https://docs.temporal.io/temporal
OpenAI Agents SDK Tracing Dokumentation	high	Trace, Span, workflow_name, trace_id	https://openai.github.io/openai-agents-python/tracing/
AWS Step Functions State Machines Dokumentation	high	State Machine, Flow State, Task State, StartAt, Next	https://docs.aws.amazon.com/step-functions/latest/dg/concepts-statemachines.html
Stately: State machines and statecharts	medium	State, Event, Transition, Guard, Action, Hierarchy	https://stately.ai/docs/state-machines-and-statecharts

Eine State Machine ist nicht für jeden Agent nötig, aber komplexe Tasks müssen ihren Fortschritt explizit machen. Der nächste Schritt ist nicht, mehr Frameworks einzuführen. Entscheidend ist, für Ihr Business-Szenario passende State, Event, Transition, Guard und Action zu entwerfen und Task-Fortschritt aus natürlicher Prompt-Sprache in strukturierten State zu verschieben.