Was ist LangGraph? Eine Anleitung zum Entwickeln zustandsbehafteter KI-Agenten

Die meisten Agenten-Codes beginnen einfach und kollabieren dann unter ihren eigenen Wiederholungsversuchen. Man verbindet ein LLM, gibt ihm einige Tools, und sobald der Workflow Schleifen, Verzweigungen oder eine Pause für einen Menschen benötigt, bricht das geradlinige Skript zusammen. LangGraph ist das Framework, das genau für dieses Chaos entwickelt wurde: Es modelliert einen Agenten als Graphen mit gemeinsamem Zustand, sodass Schleifen und Verzweigungen zu erstklassigen Strukturen statt zu verschachtelten if-Anweisungen werden. Dieser Leitfaden erklärt, was LangGraph ist, welches Problem es löst 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 zum Erstellen langlebiger, zustandsbehafteter Agenten. Es wird von LangChain Inc, dem Team hinter LangChain, entwickelt, ist aber eine eigenständige Bibliothek mit eigenem Fokus. Sie installieren es separat mit pip install -U langgraph, und Sie können es ohne den Rest des LangChain-Ökosystems verwenden.

Die Kernidee ist einfach. Sie beschreiben Ihren Agenten als einen Graphen. Knoten erledigen Arbeit (rufen ein Modell auf, führen ein Tool aus, transformieren Daten). Kanten entscheiden, was als Nächstes ausgeführt wird. Ein gemeinsames Zustandsobjekt fließt durch jeden Knoten, und jeder Knoten kann es lesen und darauf zurückschreiben. Da Kanten rückwärts zeigen können, kann der Graph Schleifen bilden. Das ist der Teil, den eine einfache Kette nicht gut kann.

Wenn Sie die ältere Chain-Abstraktion von LangChain verwendet haben, liegt der Unterschied in der Form des Kontrollflusses. Eine Kette ist eine Pipeline: Schritt eins, Schritt zwei, Schritt drei, fertig. Ein Graph ermöglicht es einem Knoten, den aktuellen Zustand zu inspizieren, dann zu einem anderen Zweig zu springen, zur Wiederholung zurückzuschleifen oder sich auf mehrere parallel laufende Knoten aufzuteilen und deren Ergebnisse zusammenzuführen. Echte Agenten brauchen das, denn „denken, handeln, beobachten, erneut denken“ ist eine Schleife, keine Linie.

Das Problem, das LangGraph löst

Agentische Workflows sind von Natur aus zyklisch. Ein Agent ruft ein Tool auf, betrachtet das Ergebnis, entscheidet, ob er fertig ist, und falls nicht, versucht er es erneut. Dies mit verschachtelten Bedingungen zu modellieren, wird schnell unleserlich, und es wird schlimmer, sobald man die Dinge hinzufügt, die Produktionsagenten tatsächlich benötigen:

• Schleifen mit einer Abbruchbedingung. Tools weiter aufrufen, bis die Aufgabe abgeschlossen ist, ohne endlos zu laufen.
• Verzweigung basierend auf dem Zustand. Zu einem anderen Knoten leiten, je nachdem, was das Modell zurückgegeben hat.
• Persistenz. Einen Absturz, ein Timeout oder einen Neustart überstehen und vom letzten gültigen Punkt fortfahren.
• Human-in-the-loop. Pausieren, eine Person den Zustand prüfen oder bearbeiten lassen, dann fortfahren.
• Streaming. Token und Zwischenschritte sofort ausgeben, nicht erst am Ende.

LangGraph verwandelt jede dieser Anforderungen in eine integrierte Funktion, anstatt sie manuell implementieren zu müssen. Sie erhalten eine Zustandsmaschine mit dauerhafter Ausführung, sodass ein Agent Minuten oder Stunden laufen und dort fortfahren kann, wo er aufgehört hat.

Kernkonzepte: Graph, Zustand, Knoten, Kanten

