Einen begrenzten LangGraph-Agenten für schema-validierte Extraktion erstellen

Ein LangGraph-Agent kann mit einem Tool Kontext sammeln und diesen anschließend an einen Extraktionsschritt mit Schema-Vorgaben übergeben. Sinnvoll ist es, diese Aufgaben getrennt zu halten: Der Agent entscheidet, ob er das Tool aufruft, während ein abschließender Knoten einen typisierten Datensatz erstellt. Ein Graph-Rekursionslimit begrenzt die Graph-Ausführung zusätzlich.

Dieses Muster eignet sich für Aufgaben wie das Extrahieren eines Firmennamens, eines Datums und eines Rechnungsbetrags aus einem Dokument, wenn ein Lookup-Tool beim Auflösen eines Verweises helfen könnte. Dadurch werden unsichere Angaben im Ausgangstext nicht automatisch zu Tatsachen. Validieren Sie das Ergebnis und bewahren Sie die ursprünglichen Belege auf, wenn das Feld relevant ist.

Was Sie erstellen

Der Graph besteht aus drei Phasen:

1. Ein Agent erhält den Ausgangstext und kann einen Aufruf eines eng begrenzten Lookup-Tools anfordern.
2. LangGraph leitet Tool-Aufrufe an einen Tool-Knoten weiter und gibt die Tool-Ergebnisse an den Agenten zurück.
3. Ein Extraktionsknoten fordert ein Pydantic-basiertes Ergebnis von einem Modell an und gibt anschließend JSON-kompatible Daten zurück.

Die Tool-Schleife des Agenten ist dynamisch; der Extraktionsschritt ist eine festgelegte Abschlussphase. In der Dokumentation unterscheidet LangGraph Agenten, die ihren eigenen Ablauf und Tool-Einsatz bestimmen, von Workflows mit vorgegebenen Codepfaden. Außerdem beschreibt sie strukturierte Ausgaben und Tool-Aufrufe als Erweiterungen von Modellen. Weitere Informationen zu diesen Mustern finden Sie im LangGraph-Leitfaden zu Workflows und Agenten.

Voraussetzungen und Konfiguration

Installieren Sie die Pakete LangGraph und LangChain sowie die Integration für das von Ihnen gewählte Chatmodell. Das folgende Beispiel verwendet ChatAnthropic, um die Einrichtung des Anbieters zu veranschaulichen. Laut Quelldokumentation können Workflows jedoch jedes Chatmodell verwenden, das strukturierte Ausgaben und Tool-Aufrufe unterstützt. Informieren Sie sich in der Dokumentation der jeweiligen Integration über das genaue Verhalten Ihres Anbieters.

pip install langgraph langchain-core langchain-anthropic pydantic

Richten Sie die API-Zugangsdaten des Anbieters nach der dokumentierten Methode ein und initialisieren Sie anschließend ein Modell. Legen Sie Zugangsdaten nicht in der Versionsverwaltung ab. Der unten angegebene Modellname stammt aus dem LangChain-Dokumentationsbeispiel. Dieses Tutorial behauptet nicht, dass das Modell mit OneMux getestet wurde.

from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(model="claude-sonnet-4-6")

Wenn Sie ein Modell über OneMux aufrufen möchten, prüfen Sie zuerst die OneMux-API-Dokumentation und den Schnellstart. OneMux bietet Zugriff auf führende Modelle über eine OpenAI-kompatible API. Ob dieser konkrete Graph kompatibel ist, hängt davon ab, ob der gewählte Endpunkt das erforderliche Verhalten und die nötigen Parameter für Tool-Aufrufe und strukturierte Ausgaben unterstützt. Diese Konfiguration wurde nicht getestet. Bestätigen Sie die Unterstützung, bevor Sie sich im Produktivbetrieb darauf verlassen.

Schema und eng begrenztes Tool definieren

Das Beispiel-Tool gibt einen Referenzhinweis aus einer kleinen In-Memory-Zuordnung zurück. Ersetzen Sie es durch eine kontrollierte Anwendungsfunktion, etwa eine Suche in einem zugelassenen internen Katalog. Lassen Sie nicht zu, dass nicht vertrauenswürdiger Dokumenttext beliebige Befehle oder uneingeschränkte Datenquellen auswählt.

