LangGraph-Tool-Aufrufe mit begrenzter Ausführung und Fehlerbehebung
Erstellen Sie einen LangGraph-Agenten für den Produktionsbetrieb, der Tool-Aufrufe, Wiederholungsbudgets, menschliche Freigaben und explizite Wiederherstellungspfade statt unbegrenzter Ausführung nutzt.
Zusammenfassung · TL;DR
Ein Agent für den Produktionsbetrieb sollte nicht endlos Wiederholungen ausführen oder Seiteneffekte blind erneut auslösen dürfen. LangGraph bietet ein Graph- und Persistenzmodell, mit dem sich die Ausführung pausieren lässt. Ihr Workflow sollte außerdem Wiederholungsbudgets, Idempotenzregeln, Eskalationspfade und Wiederherstellungszustände festlegen. HumanInTheLoopMiddleware kann riskante Tool-Aufrufe abfangen und sie nach einer Freigabe, Bearbeitung oder Ablehnung oder nach einer direkten Antwort von einem Checkpoint aus fortsetzen.
Kernaussagen
- Unterscheiden Sie vor einer Wiederholung zwischen vorübergehenden und dauerhaften Fehlern.
- Begrenzen Sie die Ausführung sowohl mit einem Wiederholungsbudget pro Tool als auch mit einem Schrittlimit auf Graph-Ebene.
- Verwenden Sie Idempotenzschlüssel für Tools, die Produktionsressourcen erstellen, löschen oder ändern.
- Lassen Sie destruktive oder extern sichtbare Aktionen von Menschen freigeben.
- Persistieren Sie den Graph-Zustand, damit ein unterbrochener Workflow fortgesetzt werden kann, ohne von vorn zu beginnen.
Auf dieser Seite (9)
Die zentrale Designentscheidung: automatisch wiederholen oder gezielt wiederherstellen?
Bei Workflows für den Produktionsbetrieb ist „jeden Fehler wiederholen“ nicht die sicherste Standardeinstellung. Stattdessen gilt:
- Wiederholen Sie nur Fehler, die plausibel vorübergehend sind.
- Beenden Sie die Versuche nach einem kleinen, klar festgelegten Limit.
- Überführen Sie ausgeschöpfte oder mehrdeutige Vorgänge in einen Wiederherstellungszustand.
- Verlangen Sie eine Freigabe, bevor Sie Seiteneffekte auslösen, die kostspielig oder unumkehrbar sein könnten.
LangGraph eignet sich gut, weil sich diese Ergebnisse als Graph-Zustände abbilden lassen, statt sie in einer großen Agentenschleife zu verbergen. Das Modell kann Tool-Aufrufe vorschlagen, doch deterministischer Code entscheidet, ob ein Aufruf sicher ausgeführt, wiederholt, eskaliert oder übersprungen werden kann.
Die folgenden Beispiele veranschaulichen mögliche Muster. Sie stellen keine getestete Anwendung dar, und die genauen APIs können je nach installierter Version von LangGraph und LangChain variieren.
Voraussetzungen
Sie benötigen:
- Python sowie kompatible LangGraph- und LangChain-Pakete.
- Ein Chatmodell, das Tool-Aufrufe über die von Ihnen gewählte Integration unterstützt.
- Tools mit expliziten Eingabeschemas und vorhersehbaren Fehlertypen.
- Einen Checkpointer.
InMemorySavereignet sich für Experimente; die LangGraph-Dokumentation empfiehlt für die Produktion einen persistenten Checkpointer wieAsyncPostgresSaveroderMongoDBSaver. - Eine stabile
thread_idfür jede Workflow-Ausführung.
Geben Sie dem Modell keinen uneingeschränkten Zugriff auf Produktionsanmeldedaten. Verankern Sie Autorisierung, Validierung, Idempotenz und Wiederholungsregeln in den Tools oder der Middleware.
Ein begrenztes, wiederholbares Tool definieren
Die erste Begrenzung sollte direkt um den Vorgang herum liegen. Dieses Beispiel wiederholt nur einen als vorübergehend eingestuften Fehler und gibt ein strukturiertes Ergebnis zurück, wenn das Budget ausgeschöpft ist.
from dataclasses import dataclass
from typing import Literal
class TransientOperationError(Exception):
pass
class PermanentOperationError(Exception):
pass
@dataclass
class OperationResult:
status: Literal["succeeded", "needs_recovery", "failed"]
attempts: int
message: str
def run_with_budget(operation, *, max_attempts: int) -> OperationResult:
for attempt in range(1, max_attempts + 1):
try:
operation()
return OperationResult("succeeded", attempt, "Operation completed")
except PermanentOperationError as exc:
return OperationResult("failed", attempt, str(exc))
except TransientOperationError as exc:
if attempt == max_attempts:
return OperationResult(
"needs_recovery", attempt,
f"Retry budget exhausted: {exc}",
)
return OperationResult("needs_recovery", max_attempts, "No attempt was made")
Fügen Sie bei realen Betriebsabläufen vor Wiederholungen einen Idempotenzschlüssel hinzu. Ein Timeout nach einer Deploy-Anfrage beweist nicht, dass das Deployment nicht stattgefunden hat. Ohne Schlüssel kann eine Wiederholung einen doppelten Auftrag, ein doppeltes Ticket, eine doppelte Zahlung oder eine doppelte Änderungsanfrage auslösen.
Eine hilfreiche Richtlinientabelle sieht so aus:
| Fehlerklasse | Automatische Aktion | Wiederherstellungsaktion |
|---|---|---|
| Vorübergehendes Netzwerk-Timeout | Innerhalb des Budgets wiederholen | Mit Vorgangs-ID eskalieren |
| Ratenlimit | Mit den Vorgaben des Anbieters erneut versuchen | Workflow in eine Warteschlange stellen oder verschieben |
| Ungültige Argumente | Nicht wiederholen | Validierungsfehler an den Agenten zurückgeben |
| Fehlende Berechtigung | Nicht wiederholen | Autorisierung anfordern oder stoppen |
| Unbekanntes Ergebnis nach einem Timeout | Nicht blind erneut ausführen | Status mithilfe des Idempotenzschlüssels prüfen |
Tool-Aufrufe und menschliche Freigaben hinzufügen
LangChains create_agent nutzt im Hintergrund die LangGraph-Ausführung. Die bereitgestellte LangGraph-Dokumentation beschreibt HumanInTheLoopMiddleware, mit der sich ausgewählte Tool-Aufrufe unterbrechen und anhand des persistierten Zustands fortsetzen lassen.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="provider:model-name",
tools=[inspect_job, restart_job, delete_artifact],
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"inspect_job": False,
"restart_job": {
"allowed_decisions": ["approve", "reject"]
},
"delete_artifact": {
"allowed_decisions": ["approve", "edit", "reject"]
},
},
interrupt_mode="per_call",
),
],
checkpointer=InMemorySaver(),
)
Hier läuft die Inspektion ohne Überprüfung, während Neustart und Löschung für eine Entscheidung pausieren. approve führt die ursprünglichen Argumente aus, edit ändert die Argumente vor der Ausführung und reject überspringt den Aufruf und gibt dem Agenten eine Ablehnungsrückmeldung. Die Quelle dokumentiert außerdem respond, das als „ask user“-Tool dient. Es sollte nicht verwendet werden, um ein Tool mit Seiteneffekten abzulehnen, da es als erfolgreiches Tool-Ergebnis behandelt wird.
Ersetzen Sie für die Produktion den In-Memory-Checkpointer durch eine persistente Implementierung und rufen Sie den Agenten mit einer stabilen Thread-ID auf:
config = {
"configurable": {"thread_id": "ops-workflow-1842"}
}
result = agent.invoke(
{
"messages": [
{
"role": "user",
"content": "Inspect the failed job and restart it if safe.",
}
]
},
config=config,
version="v2",
)
Mit Version v2 enthält ein unterbrochenes Ergebnis eine Sammlung interrupts. Legen Sie jede angeforderte Aktion einer autorisierten prüfenden Person vor und setzen Sie anschließend denselben Thread mit dem dokumentierten Entscheidungsformat Command fort.
Wiederholungen und Freigaben in die richtige Reihenfolge bringen
Die Quelldokumentation weist auf eine wichtige Middleware-Regel hin: Wenn Sie eine Überprüfung pro Aufruf verwenden, muss die Human-in-the-Loop-Behandlung vor der Middleware für Tool-Wiederholungen oder Fehlerbehandlung platziert werden. Andernfalls kann es passieren, dass die prüfende Person erneut gefragt wird oder eine ungültige Antwort so behandelt wird, als wäre sie ein Tool-Fehler, der wiederholt werden muss.
Die vorgesehene Reihenfolge lautet:
- Das Modell schlägt einen Tool-Aufruf vor.
- Die Richtlinienprüfung stellt fest, ob eine Überprüfung erforderlich ist.
- Eine prüfende Person gibt den Aufruf frei, bearbeitet ihn oder lehnt ihn ab.
- Das Tool wird mit einem eigenen, begrenzten Wiederholungsbudget ausgeführt.
- Bei Erfolg geht das Ergebnis an den Agenten zurück; bei ausgeschöpftem Budget beginnt die Wiederherstellung.
Führen Sie keine Seiteneffekte in Middleware aus, die beim Fortsetzen einer Unterbrechung erneut ausgeführt wird. Die Dokumentation warnt ausdrücklich davor, dass Middleware vor der Ebene für die menschliche Überprüfung bis zum Pausieren sicher erneut ausgeführt werden können muss.
Einen Wiederherstellungszustand statt einer weiteren Wiederholung hinzufügen
Wenn das Wiederholungsbudget ausgeschöpft ist, speichern Sie ein betriebliches Ereignis mit Workflow-ID, Tool-Name, Anzahl der Versuche, Idempotenzschlüssel und dem zuletzt bekannten Fehler. Wählen Sie anschließend einen von drei Pfaden:
- Überprüfen: Fragen Sie das externe System ab, um festzustellen, ob der ursprüngliche Vorgang erfolgreich war.
- Eskalieren: Pausieren Sie den Ablauf und geben Sie einer zuständigen Person genügend Kontext für die nächste Entscheidung.
- Kompensieren: Führen Sie einen separaten, ausdrücklich freigegebenen Korrekturvorgang aus.
Bitten Sie das Modell nicht, aus einer unvollständigen Fehlermeldung eine Ausgleichsmaßnahme abzuleiten. Geben Sie ihm strukturierte Statusdaten und beschränken Sie die verfügbaren Tools.
Ein Ausführungslimit auf Graph-Ebene bildet eine zweite Sicherheitsgrenze. Konfigurieren Sie das von Ihrer installierten LangGraph-Version unterstützte Limit und behandeln Sie dessen Erreichen als Wiederherstellungsereignis, statt den Ablauf stillschweigend fortzusetzen. So verhindern Sie, dass eine Modell-Tool-Schleife zu einem unbegrenzten Produktionsprozess wird.
Checkliste zur Fehlerbehebung
- Der Workflow beginnt wieder von vorn: Prüfen Sie, ob ein persistenter Checkpointer und eine unveränderte
thread_idverwendet werden. - Eine abgelehnte Aktion wird trotzdem ausgeführt: Prüfen Sie, ob die Fortsetzungsentscheidung eine Ablehnung und nicht
respondist. - Eine prüfende Person erhält zu viele Anfragen: Ergänzen Sie
when-Prädikate auf Basis der Argumente, damit nur riskante Aufrufe eine Unterbrechung auslösen. - Durch eine Wiederholung wird Arbeit doppelt ausgeführt: Ergänzen Sie Idempotenz und ein Tool zur Statusprüfung, bevor Sie unbekannte Ergebnisse erneut versuchen.
- Dieselbe Überprüfung erscheint wiederholt: Prüfen Sie die Reihenfolge der Middleware und stellen Sie sicher, dass die Wiederholungsbehandlung die Freigabegrenze nicht falsch umschließt.
- Ein bearbeiteter Aufruf verhält sich unerwartet: Validieren Sie bearbeitete Argumente selbst. Das dokumentierte Antwortschema beschreibt zwar die Form, gewährleistet aber nicht unbedingt die Sicherheit im jeweiligen Geschäftskontext.
Fazit
Ein zuverlässiger LangGraph-Agent für den Betrieb ist ein begrenzter Workflow und kein uneingeschränkter Chatbot. Legen Sie für jedes Tool ein Wiederholungsbudget fest, klassifizieren Sie Fehler, persistieren Sie den Zustand, lassen Sie riskante Aufrufe freigeben und bilden Sie die Wiederherstellung als expliziten Zweig ab. So wird die menschliche Freigabe zu einem kontrollierten Checkpoint im Workflow statt zu einer Notlösung.
Quellen
FAQ
Wiederholt LangGraph automatisch jeden fehlgeschlagenen Tool-Aufruf?
Gehen Sie nicht davon aus. Definieren Sie das Wiederholungsverhalten explizit, klassifizieren Sie Fehler und setzen Sie eine maximale Anzahl von Versuchen fest. In Ihrem installierten Stack ist möglicherweise Middleware für Tool-Wiederholungen verfügbar; prüfen Sie deren Konfiguration und Verhalten jedoch anhand der Dokumentation für die jeweilige Version.
Warum ist Checkpointing für menschliche Freigaben erforderlich?
Eine Unterbrechung pausiert die Ausführung, solange eine Entscheidung aussteht. Ein Checkpointer bewahrt den Graph-Zustand, sodass derselbe Workflow-Thread nach Freigabe, Bearbeitung, Ablehnung oder einer direkten Antwort fortgesetzt werden kann.
Wann sollte ein Tool-Aufruf eine menschliche Überprüfung erfordern?
Lassen Sie Aufrufe überprüfen, die den Produktionszustand ändern, Daten löschen, externe Mitteilungen versenden oder unklare Kosten oder Auswirkungen haben. Nur lesende Inspektionen können oft automatisch erfolgen, wenn Autorisierung und Ausgabegrenzen eindeutig festgelegt sind.
Was sollte geschehen, wenn das Wiederholungsbudget ausgeschöpft ist?
Wechseln Sie zu einem Wiederherstellungspfad: Überprüfen Sie den externen Vorgang, eskalieren Sie an eine zuständige Person oder führen Sie eine separat freigegebene Ausgleichsmaßnahme aus. Wiederholen Sie einen Vorgang nicht blind, wenn sein Ergebnis unbekannt ist.
Ähnliche Artikel
Guides
Agentic RAG mit LangGraph: Tool Calling, Quellenangaben und begrenzte Ausführung
Erstellen Sie einen LangGraph-Agenten zur Beantwortung von Dokumentfragen, der bei Bedarf recherchiert, den Kontext bewertet, erfolglose Suchen erneut versucht und Antworten mit Quellenangaben liefert – ohne unbegrenzte Ausführung.
Guides
Einen begrenzten LangGraph-Agenten für Tool-Aufrufe mit menschlicher Prüfung erstellen
Ein praxisnahes Muster zur Bewertung eines LangGraph-Agenten für Tool-Aufrufe mit expliziten Schrittlimits, menschlicher Freigabe für riskante Aktionen und wiederholbaren Testfällen.
Guides
Gemini 4 Hydrogen vs. Carbon für den Betrieb produktiver Workflows
Was die verfügbaren Belege über Gemini 4 Hydrogen und Carbon bei Programmieraufgaben, Tool Calling, strukturierten Ausgaben und wiederherstellbaren Produktions-Workflows aussagen.
Guides
Einen wiederanlaufbaren Datenextraktions-Workflow in n8n erstellen
Entwickeln Sie einen n8n-Extraktions-Workflow, der Datensätze validiert, vorübergehende Fehler erneut versucht und Ausnahmefälle zur menschlichen Prüfung weiterleitet, ohne doppelte Schreibvorgänge zu erzeugen.