Vier Primitive bilden den Großteil des Frameworks. So passen sie zusammen.

Zustand ist ein typisiertes Objekt, das über den gesamten Lauf geteilt wird. Sie definieren seine Form mit einem Schema, oft einem TypedDict, und LangGraph führt die Aktualisierungen jedes Knotens darin zusammen. Ein gängiger Ausgangspunkt ist MessagesState, ein vorgefertigtes Schema, das eine laufende Liste von Chat-Nachrichten enthält.

Knoten sind Funktionen. Jeder nimmt den aktuellen Zustand entgegen und gibt ein partielles Update zurück. Sie registrieren sie mit add_node().

Kanten verbinden Knoten. Eine normale Kante mit add_edge() führt immer von A nach B. Eine bedingte Kante mit add_conditional_edges() führt eine Routing-Funktion aus, die den Zustand liest und den Namen des nächsten Knotens zurückgibt. So drücken Sie aus: „Wenn das Modell nach einem Tool gefragt hat, führe es aus; andernfalls beende.“

START und END sind spezielle Marker dafür, wo die Ausführung beginnt und endet.

So sieht ein minimaler Graph aus. Es ist Pseudocode-Niveau, aber die API-Namen sind real.

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")   # loop back

graph = builder.compile()

Die Zeile add_edge("tools", "model") ist der Zyklus. Nachdem Tools ausgeführt wurden, geht die Kontrolle zurück an das Modell, das weitere Tools aufrufen oder stoppen kann. Diese Schleife ist der Hauptgrund für die Existenz von LangGraph.

Persistenz und Human-in-the-Loop

Kompilieren Sie einen Graphen mit einem Checkpointer, und er speichert nach jedem Schritt einen Snapshot des Zustands. Übergeben Sie eine thread_id in der Konfiguration, und LangGraph stellt den letzten Checkpoint für diesen Thread beim nächsten Aufruf wieder her. Ihre Knoten ändern sich nicht; die Laufzeitumgebung übernimmt das Speichern und Wiederherstellen.

from langgraph.checkpoint.memory import InMemorySaver

graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [user_message]}, config)

InMemorySaver ist für die Entwicklung ausreichend. Für etwas, das Neustarts übersteht, liefert LangGraph datenbankgestützte Saver (SQLite für einen einzelnen Server, Postgres für Multi-Instanz-Skalierung). Da der Zustand persistent ist, erhalten Sie auch Human-in-the-Loop nahezu kostenlos. Sie können den Graphen an einem ausgewählten Punkt unterbrechen, den aktuellen Zustand für eine Person zur Überprüfung oder Bearbeitung bereitstellen und dann genau von diesem Checkpoint aus fortfahren. Genehmigungsschritte, manuelle Korrekturen und „Sind Sie sicher?“-Schritte basieren alle darauf.

Streaming rundet das Ganze ab. LangGraph kann Modell-Token und Knoten-Updates streamen, während der Lauf fortschreitet, sodass eine Benutzeroberfläche den Agenten beim Denken zeigen kann, anstatt nur einen Ladekreis anzuzeigen.

Wie LangGraph mit LangChain zusammenhängt

Dies verwirrt viele, deshalb wollen wir direkt sein. LangChain ist das breitere Toolkit: Modell-Wrapper, Prompt-Templates, Retriever, Dokumentenlader und Integrationen mit Hunderten von Anbietern. LangGraph ist die Orchestrierungsschicht unter den Agenten-Teilen dieses Toolkits.

Sie benötigen LangChain nicht, um LangGraph zu verwenden. Sie können Ihren Zustand, Ihre Knoten und Kanten definieren und jeden beliebigen Modell-Client innerhalb eines Knotens aufrufen. Die Modell- und Tool-Abstraktionen von LangChain sind praktisch, aber LangGraphs vorgefertigter create_react_agent-Helfer (in langgraph.prebuilt) bietet Ihnen einen funktionierenden Tool-aufrufenden Agenten in wenigen Zeilen, wenn Sie keinen benutzerdefinierten Graphen benötigen.