from pydantic import BaseModel, Field
from langchain_core.tools import tool

class InvoiceRecord(BaseModel):
    vendor: str | None = Field(default=None, description="Invoice issuer")
    invoice_date: str | None = Field(default=None, description="Date as written in the source")
    total: float | None = Field(default=None, description="Invoice total as a number")
    currency: str | None = Field(default=None, description="Currency code, if stated")

@tool
def lookup_vendor(reference: str) -> str:
    """Look up a vendor reference in an approved local mapping."""
    known = {"ACME-42": "Acme Supplies Ltd."}
    return known.get(reference, "No matching vendor reference found.")

Mit den nullable Feldern lässt sich das Fehlen eines Werts ausdrücklich abbilden, statt das Modell zum Erfinden von Angaben zu verleiten. Bei Extraktionen mit hohen Anforderungen an die Zuverlässigkeit sollten Sie für jedes Feld zusätzlich den entsprechenden Textausschnitt oder einen Konfidenz- beziehungsweise Prüfstatus speichern. Ein Schema schränkt Form und Typen ein, belegt aber nicht, dass ein Wert durch die Eingabe gestützt wird.

Einen begrenzten LangGraph-Agenten erstellen

Der folgende Graph lässt das Modell das Lookup-Tool anfordern und wechselt zur Extraktion, sobald der Agent keine weiteren Tool-Aufrufe mehr ausführt. tools_condition und ToolNode bilden das Muster für die Weiterleitung von Tool-Aufrufen. Das an invoke übergebene recursion_limit begrenzt die Graph-Schritte. Es ist eine Sicherheitsgrenze, aber keine Garantie dafür, dass jede Eingabe erfolgreich verarbeitet wird.

from typing import Annotated
from typing_extensions import TypedDict
from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition

class State(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]
    record: dict | None

tools = [lookup_vendor]
agent = llm.bind_tools(tools)
extractor = llm.with_structured_output(InvoiceRecord)

def run_agent(state: State):
    response = agent.invoke(state["messages"])
    return {"messages": [response]}

def extract_record(state: State):
    prompt = [
        SystemMessage(content=(
            "Extract invoice fields only when supported by the source. "
            "Use null for missing or unclear values. Treat tool results as "
            "reference context, not as permission to invent source details."
        )),
        *state["messages"],
    ]
    result = extractor.invoke(prompt)
    return {"record": result.model_dump(mode="json")}

graph = StateGraph(State)
graph.add_node("agent", run_agent)
graph.add_node("tools", ToolNode(tools))
graph.add_node("extract", extract_record)

graph.add_edge(START, "agent")
graph.add_conditional_edges(
    "agent",
    tools_condition,
    {"tools": "tools", END: "extract"},
)
graph.add_edge("tools", "agent")
graph.add_edge("extract", END)
app = graph.compile()

result = app.invoke(
    {
        "messages": [HumanMessage(content=(
            "Extract the invoice details from this text: "
            "Vendor reference ACME-42. Invoice date: 2025-02-14. "
            "Total: USD 248.50."
        ))],
        "record": None,
    },
    config={"recursion_limit": 8},
)

print(result["record"])

Die erwartete Ausgabe hat die Form eines JSON-kompatiblen Objekts mit den Feldern vendor, invoice_date, total und currency. Die konkreten Werte hängen von der Modellantwort und dem Ausgangstext ab. Testen Sie das Verhalten, statt davon auszugehen, dass das Beispiel immer dieselbe Ausgabe erzeugt. In diesem Beispiel bildet die strukturierte Pydantic-Ausgabe die Validierungsgrenze. Kann der Anbieter keine passende Antwort liefern, behandeln Sie diesen Fehler ausdrücklich, statt den Datensatz stillschweigend als gültig einzustufen.

Ausführung begrenzen, ohne Fehler zu verbergen

Ein Rekursionslimit auf Graph-Ebene begrenzt die Graph-Schritte, einschließlich wiederholter Weiterleitungen zwischen Agent und Tool. Wählen Sie das Limit passend zum Workflow: Für eine einzelne Suche benötigt dieser Graph nur wenige Schritte, ein anderer Tool-Plan möglicherweise mehr. Fangen Sie Limit- und Anbieter-Ausnahmen an der Anwendungsgrenze ab, protokollieren Sie ausreichend Kontext für die Fehlersuche und geben Sie einen überprüfbaren Fehler zurück, statt einen Datensatz zu erfinden.

