LangGraph Multi-Model Routing: Gateway-Checks für Agent-Workflows

LangGraph Multi-Model Routing ist in erster Linie ein Problem des Graph-Designs und in zweiter Linie ein Gateway-Problem. Der Graph entscheidet, welche Art von Arbeit stattfindet, der Modell-Client entscheidet, welche OpenAI-kompatible Route aufgerufen wird, und das Gateway sollte nachweisen, ob jeder Aufruf innerhalb der Regeln für Budget, Tools, Wiederholungsversuche, Protokollierung und Stopp-Bedingungen geblieben ist.

Flatkey passt an diese Gateway-Grenze. Die öffentliche Website zeigt eine OpenAI-kompatible Chat-Route unter https://router.flatkey.ai/v1/chat/completions, mit einem Schlüssel, Einblick in die Nutzung, Abrechnungskontrollen und Modell-Routing an einem Ort. Dieser Leitfaden zeigt ein praktisches LangGraph Multi-Model Routing-Setup für Agent-Workflows, ohne davon auszugehen, dass jeder Modell-Alias, jedes Tool-Verhalten oder jede Fallback-Route bereits in Ihrem Konto validiert wurde.

Schnelle Antwort für LangGraph Multi-Model Routing

Ein sicheres LangGraph Multi-Model Routing-Setup trennt das Routing in drei Schichten.

Verstecken Sie LangGraph Multi-Model Routing nicht in einem langen Prompt. Legen Sie die Richtlinie in Graph-Knoten, bedingten Kanten und Gateway-Prüfungen ab, die Ihr Team inspizieren kann.

Warum Modell-Routing an die Grenzen des Graphen gehört

Die meisten LangGraph-Beispiele konzentrieren sich auf den Kontrollfluss des Graphen: Zustand, Knoten, Kanten, Tools und Persistenz. Das ist der richtige Ausgangspunkt, aber Produktions-Agenten benötigen auch Routengrenzen, über die Plattform- und Finanzteams nachdenken können.

Verwenden Sie Routen auf Graphenebene, wenn der Workflow deutlich unterschiedliche Kosten-, Latenz- oder Tool-Risikoprofile aufweist:

An dieser Grenze kann Flatkey helfen. Anstatt separate Anbieter-Schlüssel über jeden Knoten zu verteilen, kann jede Route eine OpenAI-kompatible API-Basis-URL aufrufen, während Flatkey die Sichtbarkeit auf Gateway-Ebene beibehält. Für angrenzendes Richtliniendesign siehe den Flatkey-Leitfaden zu KI-Agent-Gateway-Kontrollen.

Quellprüfungen, bevor Sie die Route verdrahten

Verwenden Sie aktuelle Dokumentationen und Live-Kontoüberprüfungen, bevor Sie Vorlagen als Produktionscode behandeln.

Der folgende Code ist eine Vorlage. Führen Sie ihn mit Ihren aktuellen langchain-, langchain-openai- und langgraph-Versionen aus, bevor Sie eine LangGraph Multi-Model Routing-Richtlinie ausliefern.

Konfigurieren Sie Flatkey-gestützte Chat-Modelle

Installieren Sie aktuelle Pakete in der Umgebung, die Ihren Graphen ausführt.

pip install -U langgraph langchain langchain-openai

Halten Sie den API-Stamm vom Endpunktpfad getrennt. LangChain-Clients sollten die Basis-URL erhalten; der Client fügt den Chat Completions-Pfad für OpenAI-kompatible Chat-Aufrufe hinzu.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_FAST_MODEL=your-fast-model-alias
FLATKEY_REASONING_MODEL=your-reasoning-model-alias
FLATKEY_TOOL_MODEL=your-tool-capable-model-alias

Erstellen Sie dann explizite Modell-Clients für jede Route.

import os
from langchain.chat_models import init_chat_model

BASE_URL = os.getenv("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1")
API_KEY = os.environ["FLATKEY_API_KEY"]