Ein Hinweis für aktuelle Benutzer: Die LangGraph v1.0-Linie (stabil seit Ende 2025) hat den vorgefertigten Agenten-Helfer in Richtung langchain.agents.create_agent verschoben. Überprüfen Sie daher Ihre installierte Version und die offizielle Referenz für den genauen Importpfad, bevor Sie ältere Code-Schnipsel kopieren. Das Erstellen benutzerdefinierter Agenten von Grund auf ist hier ebenfalls eine nützliche Fähigkeit; sehen Sie sich unser Tutorial zum Erstellen eines benutzerdefinierten KI-Agenten an, um das Gesamtbild zu erhalten.

LangGraph Plattform und Studio

Die Open-Source-Bibliothek ist der Kern, aber zwei angrenzende Produkte werden relevant, sobald Sie deployen.

LangGraph Studio ist eine visuelle Agenten-IDE. Es rendert Ihren Graphen, lässt Sie ihn ausführen und zeigt den Zustand an jedem Knoten, sodass Sie die Ausführung Schritt für Schritt durch Ihre Knoten und Kanten verfolgen können. Für alles, was Zyklen und bedingtes Routing beinhaltet, ist es besser, den tatsächlichen Pfad des Agenten zu sehen, als Protokollzeilen zu lesen.

LangGraph Plattform ist die verwaltete Bereitstellungsseite: API-Endpunkte für Ihre Agenten, integrierte Persistenz für lang laufende Ausführungen und Hosting-Optionen, die von selbst gehostet bis vollständig in der Cloud verwaltet reichen. Sie benötigen es nicht, um die Bibliothek zu nutzen; es ist da, wenn Sie Infrastruktur für Agenten in der Produktion wünschen, anstatt sie selbst zu betreiben.

Wann LangGraph zu verwenden ist

Greifen Sie zu LangGraph, wenn Ihr Agent einen echten Kontrollfluss hat. Gute Anzeichen sind:

• Die Arbeit ist eine Schleife, keine Sequenz (Tools aufrufen, prüfen, wiederholen).
• Sie müssen basierend auf der Entscheidung des Modells verzweigen.
• Eine Ausführung kann lange dauern, und Sie möchten, dass sie einen Absturz übersteht und fortgesetzt werden kann.
• Ein Mensch muss etwas während der Ausführung genehmigen oder bearbeiten.
• Sie koordinieren mehrere Akteure oder Unteragenten, die sich einen Zustand teilen.

Verzichten Sie darauf, wenn ein einzelner Modellaufruf oder eine kurze lineare Kette die Aufgabe erledigt. Ein Graph ist ein Overhead, den Sie für „diesen Text zusammenfassen“ nicht benötigen. Heben Sie sich die Struktur für Workflows auf, die wirklich verzweigen und Schleifen bilden.

Wo API-Tests und Mocking ins Spiel kommen

Das ist der Teil, der Teams in der Entwicklung zu schaffen macht. Ein LangGraph-Agent ist nur so zuverlässig wie die APIs, die er aufruft, und er ruft viele davon auf: den LLM-Endpunkt, plus jede Tool-API (Suche, ein CRM, Ihr eigenes Backend). LangGraph orchestriert diese Aufrufe; es testet sie nicht. Das ist eine separate Aufgabe, und hier kommt Apidog ins Spiel.

Zwei Probleme treten schnell auf. Erstens verbraucht das Aufrufen von Live-APIs bei jedem Testlauf Token und überschreitet Ratenbegrenzungen. Sie können die API mocken, von der ein Agent abhängt, sodass ein Tool-Endpunkt eine deterministische, sofortige Antwort zurückgibt, während Sie an der Graphenlogik iterieren. Mocken Sie den LLM-Endpunkt auf die gleiche Weise, und Sie zahlen nicht mehr für Token, nur um das Routing zu testen.