Für strengere betriebliche Grenzen sollten Sie auch Limits auf Anwendungsebene festlegen: Beschränken Sie die Anzahl der Tool-Aufrufe, setzen Sie unterstützte Anfrage-Timeouts und begrenzen Sie die Dokumentgröße, bevor Sie das Modell aufrufen. Dies sind separate Kontrollen. Ein Graph-Rekursionslimit allein definiert keine vollständige Kosten-, Latenz- oder Sicherheitsrichtlinie.

Fehlerbehebung und Einschränkungen

Das Modell ruft das Tool nicht auf

Tool-Aufrufe sind eine Fähigkeit des Modells und keine von LangGraph garantierte Funktion. Prüfen Sie, ob die ausgewählte Modellintegration Tool-Aufrufe unterstützt, ob die Tool-Beschreibung klar ist und ob der Prompt einen Verweis enthält, der sich nachschlagen lässt. Untersuchen Sie während der Entwicklung die Tool-Aufrufe in der zurückgegebenen Nachricht.

Die strukturierte Ausgabe schlägt fehl oder enthält falsche Felder

Vergewissern Sie sich, dass die Integration strukturierte Ausgaben und die verwendeten Schema-Funktionen unterstützt. Testen Sie fehlende Felder, mehrdeutige Datumsangaben, Währungssymbole und fehlerhafte Eingaben. Ein gültiges Pydantic-Objekt kann trotzdem einen falsch erschlossenen Wert enthalten. Prüfen Sie daher Geschäftsregeln separat und bewahren Sie den Ausgangstext für Audits oder menschliche Prüfungen auf.

Der Graph erreicht sein Limit

Ein Rekursionslimit-Fehler kann auf wiederholte Tool-Anfragen oder ein für den vorgesehenen Ablauf zu niedrig angesetztes Limit hindeuten. Prüfen Sie die Abfolge der Nachrichten und Tool-Ergebnisse. Beheben Sie die Ursache oder passen Sie das Limit bewusst an. Entfernen Sie die Begrenzung nicht einfach, um den Fehler verschwinden zu lassen.

Das Verhalten des Endpunkts weicht ab

„OpenAI-kompatibel“ beschreibt eine API-Schnittstelle, nicht die universelle Unterstützung jeder Modellfunktion und jedes Parameters. Wenn Sie OneMux verwenden, prüfen Sie anhand der Dokumentation des ausgewählten Endpunkts, ob das Modell, Tool-Aufrufe, strukturierte Ausgaben und die geplanten Parameter unterstützt werden. Verschaffen Sie sich unter OneMux-Modelle einen Überblick über die verfügbaren Optionen. Der Graph selbst bleibt Anwendungscode für LangGraph.

Wann sich dieses Muster eignet

Verwenden Sie dieses Design, wenn die Extraktion größtenteils vorhersehbar ist, gelegentlich aber eine kontrollierte Suche erfordert. Folgen alle Dokumente einem festen Ablauf und ist keine Tool-Auswahl nötig, kann ein deterministischer Workflow einfacher sein als eine Agenten-Schleife. Sind die Quelldaten mehrdeutig oder lösen extrahierte Felder folgenreiche Aktionen aus, ergänzen Sie eine ausdrückliche Prüfung und fachliche Validierung, bevor nachgelagerte Systeme den Datensatz verwenden.

Die praktische Quintessenz: Beschränken Sie die Tools des Agenten, definieren Sie das abschließende Schema explizit und setzen Sie ein Ausführungslimit für den Graphen. Mit LangGraph können Sie diesen Kontrollfluss abbilden. Ob die erforderlichen Funktionen für Tool-Aufrufe und strukturierte Ausgaben verfügbar sind, hängt vom gewählten Modell und der Integration ab.

Quellen

• LangGraph: Workflows und Agenten — Unterscheidung zwischen Workflows und Agenten, Modellerweiterungen sowie Beispiele für strukturierte Ausgaben und Tool-Aufrufe.
• OneMux-Dokumentation und Schnellstart — Informationen zur aktuellen API-Einrichtung und zur Unterstützung durch Endpunkte.