fast_model = init_chat_model(
    model=os.environ["FLATKEY_FAST_MODEL"],
    model_provider="openai",
    base_url=BASE_URL,
    api_key=API_KEY,
)

reasoning_model = init_chat_model(
    model=os.environ["FLATKEY_REASONING_MODEL"],
    model_provider="openai",
    base_url=BASE_URL,
    api_key=API_KEY,
)

tool_model = init_chat_model(
    model=os.environ["FLATKEY_TOOL_MODEL"],
    model_provider="openai",
    base_url=BASE_URL,
    api_key=API_KEY,
)

Dies ist die kleinste nützliche Form für das LangGraph Multi-Model Routing: Jede Route hat einen benannten Modell-Client, aber alle Aufrufe verwenden dieselbe Gateway-Grenze. Gehen Sie nicht davon aus, dass ein Modell-Alias Streaming oder Tools unterstützt, nur weil ein anderer Alias dies tut. Testen Sie jede Route separat.

Erstellen einer LangGraph-Routing-Vorlage

Verwenden Sie einen Klassifikator-Knoten, um die Route in den Zustand zu schreiben. Lassen Sie dann bedingte Kanten entscheiden, welcher Knoten als Nächstes ausgeführt wird.

from typing import Annotated, Literal, TypedDict

from langchain_core.messages import AIMessage, BaseMessage
from langchain_core.tools import tool
from langgraph.graph import END, StateGraph
from langgraph.graph.message import add_messages


class RouteState(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]
    route: Literal["simple", "complex", "tools", "stop"]
    budget_cents: float
    errors: int
    tool_calls: int


@tool
def lookup_account_status(account_id: str) -> str:
    """Template-Tool. Ersetzen Sie dies durch Ihre echte schreibgeschützte Suche."""
    return "active"


tool_ready_model = tool_model.bind_tools([lookup_account_status])


def choose_route(state: RouteState) -> dict:
    last_message = state["messages"][-1].content.lower()

    if state.get("budget_cents", 0) <= 0:
        return {"route": "stop"}
    if state.get("errors", 0) >= 2:
        return {"route": "stop"}
    if "lookup" in last_message or "account" in last_message:
        return {"route": "tools"}
    if len(last_message) > 600:
        return {"route": "complex"}
    return {"route": "simple"}


def simple_answer(state: RouteState) -> dict:
    return {"messages": [fast_model.invoke(state["messages"])]}


def complex_answer(state: RouteState) -> dict:
    return {"messages": [reasoning_model.invoke(state["messages"])]}


def tool_answer(state: RouteState) -> dict:
    if state.get("tool_calls", 0) >= 3:
        return {"messages": [AIMessage(content="Tool-Aufruflimit erreicht.")] }
    return {"messages": [tool_ready_model.invoke(state["messages"])]}


workflow = StateGraph(RouteState)
workflow.add_node("choose_route", choose_route)
workflow.add_node("simple_answer", simple_answer)
workflow.add_node("complex_answer", complex_answer)
workflow.add_node("tool_answer", tool_answer)

workflow.set_entry_point("choose_route")
workflow.add_conditional_edges(
    "choose_route",
    lambda state: state["route"],
    {
        "simple": "simple_answer",
        "complex": "complex_answer",
        "tools": "tool_answer",
        "stop": END,
    },
)
workflow.add_edge("simple_answer", END)
workflow.add_edge("complex_answer", END)
workflow.add_edge("tool_answer", END)

graph = workflow.compile()

Diese Vorlage hält das LangGraph Multi-Model Routing sichtbar. Ein Prüfer kann sehen, warum eine Anfrage an simple_answer, complex_answer, tool_answer oder stop ging, ohne einen Prompt zurückentwickeln zu müssen.

Der obige tool_answer-Knoten überprüft die Modellroute, die Tool-Aufrufe vorschlagen kann. Wenn Ihr Graph Tools ausführen soll, fügen Sie nach diesem Modellknoten einen LangGraph ToolNode oder Ihren eigenen Executor hinzu und leiten Sie dann das Tool-Ergebnis mit denselben Budget- und Stopp-Bedingungsprüfungen zurück in den Graphen.