Zweitens nehmen Ihre Knoten eine bestimmte Antwortstruktur an. Wenn die API eines Tools still und heimlich einen Feldnamen ändert, liest Ihre bedingte Kante das Falsche, und der Agent gerät in eine Schleife oder blockiert. Das Festlegen dieser Verträge mit API-Assertions fängt die Abweichung ab, bevor sie Ihren Graphen erreicht. Und da Agenten Schlüssel über Staging und Produktion hinweg jonglieren, sorgt die Verwaltung in Umgebungen dafür, dass Geheimnisse nicht in Ihrem Knotencode landen. Wenn Sie den vollständigen Agenten-fokussierten Workflow wünschen, führt Sie der Apidog Test-Harness für KI-Agenten Schritt für Schritt hindurch. Um es klarzustellen: Keines davon orchestriert den Agenten; Apidog testet und mockt die darunter liegenden APIs.

Häufig gestellte Fragen

Ist LangGraph ein Ersatz für LangChain? Nein. LangGraph ist die Orchestrierungs-Laufzeitumgebung; LangChain ist das umfassendere Set an Komponenten und Integrationen. Sie sind separate Bibliotheken desselben Teams, und Sie können LangGraph ohne LangChain ausführen oder sie zusammen verwenden. LangGraph handhabt den zustandsbehafteten, zyklischen Kontrollfluss, mit dem einfache Ketten zu kämpfen haben.

Muss ich LangChain kennen, um mit LangGraph zu beginnen? Nein. Sie können einen StateGraph definieren, Knoten und Kanten hinzufügen und jeden beliebigen Modell-Client innerhalb eines Knotens aufrufen. Die Modell-Wrapper von LangChain sind praktisch, aber optional. Beginnen Sie mit den Kern-Graphen-Primitiven und fügen Sie den Rest nur hinzu, wenn Sie ihn benötigen.

Wie merkt sich LangGraph Dinge zwischen Aufrufen? Durch Checkpointer. Kompilieren Sie Ihren Graphen mit einem Checkpointer und übergeben Sie eine thread_id, und LangGraph speichert nach jedem Schritt einen Zustandsschnappschuss und stellt ihn dann beim nächsten Aufruf für diesen Thread wieder her. So erhalten Sie Konversationsgedächtnis und Absturzwiederherstellung, ohne Ihre Knotenlogik ändern zu müssen.

Wie teste ich die APIs, die mein Agent aufruft? Testen und mocken Sie diese getrennt vom Graphen. Mocken Sie die LLM- und Tool-Endpunkte, damit die Ausführungen während der Entwicklung schnell und kostenlos sind, und setzen Sie Assertions auf die Antwortstrukturen, damit ein geändertes Feld keinen Knoten beschädigt. Unser Leitfaden zum Testen der ChatGPT API behandelt Authentifizierung, Streaming und Tool-Aufrufe, welche genau die Schnittstellen sind, von denen ein Agent abhängt.

Zusammenfassung

LangGraph bietet Ihnen die fehlende Struktur für Agenten, die Schleifen bilden, verzweigen, persistent sind und für einen Menschen pausieren. Modellieren Sie den Workflow als Graphen mit gemeinsamem Zustand, verlassen Sie sich auf Checkpointer für Speicher und Wiederherstellung, und nutzen Sie Studio und die Plattform, wenn Sie bereit zum Debuggen und Bereitstellen sind. Das Framework übernimmt die Orchestrierung. Die APIs, die Ihr Agent aufruft, benötigen immer noch ihr eigenes Sicherheitsnetz. Mocken und testen Sie sie daher in Apidog, um die Entwicklung kostengünstig und Ihre Tool-Verträge ehrlich zu halten. Laden Sie Apidog herunter, um einen Endpunkt zu mocken und seine Antworten zu überprüfen, bevor Ihr Agent ihn wirklich aufruft.