Die meisten Agenten-Codes starten als einfaches Skript und brechen zusammen, sobald Wiederholungen, Verzweigungen oder ein Human-in-the-Loop nötig werden. LangGraph löst dieses Problem, indem es Agenten als Graphen mit gemeinsamem Zustand modelliert: Knoten führen Arbeit aus, Kanten steuern den nächsten Schritt, und Schleifen werden explizit statt in verschachtelten if-Blöcken versteckt. Dieser Leitfaden zeigt, wie LangGraph funktioniert, wann Sie es einsetzen sollten und wo API-Tests ins Spiel kommen, wenn Ihr Agent echte Dienste aufruft.
Was LangGraph ist
LangGraph ist ein Low-Level-Orchestrierungs-Framework und eine Laufzeitumgebung für langlebige, zustandsbehaftete Agenten. Es wird von LangChain Inc. entwickelt, ist aber eine eigenständige Bibliothek.
Installation:
pip install -U langgraph
Sie können LangGraph ohne den Rest des LangChain-Ökosystems verwenden.
Die Grundidee:
- Sie beschreiben den Agenten als Graphen.
- Knoten führen Arbeit aus, zum Beispiel Modellaufrufe, Tool-Aufrufe oder Datenumformungen.
- Kanten entscheiden, welcher Knoten als Nächstes ausgeführt wird.
- Ein gemeinsames Zustandsobjekt wird durch den Graphen gereicht.
- Kanten können zurückspringen und dadurch Schleifen bilden.
Das ist der entscheidende Unterschied zu einer linearen Chain. Eine klassische Pipeline läuft Schritt für Schritt durch. Ein LangGraph-Agent kann dagegen prüfen, verzweigen, ein Tool erneut aufrufen, pausieren oder mehrere Pfade zusammenführen.
Das Problem, das LangGraph löst
Agentische Workflows sind selten linear. Ein typischer Agent läuft eher so:
- Nutzeranfrage lesen.
- Modell aufrufen.
- Prüfen, ob ein Tool benötigt wird.
- Tool ausführen.
- Ergebnis bewerten.
- Entweder fertig werden oder erneut zum Modell zurückspringen.
Als Skript wird daraus schnell ein schwer wartbarer Block aus Schleifen, Bedingungen und Fehlerbehandlung. In Produktion kommen weitere Anforderungen dazu:
- Schleifen mit Abbruchbedingung: Tools wiederholen, aber Endlosschleifen vermeiden.
- Routing basierend auf Zustand: Je nach Modellantwort zu einem anderen Knoten wechseln.
- Persistenz: Nach Crash, Timeout oder Neustart am letzten gültigen Punkt fortfahren.
- Human-in-the-loop: Ausführung pausieren, Zustand prüfen oder ändern lassen, danach fortsetzen.
- Streaming: Tokens und Zwischenschritte sofort an UI oder Logs ausgeben.
LangGraph macht daraus keine Sonderfälle, sondern Kernfunktionen der Laufzeitumgebung.
Kernkonzepte: Graph, Zustand, Knoten, Kanten
LangGraph basiert hauptsächlich auf vier Primitiven.
Zustand
Der Zustand ist ein typisiertes Objekt, das über den gesamten Lauf geteilt wird. Häufig definieren Sie ihn mit einem TypedDict. Für Chat-Agenten ist MessagesState ein praktischer Startpunkt, weil es eine laufende Liste von Nachrichten enthält.
Knoten
Knoten sind Funktionen. Jeder Knoten erhält den aktuellen Zustand und gibt ein partielles Update zurück.
Kanten
Kanten verbinden Knoten.
-
add_edge()erstellt eine feste Verbindung von A nach B. -
add_conditional_edges()führt eine Routing-Funktion aus, die anhand des Zustands entscheidet, welcher Knoten als Nächstes kommt.
START und END
START und END markieren Beginn und Ende der Ausführung.
Ein minimaler Graph sieht so aus:
from langgraph.graph import StateGraph, START, END, MessagesState
def call_model(state: MessagesState):
response = model.invoke(state["messages"])
return {"messages": [response]}
def should_continue(state: MessagesState) -> str:
last = state["messages"][-1]
return "tools" if last.tool_calls else END
builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", tool_node)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model") # Schleife zurück zum Modell
graph = builder.compile()
Die wichtige Zeile ist:
builder.add_edge("tools", "model")
Damit entsteht der Zyklus. Nach einem Tool-Aufruf geht die Kontrolle zurück zum Modell. Das Modell kann weitere Tools anfordern oder die Ausführung beenden.
Persistenz und Human-in-the-Loop
Für langlebige Agenten sollten Sie den Graphen mit einem Checkpointer kompilieren. LangGraph speichert dann nach jedem Schritt einen Snapshot des Zustands.
Beispiel mit InMemorySaver:
from langgraph.checkpoint.memory import InMemorySaver
graph = builder.compile(checkpointer=InMemorySaver())
config = {
"configurable": {
"thread_id": "user-42"
}
}
graph.invoke(
{"messages": [user_message]},
config
)
Die thread_id identifiziert den Lauf beziehungsweise die Konversation. Beim nächsten Aufruf kann LangGraph den letzten Checkpoint für diesen Thread wiederherstellen.
InMemorySaver reicht für lokale Entwicklung. Für persistente Setups nutzen Sie datenbankgestützte Saver, zum Beispiel SQLite für einzelne Server oder Postgres für Multi-Instanz-Setups.
Persistenz ist auch die Basis für Human-in-the-Loop:
- Graph an einem definierten Punkt unterbrechen.
- Aktuellen Zustand anzeigen.
- Mensch prüft oder bearbeitet den Zustand.
- Graph wird vom Checkpoint aus fortgesetzt.
Typische Einsatzfälle sind Freigaben, manuelle Korrekturen oder Sicherheitsabfragen vor kritischen Aktionen.
Streaming ergänzt das Setup: LangGraph kann Modell-Tokens und Knoten-Updates während der Ausführung ausgeben, damit eine UI nicht nur einen Ladeindikator zeigt.
Wie LangGraph mit LangChain zusammenhängt
LangChain ist das breitere Toolkit: Modell-Wrapper, Prompt-Templates, Retriever, Dokumentenlader und Integrationen. LangGraph ist die Orchestrierungsschicht für zustandsbehaftete Agenten mit Zyklen und Verzweigungen.
Sie müssen LangChain nicht verwenden, um LangGraph einzusetzen. Sie können jeden beliebigen Modell-Client in einem Knoten aufrufen.
Wenn Sie keinen eigenen Graphen bauen möchten, bietet langgraph.prebuilt mit create_react_agent einen Helfer für einen Tool-aufrufenden Agenten. Prüfen Sie aber immer die Version und den Importpfad, weil sich die v1.0-Linie geändert hat.
| LangChain | LangGraph | |
|---|---|---|
| Rolle | Komponenten und Integrationen | Orchestrierung und Laufzeit |
| Kontrollfluss | Lineare Ketten | Graphen mit Zyklen und Verzweigungen |
| Integrierter Zustand | Begrenzt | Geteilt, typisiert, dauerhaft |
| Persistenz / Fortsetzen | Nicht im Fokus | Checkpointer + Thread-IDs |
| Am besten geeignet für | Zusammensetzen von Modellaufrufen und Tools | Zustandsbehaftete, mehrstufige Agenten |
Hinweis für aktuelle Nutzer: Die LangGraph-v1.0-Linie hat den vorgefertigten Agenten-Helfer stärker in Richtung langchain.agents.create_agent verschoben. Prüfen Sie deshalb vor dem Kopieren älterer Snippets die offizielle Referenz. Wenn Sie eigene Agenten von Grund auf bauen möchten, hilft auch das Tutorial zum Erstellen eines benutzerdefinierten KI-Agenten.
LangGraph Plattform und Studio
Die Open-Source-Bibliothek ist der Kern. Für Debugging und Deployment sind zwei angrenzende Produkte relevant.
LangGraph Studio
LangGraph Studio ist eine visuelle Agenten-IDE. Sie rendert den Graphen, führt ihn aus und zeigt den Zustand an jedem Knoten.
Das ist besonders nützlich, wenn Ihr Agent bedingtes Routing oder Schleifen nutzt. Statt nur Logs zu lesen, sehen Sie den tatsächlichen Pfad durch den Graphen.
LangGraph Plattform
LangGraph Plattform ist die verwaltete Deployment-Seite. Sie bietet API-Endpunkte für Agenten, integrierte Persistenz für lang laufende Ausführungen und Hosting-Optionen von Self-Hosting bis Cloud.
Sie benötigen die Plattform nicht, um LangGraph lokal oder in eigener Infrastruktur zu verwenden. Sie wird interessant, wenn Sie Agenten produktiv betreiben möchten, ohne die gesamte Laufzeitinfrastruktur selbst zu bauen.
Wann Sie LangGraph verwenden sollten
LangGraph lohnt sich, wenn Ihr Agent echten Kontrollfluss braucht.
Gute Signale:
- Die Aufgabe ist eine Schleife, keine reine Sequenz.
- Das Modell entscheidet, welcher Pfad als Nächstes ausgeführt wird.
- Tool-Aufrufe müssen wiederholt oder validiert werden.
- Eine Ausführung kann lange dauern.
- Sie brauchen Wiederaufnahme nach Crash oder Neustart.
- Ein Mensch muss während der Ausführung genehmigen oder eingreifen.
- Mehrere Unteragenten teilen sich denselben Zustand.
Verzichten Sie auf LangGraph, wenn ein einzelner Modellaufruf oder eine kurze lineare Chain ausreicht. Für „Fasse diesen Text zusammen“ ist ein Graph unnötiger Overhead.
Wo API-Tests und Mocking ins Spiel kommen
Ein LangGraph-Agent ist nur so zuverlässig wie die APIs, die er aufruft. Dazu gehören der LLM-Endpunkt und jede Tool-API, zum Beispiel Suche, CRM, Zahlungsdienst, internes Backend oder Datenbank-Service.
LangGraph orchestriert diese Aufrufe. Es testet sie nicht. Dafür brauchen Sie ein separates Setup, zum Beispiel Apidog.
Problem 1: Live-APIs machen Tests teuer und langsam
Wenn jeder lokale Testlauf echte LLM- und Tool-Endpunkte aufruft, entstehen schnell Kosten, Rate-Limits und instabile Tests.
Praktischer Ansatz:
- Tool-Endpunkte in Apidog definieren.
- Erwartete Responses mocken.
- Den LangGraph-Knoten gegen den Mock statt gegen die Live-API ausführen.
- Routing-Logik testen, ohne echte Tokens oder externe Systeme zu verbrauchen.
Sie können auch die API mocken, von der Ihr Agent abhängt, damit Tool-Aufrufe deterministische Antworten liefern.
Problem 2: Agenten hängen an Response-Strukturen
Ihre Knoten erwarten bestimmte Felder. Wenn eine Tool-API ein Feld umbenennt oder eine verschachtelte Struktur ändert, kann der Agent falsch routen, hängen bleiben oder in eine Schleife geraten.
Nutzen Sie dafür API-Assertions:
- Existiert das erwartete Feld?
- Hat es den erwarteten Typ?
- Ist ein Statuscode korrekt?
- Enthält die Antwort die Daten, die der nächste Knoten braucht?
So erkennen Sie Vertragsbrüche, bevor sie Ihren Graphen beschädigen.
Wenn Sie einen vollständigen agentenfokussierten Workflow aufbauen möchten, führt der Apidog Test-Harness für KI-Agenten Schritt für Schritt durch das Setup. Wichtig: Apidog orchestriert nicht den Agenten. Apidog testet und mockt die APIs, auf denen der Agent basiert.
Häufig gestellte Fragen
Ist LangGraph ein Ersatz für LangChain?
Nein. LangGraph ist die Orchestrierungs-Laufzeitumgebung für zustandsbehaftete, zyklische Workflows. LangChain ist das breitere Set aus Komponenten, Integrationen und Abstraktionen. Sie können beide zusammen verwenden oder LangGraph unabhängig einsetzen.
Muss ich LangChain kennen, um mit LangGraph zu beginnen?
Nein. Sie können direkt mit StateGraph, Knoten, Kanten und einem eigenen Modell-Client starten. LangChain-Wrapper sind praktisch, aber optional.
Wie merkt sich LangGraph Dinge zwischen Aufrufen?
Über Checkpointer. Sie kompilieren den Graphen mit einem Checkpointer und übergeben eine thread_id. LangGraph speichert nach jedem Schritt einen Zustandssnapshot und stellt ihn beim nächsten Aufruf für denselben Thread wieder her.
Wie teste ich die APIs, die mein Agent aufruft?
Testen Sie die APIs getrennt vom Graphen:
- LLM- und Tool-Endpunkte mocken.
- Deterministische Responses für Entwicklungs- und CI-Läufe verwenden.
- Assertions auf Response-Strukturen setzen.
- Umgebungen für Staging und Produktion getrennt verwalten.
Der Leitfaden zum Testen der ChatGPT API behandelt Authentifizierung, Streaming und Tool-Aufrufe, also genau die Schnittstellen, von denen viele Agenten abhängen.
Zusammenfassung
LangGraph gibt Agenten eine explizite Struktur für Schleifen, Verzweigungen, Persistenz und Human-in-the-Loop. Modellieren Sie den Workflow als Graphen, halten Sie Zustand zentral, nutzen Sie Checkpointer für Wiederaufnahme und verwenden Sie Studio oder Plattform, wenn Debugging und Deployment wichtiger werden.
LangGraph übernimmt die Orchestrierung. Die APIs darunter brauchen trotzdem ein eigenes Sicherheitsnetz. Mocken und testen Sie sie in Apidog, bevor Ihr Agent sie produktiv aufruft. Laden Sie Apidog herunter, um einen Endpunkt zu mocken und seine Antworten zu prüfen.
Top comments (0)