GuidesOneMux

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.

AI

Zusammenfassung · TL;DR

Begrenzen Sie die Ausführung mit einem Graph-Schrittl bietet, pausieren Sie riskante Tool-Aufrufe mit HumanInTheLoopMiddleware und prüfen Sie Freigabe-, Ablehnungs- und Limitverhalten mit einem kleinen, festen Testsatz. Betrachten Sie die Beispiele als Ausgangspunkt: Das Verhalten von Modell und Tools muss in Ihrer eigenen Umgebung getestet werden.

Kernaussagen

  • Ein Graph-Rekursionslimit setzt eine klare Ausführungsgrenze für einen Agenten; es garantiert nicht, dass der Agent seine Aufgabe abschließt.
  • Eine menschliche Prüfung kann die Tool-Ausführung pausieren und später fortsetzen, wenn der Graph über einen Checkpointer und eine Thread-ID verfügt.
  • Halten Sie Bewertungen wiederholbar, indem Sie Testeingaben, erwartete Ergebnisse, Tool-Fixtures und das Ausführungslimit festlegen.
  • Testen Sie abgelehnte Aktionen und das Erreichen des Limits ausdrücklich; beides ist nicht dasselbe wie eine erfolgreiche Wiederherstellung.
Auf dieser Seite (6)

Ein Agent für Tool-Aufrufe braucht mehr als einen guten Prompt: Er benötigt eine Abbruchgrenze, einen Plan für riskante Aktionen und Tests, die sein Verhalten reproduzierbar machen. In LangGraph können Sie ein Graph-Rekursionslimit mit einer Human-in-the-loop-Prüfung (HITL) für ausgewählte Tools kombinieren. Anschließend bewerten Sie den Workflow anhand fester Fälle, statt sich auf einige wenige erfolgreiche Durchläufe zu verlassen.

Das folgende Beispiel dient zur Veranschaulichung und ist keine getestete Konfiguration. Es setzt eine Python-Umgebung mit kompatiblen LangChain- und LangGraph-Paketen, ein Chatmodell mit Unterstützung für Tool-Aufrufe und ein von Ihnen implementiertes Tool voraus. Prüfen Sie die Versionen und die Parameter des Modellanbieters in Ihrer eigenen Umgebung.

Die Grenze festlegen, bevor Sie Tools hinzufügen

Ein Rekursionslimit begrenzt die Ausführungsschritte des Graphen. Es ist eine Sicherheitsgrenze, keine Zusage, dass der Agent fertig wird, und auch kein präzises Limit für die Anzahl der Tool-Aufrufe: Die Graphstruktur beeinflusst, wie Schritte gezählt werden. Wenn die Ausführung das Limit erreicht, sollten Sie mit einem Graph-Rekursionsfehler rechnen und den Lauf als unvollständig behandeln. Betrachten Sie ihn nicht als erfolgreiche Antwort.

Beginnen Sie während der Bewertung mit einem kleinen Limit und erhöhen Sie es erst, wenn ein Testfall zeigt, dass der Workflow mehr Schritte benötigt. Halten Sie auch die Abläufe der Tools eng begrenzt. Ein Limit auf Graph-Ebene kann keinen Seiteneffekt rückgängig machen, den ein Tool bereits ausgeführt hat.

Einen Tool-Aufruf konfigurieren, der für eine Prüfung pausieren kann

Dieses Beispiel verwendet create_agent mit HITL-Middleware. Das Tool write_file wird zur Freigabe oder Ablehnung unterbrochen, read_data dagegen nicht. Die Implementierungen der Tools und der Modellname sind Platzhalter. Vergewissern Sie sich, dass Ihr gewähltes Modell und Ihr Endpunkt die von Ihrem Agenten verwendeten Parameter und das Verhalten bei Tool-Aufrufen unterstützen.

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver

# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]

agent = create_agent(
    model="your-tool-capable-chat-model",
    tools=tools,
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "write_file": {"allowed_decisions": ["approve", "reject"]},
                "read_data": False,
            }
        )
    ],
    checkpointer=InMemorySaver(),
)

config = {
    "configurable": {"thread_id": "evaluation-case-001"},
    "recursion_limit": 8,
}

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Save the approved summary."}]},
    config=config,
    version="v2",
)

InMemorySaver eignet sich für einen Prototyp oder einen Test, der in einem Prozess ausgeführt wird; bei Neustarts von Prozessen ist es nicht dauerhaft. Für einen bereitgestellten Workflow sollten Sie einen persistenten Checkpointer verwenden. Der LangChain-Leitfaden zu HITL erklärt, dass ein Checkpointer und eine Thread-ID erforderlich sind, um eine Ausführung zu pausieren und fortzusetzen. Quelle: Human-in-the-loop.

Wenn der Lauf einen Interrupt zurückgibt, zeigen Sie einem Prüfer die angeforderte Aktion und ihre Argumente. Setzen Sie denselben Thread mit einer Entscheidung fort. Die Reihenfolge der Entscheidungen muss der Reihenfolge der Aktionen im Interrupt entsprechen. Lehnen Sie eine Aktion ab, die Sie verweigern möchten; respond dient dazu, eine menschliche Antwort als Tool-Ergebnis zurückzugeben, nicht dazu, einen Seiteneffekt zu verweigern.

from langgraph.types import Command

# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
    Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
    config=config,
    version="v2",
)

Die Bewertung wiederholbar machen

Halten Sie einen kompakten Testsatz in der Versionsverwaltung. Jeder Fall sollte die Anfrage des Benutzers, das erwartete Tool-Verhalten, die Frage, ob eine Prüfung erforderlich ist, und den erwarteten Endstatus festlegen. Verwenden Sie für Tests harmlose Fixtures oder Mock-Tools; lassen Sie Testfälle weder in echte Dateien schreiben noch Produktionsdaten ändern.