Hinzufügen von Gateway-Checks um jeden Modellaufruf

Die Graph-Route sollte nicht die einzige Leitplanke sein. Fügen Sie einen kleinen Wrapper hinzu, der Budgets vor einem Modellaufruf prüft und Nachweise nach einem Modellaufruf aufzeichnet.

from dataclasses import dataclass
from time import time


@dataclass
class GatewayDecision:
    route: str
    model_alias: str
    allowed: bool
    reason: str
    started_at: float


def preflight(route: str, model_alias: str, state: RouteState) -> GatewayDecision:
    if state.get("budget_cents", 0) <= 0:
        return GatewayDecision(route, model_alias, False, "budget_exhausted", time())
    if route == "tools" and state.get("tool_calls", 0) >= 3:
        return GatewayDecision(route, model_alias, False, "tool_limit_reached", time())
    if state.get("errors", 0) >= 2:
        return GatewayDecision(route, model_alias, False, "retry_limit_reached", time())
    return GatewayDecision(route, model_alias, True, "allowed", time())


def record_gateway_result(decision: GatewayDecision, response: BaseMessage) -> None:
    # Ersetzen Sie dies durch strukturiertes Logging. Fügen Sie eine geschwärzte Schlüsselbezeichnung,
    # Routennamen, Modell-Alias, Anfrage-Zeitstempel und Antwort-Metadaten hinzu.
    print(
        {
            "route": decision.route,
            "model_alias": decision.model_alias,
            "allowed": decision.allowed,
            "reason": decision.reason,
            "started_at": decision.started_at,
            "response_type": response.type,
        }
    )

Hören Sie in der Produktion nicht bei lokalen Protokollen auf. Gleichen Sie den Zeitstempel und den Modell-Alias mit den Flatkey-Nutzungs- oder Anforderungsprotokollen ab. Das ist der Beweis, dass das LangGraph Multi-Model Routing die von Ihnen beabsichtigte Gateway-Route verwendet hat.

Überprüfen Sie Tools, bevor Sie einer tool-lastigen Route vertrauen

Tool-lastige Knoten verdienen ihr eigenes Verifizierungspaket. Ein Modell mag gut im einfachen Chat sein, aber an Ihrem Tool-Schema scheitern, Tool-Deltas anders streamen oder Tool-Argumente erzeugen, die Ihr Executor ablehnt. Für tiefere Kompatibilitätsprüfungen verwenden Sie den Flatkey-Leitfaden zur Tool-Aufruf-Kompatibilität über Anbieter hinweg.

Hier entscheiden Sie auch, ob eine Route zu Chat Completions oder Responses gehört. Halten Sie Endpunkt-Familien getrennt; wenn Sie Agenten-Routen im Responses-Stil evaluieren, kombinieren Sie diesen Leitfaden mit dem Flatkey OpenAI-kompatiblen Responses API-Router.

Richtlinie für Wiederholungen, Fallback und Stopp-Bedingungen

Wiederholungen können Routing-Fehler verbergen. Eine strikte LangGraph Multi-Model Routing-Richtlinie sollte festlegen, wann wiederholt, wann auf ein Fallback zurückgegriffen und wann gestoppt werden soll.

LangChain-Middleware kann bei Wiederholungen, Fallback und Aufruflimits auf Agenten-Ebene helfen. Für handgebaute LangGraph-Workflows behalten Sie dieselbe Richtlinie in der Nähe des Knotens, der das Modell aufruft, und belegen Sie das Ergebnis dann in den Flatkey-Protokollen.

Test-Checkliste vor der Veröffentlichung

Führen Sie diese Prüfungen durch, bevor Sie Flatkey zur Standardroute für einen Agenten machen.

