Enrutamiento Multimodelo con LangGraph: Controles de Gateway para Flujos de Trabajo de Agentes

El enrutamiento multimodelo con LangGraph es, en primer lugar, un problema de diseño de grafos y, en segundo lugar, un problema de gateway. El grafo decide qué tipo de trabajo se está realizando, el cliente del modelo decide a qué ruta compatible con OpenAI llamar y el gateway debe comprobar si cada llamada se mantuvo dentro de las reglas de presupuesto, herramientas, reintentos, registro y condiciones de detención.

Flatkey encaja en ese límite del gateway. Su sitio público muestra una ruta de chat compatible con OpenAI en https://router.flatkey.ai/v1/chat/completions, con una sola clave, visibilidad de uso, controles de facturación y enrutamiento de modelos en un solo lugar. Esta guía muestra una configuración práctica de enrutamiento multimodelo con LangGraph para flujos de trabajo de agentes sin asumir que cada alias de modelo, comportamiento de herramienta o ruta de respaldo ya ha sido validado en su cuenta.

Respuesta rápida para el enrutamiento multimodelo con LangGraph

Una configuración segura de enrutamiento multimodelo con LangGraph separa el enrutamiento en tres capas.

No oculte el enrutamiento multimodelo con LangGraph dentro de un único prompt largo. Coloque la política en nodos de grafo, bordes condicionales y controles de gateway que su equipo pueda inspeccionar.

Por qué el enrutamiento de modelos pertenece a los límites del grafo

La mayoría de los ejemplos de LangGraph se centran en el flujo de control del grafo: estado, nodos, bordes, herramientas y persistencia. Ese es el punto de partida correcto, pero los agentes de producción también necesitan límites de ruta sobre los que los equipos de plataforma y finanzas puedan razonar.

Utilice rutas a nivel de grafo cuando el flujo de trabajo tenga perfiles de costo, latencia o riesgo de herramienta claramente diferentes:

Ese límite es donde Flatkey puede ayudar. En lugar de dispersar claves de proveedor separadas por cada nodo, cada ruta puede llamar a una URL base de API compatible con OpenAI mientras Flatkey mantiene la visibilidad a nivel de gateway. Para el diseño de políticas adyacentes, consulte la guía de Flatkey sobre controles de gateway para agentes de IA.

Comprobaciones de origen antes de conectar la ruta

Utilice la documentación actual y las comprobaciones de la cuenta en vivo antes de tratar las plantillas como código de producción.

El código a continuación es una plantilla. Ejecútelo con sus versiones actuales de langchain, langchain-openai y langgraph antes de implementar una política de enrutamiento multimodelo con LangGraph.

Configurar modelos de chat respaldados por Flatkey

Instale los paquetes actuales en el entorno que ejecuta su grafo.

pip install -U langgraph langchain langchain-openai

Mantenga la raíz de la API separada de la ruta del endpoint. Los clientes de LangChain deben recibir la URL base; el cliente agrega la ruta de Chat Completions para las llamadas de chat compatibles con 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

Luego, cree clientes de modelo explícitos para cada ruta.

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,
)

Esta es la forma útil más pequeña para el enrutamiento multimodelo con LangGraph: cada ruta tiene un cliente de modelo con nombre, pero todas las llamadas utilizan el mismo límite de gateway. No asuma que un alias de modelo admite streaming o herramientas solo porque otro alias lo haga. Pruebe cada ruta por separado.

Construir una plantilla de enrutamiento de LangGraph

Use un nodo clasificador para escribir la ruta en el estado. Luego, deje que los bordes condicionales decidan qué nodo se ejecuta a continuación.

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:
    """Herramienta de plantilla. Reemplácela con su búsqueda real de solo lectura."""
    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-call limit reached.")] }
    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()

Esta plantilla mantiene visible el enrutamiento multimodelo con LangGraph. Un revisor puede ver por qué una solicitud fue a simple_answer, complex_answer, tool_answer o stop sin tener que hacer ingeniería inversa de un prompt.

El nodo tool_answer anterior verifica la ruta del modelo que puede proponer llamadas a herramientas. Si su grafo debe ejecutar herramientas, agregue un ToolNode de LangGraph o su propio ejecutor después de ese nodo de modelo, luego enrute el resultado de la herramienta de vuelta al grafo con el mismo presupuesto y las mismas comprobaciones de condición de parada.

Añadir controles de gateway en cada llamada al modelo

La ruta del grafo no debe ser la única barrera de protección. Añada un pequeño envoltorio que compruebe los presupuestos antes de una llamada al modelo y registre la evidencia después de una llamada al modelo.

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:
    # Reemplace esto con un registro estructurado. Incluya una etiqueta de clave redactada,
    # nombre de la ruta, alias del modelo, marca de tiempo de la solicitud y metadatos de la respuesta.
    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 producción, no se detenga en los registros locales. Compare la marca de tiempo y el alias del modelo con los registros de uso o de solicitud de Flatkey. Esa es la prueba de que el enrutamiento multimodelo con LangGraph utilizó la ruta de gateway que usted pretendía.