FallEinrichtungErwartetes Ergebnis
Sicheres LesenInformationen über read_data anfordernKein HITL-Interrupt; Tool-Ergebnis wird zurückgegeben
Geprüftes SchreibenEin erlaubtes Schreiben anfordernInterrupt erscheint, bevor der Schreibvorgang ausgeführt wird; die Freigabe erlaubt die Ausführung
Abgelehntes SchreibenEin Schreiben anfordern und anschließend ablehnenDas Schreib-Tool wird nicht ausgeführt; Ablehnungsfeedback wird an den Agenten zurückgegeben
Grenze des SchrittlimitsEine Fixture verwenden, die verhindert, dass der Workflow abgeschlossen wirdDer Lauf stoppt an der konfigurierten Grenze und wird als unvollständig erfasst

Erfassen Sie für jeden Lauf die Fall-ID, das konfigurierte Limit, Tool-Aufrufe, Interrupt-Entscheidungen, den Abschlussstatus und etwaige Fehler. Vergleichen Sie diese Felder mit den Erwartungen. Beurteilen Sie nicht nur die abschließende natürlichsprachliche Antwort: Ein Agent kann eine plausible Antwort erzeugen, nachdem er die falsche Aktion ausgeführt hat.

Fehlerbehandlung: pausieren, ablehnen oder stoppen

HITL ist eine kontrollierte Pause und kein allgemeiner Wiederholungsmechanismus. Ein Prüfer kann je nach konfigurierter Richtlinie freigeben, bearbeiten, ablehnen oder antworten. Eine Ablehnung überspringt den angeforderten Tool-Aufruf und gibt Ablehnungsfeedback an den Agenten zurück. Ob der Agent anschließend fertig wird, eine weitere Aktion anfordert oder fehlschlägt, hängt von seinem weiteren Verhalten ab; testen Sie daher auch diesen Pfad.

Wenn der Graph sein Rekursionslimit erreicht, erfassen Sie den Lauf als Limitfehler und prüfen Sie seinen Zustand sowie den Tool-Verlauf. Wiederholen Sie einen Lauf nicht automatisch, wenn er möglicherweise bereits Seiteneffekte ausgeführt hat. Machen Sie Tools, soweit praktikabel, idempotent oder verlangen Sie vor der Wiederholung einer Operation eine separate Prüfung. Die bereitgestellte Dokumentation beschreibt das Pausieren und Fortsetzen mit Checkpointing; sie belegt keine automatische Wiederherstellung nach beliebigen Tool- oder Modellfehlern.

Checkliste zur Fehlerbehebung

  • Es erscheint kein Interrupt: Prüfen Sie, ob der Tool-Name mit der Zuordnung interrupt_on übereinstimmt und die Richtlinie des Tools eine Prüfung aktiviert.
  • Beim Fortsetzen wird der pausierte Lauf nicht gefunden: Stellen Sie sicher, dass derselbe Checkpointer und dieselbe Thread-ID verwendet werden.
  • Der Lauf stoppt zu früh: Prüfen Sie das konfigurierte Rekursionslimit und den Graph-Pfad; erhöhen Sie das Limit nur, wenn ein Testfall dies rechtfertigt.
  • Eine abgelehnte Aktion scheint ausgeführt worden zu sein: Vergewissern Sie sich, dass das Tool vor der Prüfung nicht aufgerufen wurde und der Prüfer reject statt respond verwendet hat.
  • Tests unterscheiden sich zwischen den Läufen: Fixieren Sie Tool-Fixtures und Testeingaben und kontrollieren oder stubben Sie Modellantworten, sofern Ihre Einrichtung dies erlaubt. Eine feste Eingabe allein macht die Modellausgabe nicht deterministisch.

Die praktische Regel

Verwenden Sie das Rekursionslimit, um die Graph-Arbeit zu begrenzen, HITL, um folgenreiche Tool-Aufrufe zu kontrollieren, und einen kleinen, expliziten Testsatz, um sowohl den Erfolgs- als auch die Fehlerpfade zu prüfen. Behandeln Sie unterbrochene, abgelehnte und wegen des Limits beendete Läufe als unterschiedliche Ergebnisse. Diese Unterscheidung macht einen Agenten leichter bewertbar und sicherer veränderbar.

FAQ

Begrenzt das Rekursionslimit von LangGraph die Anzahl der Tool-Aufrufe?

Nicht genau. Es begrenzt die Ausführungsschritte des Graphen, und wie viele Tool-Aufrufe darin Platz finden, hängt von der Graphstruktur ab. Behandeln Sie das Erreichen des Limits als unvollständigen Lauf und testen Sie die Grenze.

Was ist erforderlich, um einen von Menschen geprüften Tool-Aufruf fortzusetzen?

Konfigurieren Sie einen Checkpointer, geben Sie eine Thread-ID an und setzen Sie die Ausführung mit demselben Thread und Persistenzkontext fort. Der Prüfer liefert für jede unterbrochene Aktion eine Entscheidung.

Wiederholt HITL einen fehlgeschlagenen Tool-Aufruf automatisch?

Nein. Der dokumentierte HITL-Workflow pausiert für eine menschliche Entscheidung und führt die geprüfte Aktion anschließend aus oder überspringt sie. Er etabliert keine automatischen Wiederholungen für beliebige Tool- oder Modellfehler.

Wie sollte ich einen abgelehnten Tool-Aufruf testen?

Verwenden Sie ein harmloses oder gemocktes Tool, lösen Sie den Interrupt aus, lehnen Sie die Aktion ab und prüfen Sie, dass das Tool nicht ausgeführt wurde und der Lauf Ablehnungsfeedback erfasst.

Ähnliche Artikel