LangGraph: zustandsbehaftete Agenten-Workflows verständlich erklärt
Viele Agenten-Prototypen bestehen aus einer Schleife: Modell fragen, Tool aufrufen, wiederholen. Das reicht für eine Demo, aber nicht für einen Prozess, der über Stunden läuft, eine Freigabe durch die Fachabteilung braucht und nach einem Serverneustart weitermachen muss. Genau dafür ist LangGraph gebaut. Dieser Leitfaden erklärt das Modell dahinter, die Abgrenzung zu LangChain und wann sich der Aufwand lohnt. Stand: Oktober 2026, LangGraph 1.2.18.
Was ist LangGraph und wofür wird es eingesetzt?
LangGraph ist ein Open-Source-Framework von LangChain, das Agenten und Workflows als Graph aus Funktionen mit gemeinsamem Zustand ausführt. Es kümmert sich um Ablaufsteuerung, Zwischenspeicherung, Pausen für menschliche Entscheidungen und Streaming. Eingesetzt wird es dort, wo ein Agent nachvollziehbar, unterbrechbar und wiederaufnehmbar sein muss.
Die offizielle Übersicht beschreibt LangGraph als „low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents". Wichtig ist das Wort low-level: LangGraph schreibt Ihnen weder Prompts noch eine Agenten-Architektur vor. Es liefert die Laufzeit, auf der Sie beides selbst festlegen.
Laut PyPI ist die aktuelle Version 1.2.18 vom 26. Oktober 2026, die Lizenz ist MIT, vorausgesetzt wird Python 3.10 oder neuer. Version 1.0 erschien am 22. Oktober 2025; LangChain hat dabei zugesagt, bis zur Version 2.0 keine inkompatiblen Änderungen vorzunehmen. Für Unternehmen, die einen Agenten mehrere Jahre betreiben wollen, ist diese Stabilitätszusage ein relevantes Auswahlkriterium.
Typische Einsatzmuster:
- Mehrstufige Fachprozesse: Anfrage einlesen, Daten aus ERP und Dokumenten zusammentragen, Entwurf erzeugen, Freigabe einholen, versenden.
- Agenten mit Prüfpunkten: Ein Agent darf Tools aufrufen, aber bestimmte Aktionen (Bestellung auslösen, Mail an Externe senden) nur nach menschlicher Bestätigung.
- Lang laufende Aufgaben: Recherchen oder Auswertungen, die Minuten bis Stunden dauern und einen Absturz überstehen müssen.
- Mehrere spezialisierte Agenten: Teilgraphen für Recherche, Prüfung und Formulierung, die ein übergeordneter Graph koordiniert.
Was unterscheidet LangGraph von LangChain?
LangChain ist die Bibliothek für Bausteine und schnelle Agenten: Modellanbindungen, Tool-Definitionen und seit Version 1.0 die Funktion create_agent. LangGraph ist die darunterliegende Laufzeit für Ablauf, Zustand und Persistenz. Sie können LangGraph ohne LangChain nutzen, umgekehrt läuft jeder LangChain-Agent auf LangGraph.
Beides ist in der Dokumentation belegt: Die Übersicht stellt klar, dass Sie LangChain für LangGraph nicht brauchen, und der Release-Beitrag zu Version 1.0 sagt, dass create_agent „uses LangGraph under the hood". Mit 1.0 wurde zudem das Modul langgraph.prebuilt abgekündigt; dessen fertige Agenten-Funktionen sind nach langchain.agents umgezogen.
Für die Praxis heißt das:
- Ein Agent mit Modell, Tools und Systemprompt ohne besondere Ablauflogik:
create_agentaus LangChain genügt. Sie bekommen trotzdem Checkpointing, weil darunter LangGraph läuft. - Ein fester Prozess mit Verzweigungen, Freigaben und deterministischen Schritten zwischen den Modellaufrufen: Hier modellieren Sie den Graphen selbst in LangGraph.
- Mischformen: Ein selbst gebauter Graph kann einen
create_agent-Agenten als einen von mehreren Knoten enthalten.
Einen Vergleich mit anderen Frameworks wie dem OpenAI Agents SDK, CrewAI oder dem Claude Agent SDK finden Sie im Überblick über KI-Agenten-Frameworks. Dieser Leitfaden geht dagegen in die Tiefe eines einzigen Frameworks: wie LangGraph intern arbeitet und was das für Ihren Betrieb bedeutet. Der Unterschied zum Claude Agent SDK liegt vor allem in der Steuerung: Dort führt das Modell die Agenten-Schleife selbst und Sie greifen über Hooks und Berechtigungen ein, in LangGraph legen Sie den Ablauf als Graph fest und das Modell arbeitet nur in den Knoten, die Sie dafür vorsehen.
Wie funktioniert LangGraph? Die Bausteine
Ein LangGraph-Programm besteht aus einem Zustandsobjekt, Knoten (Python-Funktionen), die diesen Zustand lesen und Änderungen zurückgeben, und Kanten, die festlegen, welcher Knoten als Nächstes läuft. Kompiliert wird das Ganze zu einem ausführbaren Graphen, an den Sie Speicher und Prüfpunkte hängen.
Die Graph-API-Dokumentation fasst es knapp zusammen: „nodes do the work, edges tell what to do next". Im Einzelnen:
- State: meist ein
TypedDict, alternativ Dataclass oder Pydantic-Modell (mit Validierung, aber langsamer). Er ist die einzige Wahrheit über den aktuellen Stand eines Laufs. - Reducer: legen je Feld fest, wie Updates eingearbeitet werden. Standard ist Überschreiben; mit
operator.addwerden Listen verlängert, mitadd_messageswerden Nachrichten angehängt oder anhand ihrer ID aktualisiert. - Nodes: synchrone oder asynchrone Funktionen, die den State bekommen und ein Teil-Update zurückgeben. Darin kann ein Modellaufruf stehen, eine Datenbankabfrage oder reine Geschäftslogik.
- Edges: feste Kanten mit
add_edge, bedingte Kanten mitadd_conditional_edges, die eine Routing-Funktion auswerten.STARTundENDmarkieren Ein- und Ausgang. - Command und Send:
Commandkombiniert ein State-Update mit einem Sprungziel,Sendverteilt Arbeit auf eine vorher unbekannte Zahl paralleler Knotenaufrufe (Map-Reduce). compile(): prüft die Struktur, etwa auf verwaiste Knoten, und nimmt Checkpointer und Haltepunkte entgegen. Ohne Kompilieren läuft nichts.
Ausgeführt wird in sogenannten Super-Steps, angelehnt an Googles Pregel-System: Alle Knoten, die gleichzeitig aktiv werden, laufen in einem Super-Step parallel; der Lauf endet, wenn kein Knoten mehr aktiv ist. Seit Version 1.0.6 bricht LangGraph nach standardmäßig 1.000 Super-Steps mit GraphRecursionError ab, damit eine fehlerhafte Schleife nicht endlos Modellkosten erzeugt.
Checkpointing: der eigentliche Kern
Ein Checkpointer speichert den Zustand eines Laufs nach jedem Super-Step, zugeordnet zu einer thread_id. Das ist die Grundlage für Gesprächsgedächtnis, Freigaben, Wiederaufnahme nach Fehlern und das Zurückspringen auf frühere Stände.
Laut Checkpointer-Dokumentation gibt es diese Implementierungen:
| Paket | Klasse | Einsatz laut Doku |
|---|---|---|
langgraph-checkpoint (enthalten) | InMemorySaver | Experimente; nach Neustart ist alles weg |
langgraph-checkpoint-sqlite | SqliteSaver | lokale Entwicklung |
langgraph-checkpoint-postgres | PostgresSaver | Produktion |
langgraph-checkpoint-mongodb | MongoDBSaver | Produktion |
Mit graph.get_state(config) lesen Sie den aktuellen Stand, mit get_state_history alle früheren Checkpoints, mit update_state legen Sie einen neuen Checkpoint mit korrigierten Werten an, ohne den alten zu verändern. Fortsetzen lässt sich ein Lauf nur an einer Super-Step-Grenze. Über die Option durability steuern Sie, wann geschrieben wird: "exit" erst am Ende (schnell, aber kein Wiederanlauf mitten im Lauf), "async" parallel zum nächsten Schritt, "sync" vor jedem nächsten Schritt (am sichersten, etwas langsamer).
Für Wissen, das über einzelne Läufe hinaus gilt, etwa Vorlieben eines Nutzers oder gelernte Fakten, gibt es zusätzlich einen Store: einen Schlüssel-Wert-Speicher, der über Threads hinweg gilt.
Interrupts: Pausen für Menschen
Mit interrupt() hält ein Knoten den Graphen an und übergibt eine Frage nach außen. Der Lauf ruht im Checkpointer, bis Ihre Anwendung ihn mit Command(resume=...) und derselben thread_id fortsetzt, auch Tage später und aus einem anderen Prozess.
Dieses Muster heißt Human-in-the-Loop: Der Mensch entscheidet an fest definierten Stellen, der Agent erledigt den Rest. Das folgende Beispiel zeigt das Muster an einem Angebotsentwurf mit Freigabe. Es kommt ohne Modellaufruf aus, damit es sofort läuft; getestet mit langgraph 1.2.18 und Python 3.14, Stand Oktober 2026.
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import interrupt, Command
class State(TypedDict):
anfrage: str
entwurf: str
freigegeben: bool
def entwurf_erstellen(state: State) -> dict:
# hier stünde der LLM-Aufruf
return {"entwurf": f"Angebotsentwurf zu: {state['anfrage']}"}
def freigabe(state: State) -> dict:
# pausiert den Graphen, bis ein Mensch entscheidet
ok = interrupt({"bitte_pruefen": state["entwurf"]})
return {"freigegeben": bool(ok)}
def route(state: State) -> str:
return "versenden" if state["freigegeben"] else END
def versenden(state: State) -> dict:
print("versendet:", state["entwurf"])
return {}
builder = StateGraph(State)
builder.add_node("entwurf_erstellen", entwurf_erstellen)
builder.add_node("freigabe", freigabe)
builder.add_node("versenden", versenden)
builder.add_edge(START, "entwurf_erstellen")
builder.add_edge("entwurf_erstellen", "freigabe")
builder.add_conditional_edges("freigabe", route)
builder.add_edge("versenden", END)
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "anfrage-4711"}}
result = graph.invoke({"anfrage": "Ersatzteil 12-B"}, config)
print(result["__interrupt__"])
# später, mit dauerhaftem Checkpointer auch in einem anderen Prozess:
graph.invoke(Command(resume=True), config)
Der erste invoke endet am Interrupt und liefert die Prüffrage unter __interrupt__. Der zweite setzt mit der Entscheidung fort. Für den Produktivbetrieb tauschen Sie InMemorySaver gegen PostgresSaver.
Welche Varianten und Einsatzfelder gibt es?
LangGraph lässt sich auf drei Ebenen nutzen: als explizit modellierter Graph, als Functional API mit normalem Python-Kontrollfluss und indirekt über create_agent aus LangChain. Dazu kommen Teilgraphen für Systeme aus mehreren Agenten. Welche Ebene passt, hängt davon ab, wie fest Ihr Prozess ist.
Graph API. Sie deklarieren State, Knoten und Kanten. Vorteil: Der Ablauf ist sichtbar, lässt sich darstellen und an jedem Super-Step prüfen. Das passt zu Prozessen, die eine Fachabteilung ohnehin als Ablaufdiagramm beschreiben kann, etwa die Angebotserstellung mit Prüf- und Freigabeschritten.
Functional API. Mit den Dekoratoren @entrypoint und @task schreiben Sie gewöhnliche Python-Funktionen mit if und Schleifen und bekommen trotzdem Persistenz, Interrupts und Streaming. Laut Dokumentation entfällt die explizite State-Definition; dafür lässt sich der Ablauf nicht als Graph visualisieren, weil er erst zur Laufzeit entsteht. Beide APIs laufen auf derselben Laufzeit und lassen sich mischen.
create_agent als Einstieg. Wer zunächst nur einen Agenten mit Tools braucht, startet in LangChain und wechselt erst dann in eigene Graphen, wenn feste Prozessschritte dazukommen. Der Wechsel ist kein Neuanfang, weil beide Ebenen dieselbe Laufzeit teilen.
Mehrere Agenten über Teilgraphen. Ein kompilierter Graph kann Knoten in einem übergeordneten Graphen sein. So bauen Sie etwa einen Recherche-Agenten und einen Prüf-Agenten getrennt und verbinden sie in einem Koordinationsgraphen. Teilgraphen führen laut Doku einen eigenen Checkpoint-Namensraum; Daten, die über Graphgrenzen hinweg gelten sollen, gehören in den Store. Wann sich mehrere Agenten gegenüber einem einzelnen überhaupt lohnen, behandelt der Leitfaden zu Multi-Agenten-Systemen.
Als Anwendungsfelder im Unternehmen bieten sich Prozesse mit klaren Übergaben an: Serviceanfragen im technischen Service, Recherchen im Wissensmanagement oder Vorqualifizierung im Vertrieb. Was sich in diesen Bereichen typischerweise automatisieren lässt, zeigt die Übersicht zu KI-Agenten.
Welche Voraussetzungen braucht ein LangGraph-Projekt?
Sie brauchen Python-Kenntnisse im Team, eine Datenbank für Checkpoints im Produktivbetrieb, Zugang zu einem Sprachmodell und einen beschriebenen Prozess mit klaren Entscheidungspunkten. Fehlt das Letzte, hilft kein Framework: LangGraph macht Abläufe explizit, es erfindet sie nicht.
Im Detail:
- Technik: Python 3.10 oder neuer (für 1.2.18). Eine PostgreSQL- oder MongoDB-Instanz für den
PostgresSaverbzw.MongoDBSaver. Ein Weg, den Graphen als Dienst zu betreiben, etwa als Container hinter einer internen API. - Modellzugang: Ein Cloud-Modell per API oder ein selbst betriebenes Modell. LangGraph ist hier neutral; die Entscheidung hängt an Datenschutz und Kosten. Wer Modelle im eigenen Haus betreiben will, findet Hintergründe unter souveräne KI.
- Daten und Systeme: Lesende und schreibende Zugriffe auf ERP, CRM oder Dokumentablage als Tools, mit eigenen, eng begrenzten Berechtigungen.
- Organisation: Eine verantwortliche Person aus der Fachabteilung, die Freigabepunkte festlegt und Ergebnisse bewertet. Ohne sie bleibt unklar, wo ein Interrupt sitzen muss.
- Kompetenz: Das Team muss Konzepte wie Reducer, Super-Steps und Idempotenz verstehen. Die Lernkurve ist spürbar steiler als bei Frameworks, die nur eine Agenten-Schleife anbieten.
Wie gehen Sie bei einem LangGraph-Projekt vor?
Bewährt hat sich, mit dem Prozess statt mit dem Code zu beginnen: Schritte und Entscheidungen aufzeichnen, daraus State und Knoten ableiten, Freigabepunkte setzen, erst dann Modellaufrufe einbauen. So bleibt der deterministische Anteil groß und der Modellanteil dort, wo er wirklich nötig ist.
- Prozess skizzieren. Welche Schritte, welche Daten, welche Entscheidungen, wer gibt frei? Ein Ablaufdiagramm auf Papier reicht.
- State definieren. Welche Felder braucht jeder Schritt? Für welche Felder ist Anhängen statt Überschreiben richtig (Nachrichten, gesammelte Belege)?
- Knoten schreiben, zunächst ohne Modell. Platzhalterlogik wie im Beispiel oben zeigt, ob Routing und Freigaben stimmen.
- Modellaufrufe und Tools einsetzen. Jeweils in einen eigenen Knoten, mit klarer Ein- und Ausgabe.
- Persistenz festlegen.
PostgresSaverfür den Betrieb,durabilitypassend zur Laufzeit wählen,thread_idaus einer fachlichen ID ableiten (unter 255 Zeichen, wie die Persistenz-Doku für Postgres verlangt). - Beobachtbarkeit herstellen. Über die Stream-Modi
updates,tasksoderdebugsehen Sie, welcher Knoten was geändert hat. Ob Sie dafür LangSmith oder ein eigenes Logging nutzen, ist eine Betriebsentscheidung; was im laufenden Betrieb von Agenten sonst noch zu überwachen ist, beschreibt der Beitrag zu AgentOps. - Mit echten Fällen testen. Vergangene Vorgänge durchspielen, Ergebnisse mit der Fachabteilung bewerten, dann erst Schreibrechte freigeben.
Wenn Sie Ideen für den ersten Prozess suchen, ist ein strukturierter Workshop mit den Fachbereichen oft der schnellere Weg als eine technische Bestandsaufnahme.
Welche Grenzen und Risiken hat LangGraph?
LangGraph löst Ablauf und Zustand, nicht Qualität. Ein schlecht geschnittener Prozess wird durch einen Graphen nicht besser, und die Freiheit des Low-Level-Ansatzes bringt Komplexität mit sich. Dazu kommen einige technische Fallen, die man kennen sollte, bevor ein Agent produktiv schreibt.
- Lernkurve. Reducer, Super-Steps, Checkpoint-Namensräume von Teilgraphen und Durability-Modi sind eigene Konzepte. Für einen einfachen Frage-Antwort-Agenten ist das Overhead.
- Knoten starten nach einem Interrupt neu. Laut Interrupt-Dokumentation läuft beim Fortsetzen der gesamte Knoten von vorn. Code vor
interrupt()wird also mehrfach ausgeführt. Nicht idempotente Aktionen, etwa eine Bestellung, gehören hinter den Interrupt oder in einen eigenen Knoten. - Kein pauschales
try/exceptuminterrupt(). Der Interrupt arbeitet intern mit einer Ausnahme; ein breiterexceptfängt sie ab und verhindert die Pause. - Wiederholte Modellaufrufe. Beim Zurückspringen auf einen früheren Checkpoint laufen alle folgenden Knoten erneut, inklusive Modellaufrufe und API-Anfragen. Das kostet Geld und kann Seiteneffekte doppeln.
- Wachsende Checkpoint-Datenbank. Checkpoints sammeln sich an und erhöhen Speicherbedarf und Latenz. Sie brauchen eine Aufbewahrungsregel.
InMemorySaverist kein Produktivspeicher. Nach einem Neustart sind alle Läufe und offenen Freigaben verloren.- Abhängigkeit vom Ökosystem. Die Bibliothek ist offen und lizenzfrei, aber Tracing und Hosting im Komfortpaket kommen von LangChain selbst. Planen Sie bewusst, welche Teile Sie selbst betreiben.
Wann LangGraph nicht passt: wenn Ihr Anwendungsfall eine einzelne Modellanfrage mit Dokumentensuche ist, wenn niemand im Team Python pflegt oder wenn der Prozess noch so unklar ist, dass sich kein Graph zeichnen lässt. Dann ist ein einfacheres Werkzeug oder zuerst Prozessarbeit sinnvoller.
Wie fange ich mit LangGraph an?
Starten Sie mit einem kleinen, echten Prozess mit genau einem Freigabepunkt, bauen Sie ihn zuerst ohne Modell und mit InMemorySaver, und wechseln Sie erst auf Postgres, wenn Routing und Freigabe stimmen. So lernen Sie die Konzepte an Ihrem eigenen Fall statt an Spielbeispielen.
Ein pragmatischer Einstieg in drei Schritten:
pip install langgraphin einer Umgebung mit Python 3.10 oder neuer, dann das Beispiel oben an einen eigenen Ablauf anpassen.- Einen Knoten durch einen echten Modellaufruf ersetzen und die Ausgabe über
stream_mode="updates"beobachten. PostgresSaveranbinden, den Prozess abbrechen und mit derselbenthread_idfortsetzen. Erst wenn das zuverlässig klappt, ist der Agent betriebsreif.
Wenn Sie noch zwischen Frameworks abwägen, hilft der Framework-Vergleich bei der Vorauswahl. Für die Frage, welche Prozesse sich überhaupt für Agenten eignen und wie diese im Unternehmen betrieben werden, ist die Übersicht zu KI-Agenten im Unternehmen der nächste Schritt.
Häufige Fragen
Brauche ich LangChain, um LangGraph zu nutzen?
Nein. Laut Dokumentation lässt sich LangGraph ohne LangChain einsetzen; LangChain ist nur bequem für die Anbindung von Modellen und Tools.
Ist LangGraph kostenlos?
Die Python-Bibliothek steht unter MIT-Lizenz und läuft auf eigener Infrastruktur. Kosten entstehen für die Modell-APIs, die Sie anbinden, und für optionale Dienste wie LangSmith.
Welche Python-Version setzt LangGraph voraus?
Version 1.2.18 vom Oktober 2026 verlangt laut PyPI Python 3.10 oder neuer.
Kann LangGraph mit lokalen Modellen arbeiten?
Ja. Nodes sind normale Python-Funktionen, darin können Sie jedes Modell aufrufen, auch ein selbst betriebenes. Die Ablaufsteuerung ist vom Modell unabhängig.
Was passiert, wenn der Server während eines Laufs abstürzt?
Mit einem dauerhaften Checkpointer und dem Modus durability="sync" setzt der Lauf am letzten gespeicherten Schritt wieder an. Mit dem In-Memory-Checkpointer gehen alle Zwischenstände verloren.
Quellen
- LangGraph Overview (LangChain Docs) docs.langchain.com
- LangGraph Graph API docs.langchain.com
- LangGraph Persistence docs.langchain.com
- LangGraph Checkpointers docs.langchain.com
- LangGraph Interrupts docs.langchain.com
- LangGraph Functional API docs.langchain.com
- LangGraph Streaming docs.langchain.com
- langgraph auf PyPI pypi.org
- LangChain and LangGraph Agent Frameworks Reach v1.0 Milestones langchain.com
- Claude Agent SDK overview code.claude.com