Comprobar las herramientas antes de confiar en una ruta con muchas herramientas

Los nodos con muchas herramientas merecen su propio paquete de verificación. Un modelo puede ser bueno en el chat simple pero fallar en el esquema de tu herramienta, transmitir los deltas de la herramienta de manera diferente o producir argumentos de herramienta que tu ejecutor rechace. Para comprobaciones de compatibilidad más profundas, utiliza la guía de Flatkey sobre la compatibilidad de llamadas a herramientas entre proveedores.

Aquí es también donde decides si una ruta pertenece a Completions de Chat o a Responses. Mantén las familias de endpoints separadas; si estás evaluando rutas de agentes estilo Responses, combina esta guía con el enrutador de API de Responses compatible con OpenAI de Flatkey.

Política de reintentos, fallback y condición de parada

Los reintentos pueden ocultar errores de enrutamiento. Una política estricta de enrutamiento multimodelo con LangGraph debe indicar cuándo reintentar, cuándo recurrir a un fallback y cuándo detenerse.

El middleware de LangChain puede ayudar con los reintentos a nivel de agente, el fallback y los límites de llamadas. Para los flujos de trabajo de LangGraph creados manualmente, mantén la misma política cerca del nodo que llama al modelo y luego demuestra el resultado en los registros de Flatkey.

Lista de comprobación previa a la publicación

Ejecuta estas comprobaciones antes de hacer de Flatkey la ruta predeterminada para un agente.

1. Envía una solicitud curl directa a https://router.flatkey.ai/v1/chat/completions con la clave y el alias de modelo previstos.
2. Invoca cada cliente de modelo de LangChain una vez fuera de LangGraph.
3. Ejecuta el grafo con una instrucción para la ruta simple, una para la ruta compleja y una para la ruta con muchas herramientas.
4. Fuerza la ruta de detención estableciendo budget_cents en 0.
5. Fuerza el límite de reintentos estableciendo errors en el valor máximo permitido.
6. Confirma que cada solicitud aparece en los registros de Flatkey con la marca de tiempo, la etiqueta de la clave, el nombre de la ruta y el alias del modelo esperados.
7. Compara los campos de costo o uso con el propietario que aprueba el presupuesto del flujo de trabajo. La página de precios de Flatkey es el lugar público adecuado para iniciar esa revisión.

El resultado de esta lista de comprobación se convierte en el paquete de aceptación para el enrutamiento multimodelo con LangGraph. Es más útil que una captura de pantalla de una instrucción que funciona porque demuestra que el grafo, el cliente del modelo y el gateway están todos de acuerdo.

Solución de problemas del enrutamiento multimodelo con LangGraph

Si la primera ruta falla, mantén la superficie de depuración pequeña: clave, URL base, alias de modelo, un cliente de modelo, un nodo de grafo y una consulta de registro de Flatkey.

Preguntas frecuentes

¿Es el enrutamiento multimodelo con LangGraph lo mismo que el failover de proveedor?

No. El enrutamiento multimodelo con LangGraph decide qué ruta se ajusta a la tarea antes o durante la ejecución del grafo. El failover de proveedor es lo que sucede cuando una ruta seleccionada no puede completarse. Puedes usar ambos, pero deben probarse por separado.

¿Debería cada nodo de LangGraph usar un modelo diferente?

No. Comience con dos o tres rutas explícitas. Demasiados alias de modelos dificultan la revisión de los registros, los presupuestos y la reversión.

¿Puedo usar Flatkey tanto con las rutas de Completado de Chat como con las de Respuestas?

Flatkey expone familias de endpoints compatibles con OpenAI, pero cada ruta de cliente aún necesita su propia prueba. Mantenga separadas las comprobaciones de Completado de Chat y de Respuestas, especialmente para las llamadas a herramientas, el streaming, los campos de uso y el comportamiento de fallback.

Lista de verificación final

Su configuración de enrutamiento multimodelo con LangGraph está lista para ir más allá de una plantilla cuando:

1. La ruta del grafo es visible en el estado y en los registros.
2. Cada ruta se asigna a un alias de modelo con nombre.
3. La clave de Flatkey puede llamar a cada alias seleccionado a través de la URL base compatible con OpenAI.
4. Las rutas con muchas herramientas superan las pruebas de esquema, argumento, límite y error.
5. Las condiciones de detención de presupuesto y reintento se ejecutan antes de otra llamada al modelo.
6. Los registros de uso o de solicitudes de Flatkey confirman la ruta seleccionada.
7. La reversión es un cambio de configuración, no una reescritura de la aplicación.

Cuando esté listo para enrutar el tráfico del agente de LangGraph a través de un único gateway, obtenga una clave de Flatkey, comience con una única ruta de grafo de bajo riesgo y amplíe solo después de que los registros demuestren que la política funciona.