Routage multi-modèle LangGraph : Contrôles de passerelle pour les flux de travail d'agents

Le routage multi-modèle LangGraph est d'abord un problème de conception de graphe et ensuite un problème de passerelle. Le graphe décide du type de travail à effectuer, le client du modèle décide quelle route compatible OpenAI appeler, et la passerelle doit vérifier si chaque appel est resté dans les limites des règles de budget, d'outil, de nouvelle tentative, de journalisation et de condition d'arrêt.

Flatkey s'intègre à cette frontière de passerelle. Son site public affiche une route de chat compatible OpenAI à l'adresse https://router.flatkey.ai/v1/chat/completions, avec une seule clé, une visibilité sur l'utilisation, des contrôles de facturation et un routage de modèle en un seul endroit. Ce guide présente une configuration pratique de routage multi-modèle LangGraph pour les flux de travail d'agents sans supposer que chaque alias de modèle, comportement d'outil ou route de secours a déjà été validé dans votre compte.

Réponse rapide pour le routage multi-modèle LangGraph

Une configuration sécurisée de routage multi-modèle LangGraph sépare le routage en trois couches.

Ne masquez pas le routage multi-modèle LangGraph à l'intérieur d'une seule longue invite. Placez la politique dans les nœuds de graphe, les arêtes conditionnelles et les contrôles de passerelle que votre équipe peut inspecter.

Pourquoi le routage de modèle appartient aux frontières du graphe

La plupart des exemples LangGraph se concentrent sur le flux de contrôle du graphe : état, nœuds, arêtes, outils et persistance. C'est le bon point de départ, mais les agents en production ont également besoin de frontières de routage que les équipes de plateforme et financières peuvent analyser.

Utilisez des routes au niveau du graphe lorsque le flux de travail présente des profils de coût, de latence ou de risque lié aux outils clairement différents :

C'est à cette frontière que Flatkey peut aider. Au lieu de disperser des clés de fournisseur distinctes dans chaque nœud, chaque route peut appeler une URL de base d'API compatible OpenAI pendant que Flatkey maintient une visibilité au niveau de la passerelle. Pour la conception de politiques adjacentes, consultez le guide Flatkey sur les contrôles de passerelle pour les agents IA.

Vérifications des sources avant de câbler la route

Utilisez la documentation actuelle et les vérifications de compte en direct avant de traiter les modèles comme du code de production.

Le code ci-dessous est un modèle. Exécutez-le avec vos versions actuelles de langchain, langchain-openai et langgraph avant de déployer une politique de routage multi-modèle LangGraph.

Configurer les modèles de chat basés sur Flatkey

Installez les paquets actuels dans l'environnement qui exécute votre graphe.

pip install -U langgraph langchain langchain-openai

Gardez la racine de l'API séparée du chemin du point de terminaison. Les clients LangChain doivent recevoir l'URL de base ; le client ajoute le chemin des Complétions de Chat pour les appels de chat compatibles OpenAI.

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

Créez ensuite des clients de modèle explicites pour chaque 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,
)

C'est la forme utile la plus petite pour le routage multi-modèle LangGraph : chaque route a un client de modèle nommé, mais tous les appels utilisent la même limite de passerelle. Ne présumez pas qu'un alias de modèle prend en charge le streaming ou les outils simplement parce qu'un autre alias le fait. Testez chaque route séparément.

Construire un modèle de routage LangGraph

Utilisez un nœud classifieur pour écrire la route dans l'état. Ensuite, laissez les arêtes conditionnelles décider quel nœud s'exécutera.

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:
    """Outil modèle. Remplacez par votre véritable recherche en lecture seule."""
    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="Limite d'appels d'outils atteinte.")] }
    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()

Ce modèle maintient le routage multi-modèle LangGraph visible. Un réviseur peut voir pourquoi une requête est allée à simple_answer, complex_answer, tool_answer ou stop sans avoir à faire de l'ingénierie inverse sur un prompt.

Le nœud tool_answer ci-dessus vérifie la route du modèle qui peut proposer des appels d'outils. Si votre graphe doit exécuter des outils, ajoutez un ToolNode LangGraph ou votre propre exécuteur après ce nœud de modèle, puis routez le résultat de l'outil de nouveau dans le graphe avec les mêmes vérifications de budget et de condition d'arrêt.

Ajouter des contrôles de passerelle autour de chaque appel de modèle

La route du graphe ne doit pas être le seul garde-fou. Ajoutez un petit wrapper qui vérifie les budgets avant un appel de modèle et enregistre les preuves après un appel de modèle.

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:
    # Remplacez ceci par une journalisation structurée. Incluez une étiquette de clé expurgée,
    # le nom de la route, l'alias du modèle, l'horodatage de la requête et les métadonnées de la réponse.
    print(
        {
            "route": decision.route,
            "model_alias": decision.model_alias,
            "allowed": decision.allowed,
            "reason": decision.reason,
            "started_at": decision.started_at,
            "response_type": response.type,
        }
    )