1. Senden Sie eine direkte curl-Anfrage an https://router.flatkey.ai/v1/chat/completions mit dem vorgesehenen Schlüssel und Modell-Alias.
2. Rufen Sie jeden LangChain-Modell-Client einmal außerhalb von LangGraph auf.
3. Führen Sie den Graphen mit einem Prompt für die einfache Route, einem für die komplexe Route und einem für die Tool-lastige Route aus.
4. Erzwingen Sie den Stopp-Pfad, indem Sie budget_cents auf 0 setzen.
5. Erzwingen Sie das Wiederholungslimit, indem Sie errors auf den maximal zulässigen Wert setzen.
6. Bestätigen Sie, dass jede Anfrage in den Flatkey-Protokollen mit dem erwarteten Zeitstempel, der Schlüsselbezeichnung, dem Routennamen und dem Modell-Alias erscheint.
7. Vergleichen Sie die Kosten- oder Nutzungsfelder mit dem Eigentümer, der das Workflow-Budget genehmigt. Die Flatkey-Preisseite ist der richtige öffentliche Ort, um diese Überprüfung zu beginnen.

Das Ergebnis dieser Checkliste wird zum Abnahmepaket für das LangGraph Multi-Model Routing. Es ist nützlicher als ein Screenshot eines funktionierenden Prompts, da es beweist, dass der Graph, der Modell-Client und das Gateway alle übereinstimmen.

Fehlerbehebung beim LangGraph Multi-Model Routing

Wenn die erste Route fehlschlägt, halten Sie die Debugging-Oberfläche klein: Schlüssel, Basis-URL, Modell-Alias, ein Modell-Client, ein Graph-Knoten und eine Flatkey-Protokollsuche.

FAQ

Ist LangGraph Multi-Model Routing dasselbe wie Anbieter-Failover?

Nein. LangGraph Multi-Model Routing entscheidet vor oder während der Graph-Ausführung, welche Route zur Aufgabe passt. Anbieter-Failover ist das, was passiert, wenn eine ausgewählte Route nicht abgeschlossen werden kann. Sie können beides verwenden, aber sie sollten separat getestet werden.

Sollte jeder LangGraph-Knoten ein anderes Modell verwenden?

Nein. Beginnen Sie mit zwei oder drei expliziten Routen. Zu viele Modell-Aliase erschweren die Überprüfung von Protokollen, Budgets und Rollbacks.

Kann ich Flatkey sowohl mit Chat Completions- als auch mit Responses-Routen verwenden?

Flatkey stellt OpenAI-kompatible Endpunkt-Familien bereit, aber jeder Client-Pfad benötigt dennoch seinen eigenen Test. Halten Sie die Prüfungen für Chat Completions und Responses getrennt, insbesondere für Tool-Aufrufe, Streaming, Nutzungsfelder und Fallback-Verhalten.

Abschließende Checkliste

Ihr LangGraph Multi-Model Routing-Setup ist bereit, über eine Vorlage hinauszugehen, wenn:

1. Die Graph-Route ist im Zustand und in den Protokollen sichtbar.
2. Jede Route ist einem benannten Modell-Alias zugeordnet.
3. Der Flatkey-Schlüssel kann jeden ausgewählten Alias über die OpenAI-kompatible Basis-URL aufrufen.
4. Tool-lastige Routen bestehen Schema-, Argument-, Cap- und Fehlertests.
5. Budget- und Wiederholungs-Stoppbedingungen werden vor einem weiteren Modellaufruf ausgeführt.
6. Flatkey-Nutzungs- oder Anforderungsprotokolle bestätigen die ausgewählte Route.
7. Ein Rollback ist eine einzelne Konfigurationsänderung, kein Neuschreiben der Anwendung.

Wenn Sie bereit sind, den LangGraph-Agentenverkehr über ein einziges Gateway zu leiten, holen Sie sich einen Flatkey-Schlüssel, beginnen Sie mit einer einzigen risikoarmen Graph-Route und erweitern Sie diese erst, nachdem die Protokolle die Funktionsfähigkeit der Richtlinie belegen.