En production, ne vous arrêtez pas aux journaux locaux. Faites correspondre l'horodatage et l'alias du modèle avec les journaux d'utilisation ou de requêtes de Flatkey. C'est la preuve que le routage multi-modèle LangGraph a utilisé la route de passerelle que vous aviez prévue.

Vérifiez les outils avant de vous fier à une route qui en dépend fortement

Les nœuds riches en outils méritent leur propre paquet de vérification. Un modèle peut être bon pour une simple conversation mais échouer avec votre schéma d'outils, diffuser les deltas d'outils différemment, ou produire des arguments d'outils que votre exécuteur rejette. Pour des vérifications de compatibilité plus approfondies, utilisez le guide Flatkey sur la compatibilité des appels d'outils entre les fournisseurs.

C'est également ici que vous décidez si une route appartient à Chat Completions ou à Responses. Gardez les familles de points de terminaison séparées ; si vous évaluez des routes d'agents de type Responses, associez ce guide au routeur d'API Responses compatible OpenAI de Flatkey.

Politique de relance, de repli et de condition d'arrêt

Les relances peuvent masquer des erreurs de routage. Une politique stricte de routage multi-modèle LangGraph doit indiquer quand relancer, quand se replier et quand s'arrêter.

Le middleware LangChain peut aider avec les relances au niveau de l'agent, le repli et les limites d'appels. Pour les flux de travail LangGraph créés manuellement, conservez la même politique près du nœud qui appelle le modèle, puis prouvez le résultat dans les journaux Flatkey.

Liste de contrôle des tests avant publication

Exécutez ces vérifications avant de faire de Flatkey la route par défaut pour un agent.

1. Envoyez une requête curl directe à https://router.flatkey.ai/v1/chat/completions avec la clé et l'alias de modèle prévus.
2. Invoquez chaque client de modèle LangChain une fois en dehors de LangGraph.
3. Exécutez le graphe avec une invite pour la route simple, une pour la route complexe et une pour la route riche en outils.
4. Forcez le chemin d'arrêt en définissant budget_cents sur 0.
5. Forcez la limite de relances en définissant errors sur la valeur maximale autorisée.
6. Confirmez que chaque requête apparaît dans les journaux Flatkey avec l'horodatage, l'étiquette de clé, le nom de la route et l'alias de modèle attendus.
7. Comparez les champs de coût ou d'utilisation avec le propriétaire qui approuve le budget du flux de travail. La page de tarification de Flatkey est le bon endroit public pour commencer cet examen.

Le résultat de cette liste de contrôle devient le paquet d'acceptation pour le routage multi-modèle LangGraph. Il est plus utile qu'une capture d'écran d'une invite fonctionnelle car il prouve que le graphe, le client du modèle et la passerelle sont tous d'accord.

Dépannage du routage multi-modèle LangGraph

Si la première route échoue, gardez la surface de débogage petite : clé, URL de base, alias de modèle, un client de modèle, un nœud de graphe et une consultation des journaux Flatkey.

FAQ

Le routage multi-modèle LangGraph est-il la même chose que le basculement de fournisseur ?

Non. Le routage multi-modèle LangGraph décide quelle route correspond à la tâche avant ou pendant l'exécution du graphe. Le basculement de fournisseur est ce qui se passe lorsqu'une route sélectionnée ne peut pas être terminée. Vous pouvez utiliser les deux, mais ils doivent être testés séparément.

Chaque nœud LangGraph doit-il utiliser un modèle différent ?

Non. Commencez avec deux ou trois routes explicites. Trop d'alias de modèles rendent les journaux, les budgets et la restauration plus difficiles à examiner.

Puis-je utiliser Flatkey avec les routes Chat Completions et Responses ?

Flatkey expose des familles de points de terminaison compatibles avec OpenAI, mais chaque chemin client nécessite toujours son propre test. Gardez les vérifications pour Chat Completions et Responses séparées, en particulier pour les appels d'outils, le streaming, les champs d'utilisation et le comportement de repli.

Checklist finale

Votre configuration de routage multi-modèle LangGraph est prête à dépasser le stade de modèle lorsque :

1. La route du graphe est visible dans l'état et les journaux.
2. Chaque route correspond à un alias de modèle nommé.
3. La clé Flatkey peut appeler chaque alias sélectionné via l'URL de base compatible avec OpenAI.
4. Les routes utilisant beaucoup d'outils réussissent les tests de schéma, d'argument, de capacité et d'erreur.
5. Les conditions d'arrêt pour le budget et les nouvelles tentatives s'exécutent avant un autre appel de modèle.
6. Les journaux d'utilisation ou de requêtes de Flatkey confirment la route sélectionnée.
7. La restauration est un simple changement de configuration, pas une réécriture de l'application.

Lorsque vous êtes prêt à router le trafic de l'agent LangGraph via une seule passerelle, obtenez une clé Flatkey, commencez par une seule route de graphe à faible risque, et n'étendez qu'une fois que les journaux prouvent que la politique fonctionne.