Roteamento Multi-Modelo com LangGraph: Verificações de Gateway para Workflows de Agentes

O roteamento multi-modelo com LangGraph é, em primeiro lugar, um problema de design de grafo e, em segundo, um problema de gateway. O grafo decide que tipo de trabalho está a acontecer, o cliente do modelo decide que rota compatível com OpenAI chamar, e o gateway deve comprovar se cada chamada permaneceu dentro das regras de orçamento, ferramenta, repetição, registo e condição de paragem.

O Flatkey encaixa-se nessa fronteira de gateway. O seu site público mostra uma rota de chat compatível com OpenAI em https://router.flatkey.ai/v1/chat/completions, com uma chave, visibilidade de uso, controlos de faturação e roteamento de modelo num só lugar. Este guia mostra uma configuração prática de roteamento multi-modelo com LangGraph para workflows de agentes sem assumir que todos os aliases de modelo, comportamentos de ferramenta ou rotas de fallback já foram validados na sua conta.

Resposta rápida para o roteamento multi-modelo com LangGraph

Uma configuração segura de roteamento multi-modelo com LangGraph separa o roteamento em três camadas.

Não esconda o roteamento multi-modelo com LangGraph dentro de um único prompt longo. Coloque a política em nós de grafo, arestas condicionais e verificações de gateway que a sua equipa possa inspecionar.

Porque o roteamento de modelo pertence às fronteiras do grafo

A maioria dos exemplos de LangGraph foca-se no fluxo de controlo do grafo: estado, nós, arestas, ferramentas e persistência. Esse é o ponto de partida correto, mas os agentes de produção também precisam de fronteiras de rota que as equipas de plataforma e finanças possam analisar.

Use rotas ao nível do grafo quando o workflow tiver perfis de custo, latência ou risco de ferramenta claramente diferentes:

É nessa fronteira que o Flatkey pode ajudar. Em vez de espalhar chaves de fornecedor separadas por cada nó, cada rota pode chamar um URL base de API compatível com OpenAI enquanto o Flatkey mantém a visibilidade ao nível do gateway. Para o design de políticas adjacentes, consulte o guia do Flatkey sobre controlos de gateway para agentes de IA.

Verificações de origem antes de ligar a rota

Use a documentação atual e verificações de conta em tempo real antes de tratar os modelos como código de produção.

O código abaixo é um modelo. Execute-o com as suas versões atuais de langchain, langchain-openai e langgraph antes de implementar uma política de roteamento multi-modelo com LangGraph.

Configurar modelos de chat suportados pelo Flatkey

Instale os pacotes atuais no ambiente que executa o seu grafo.

pip install -U langgraph langchain langchain-openai

Mantenha a raiz da API separada do caminho do endpoint. Os clientes LangChain devem receber o URL base; o cliente adiciona o caminho de Chat Completions para chamadas de chat compatíveis com 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

Depois, crie clientes de modelo explícitos para cada rota.

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 é a forma útil mais pequena para o roteamento multi-modelo com LangGraph: cada rota tem um cliente de modelo nomeado, mas todas as chamadas usam o mesmo limite de gateway. Não presuma que um alias de modelo suporta streaming ou ferramentas apenas porque outro alias o faz. Teste cada rota separadamente.

Construa um modelo de roteamento com LangGraph

Use um nó classificador para escrever a rota no estado. Em seguida, deixe as arestas condicionais decidirem qual nó será executado a seguir.

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:
    """Ferramenta de modelo. Substitua pela sua consulta real de apenas leitura."""
    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()

Este modelo mantém o roteamento multi-modelo com LangGraph visível. Um revisor pode ver por que uma solicitação foi para simple_answer, complex_answer, tool_answer ou stop sem fazer engenharia reversa de um prompt.

O nó tool_answer acima verifica a rota do modelo que pode propor chamadas de ferramentas. Se o seu grafo deve executar ferramentas, adicione um ToolNode do LangGraph ou o seu próprio executor após esse nó de modelo e, em seguida, roteie o resultado da ferramenta de volta para o grafo com as mesmas verificações de orçamento e condição de parada.

Adicione verificações de gateway em torno de cada chamada de modelo

A rota do grafo não deve ser a única proteção. Adicione um pequeno wrapper que verifica os orçamentos antes de uma chamada de modelo e registra evidências após uma chamada de 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:
    # Substitua isso por logs estruturados. Inclua um rótulo de chave redigido,
    # nome da rota, alias do modelo, carimbo de data/hora da solicitação e metadados da resposta.
    print(
        {
            "route": decision.route,
            "model_alias": decision.model_alias,
            "allowed": decision.allowed,
            "reason": decision.reason,
            "started_at": decision.started_at,
            "response_type": response.type,
        }
    )

Em produção, não se limite aos logs locais. Compare o carimbo de data/hora e o alias do modelo com os logs de uso ou de solicitação do Flatkey. Essa é a prova de que o roteamento multi-modelo com LangGraph usou a rota de gateway que você pretendia.

Verifique as ferramentas antes de confiar em uma rota com uso intensivo de ferramentas

Nós com muitas ferramentas merecem seu próprio pacote de verificação. Um modelo pode ser bom em chat simples, mas falhar no esquema da sua ferramenta, transmitir deltas de ferramentas de forma diferente ou produzir argumentos de ferramenta que seu executor rejeita. Para verificações de compatibilidade mais aprofundadas, use o guia da Flatkey para compatibilidade de chamada de ferramentas entre provedores.

É aqui também que você decide se uma rota pertence a Chat Completions ou Responses. Mantenha as famílias de endpoints separadas; se você estiver avaliando rotas de agente no estilo Responses, combine este guia com o roteador de API de Responses compatível com OpenAI da Flatkey.

Política de nova tentativa, fallback e condição de parada

Novas tentativas podem ocultar erros de roteamento. Uma política rigorosa de roteamento multi-modelo com LangGraph deve dizer quando tentar novamente, quando usar fallback e quando parar.

O middleware do LangChain pode ajudar com novas tentativas, fallback e limites de chamada no nível do agente. Para workflows LangGraph construídos manualmente, mantenha a mesma política perto do nó que chama o modelo e, em seguida, comprove o resultado nos logs da Flatkey.

Checklist de teste pré-publicação

Execute estas verificações antes de tornar a Flatkey a rota padrão para um agente.

1. Envie uma solicitação curl direta para https://router.flatkey.ai/v1/chat/completions com a chave e o alias de modelo pretendidos.
2. Invoque cada cliente de modelo LangChain uma vez fora do LangGraph.
3. Execute o grafo com um prompt para a rota simples, um para a rota complexa e um para a rota com muitas ferramentas.
4. Force o caminho de parada definindo budget_cents como 0.
5. Force o limite de novas tentativas definindo errors como o valor máximo permitido.
6. Confirme se cada solicitação aparece nos logs da Flatkey com o carimbo de data/hora, rótulo da chave, nome da rota e alias de modelo esperados.
7. Compare os campos de custo ou uso com o proprietário que aprova o orçamento do workflow. A página de preços da Flatkey é o lugar público certo para iniciar essa revisão.

O resultado deste checklist se torna o pacote de aceitação para o roteamento multi-modelo com LangGraph. É mais útil do que uma captura de tela de um prompt funcionando, pois prova que o grafo, o cliente do modelo e o gateway estão todos de acordo.

Solução de problemas de roteamento multi-modelo com LangGraph

Se a primeira rota falhar, mantenha a superfície de depuração pequena: chave, URL base, alias de modelo, um cliente de modelo, um nó de grafo e uma consulta de log na Flatkey.

FAQ

O roteamento multi-modelo com LangGraph é o mesmo que failover de provedor?

Não. O roteamento multi-modelo com LangGraph decide qual rota se ajusta à tarefa antes ou durante a execução do grafo. Failover de provedor é o que acontece quando uma rota selecionada não pode ser concluída. Você pode usar ambos, mas eles devem ser testados separadamente.

Cada nó do LangGraph deve usar um modelo diferente?

Não. Comece com duas ou três rotas explícitas. Muitos aliases de modelo tornam os logs, orçamentos e a reversão (rollback) mais difíceis de revisar.

Posso usar o Flatkey com as rotas de Chat Completions e Responses?

O Flatkey expõe famílias de endpoints compatíveis com a OpenAI, mas cada caminho de cliente ainda precisa de seu próprio teste. Mantenha as verificações de Chat Completions e Responses separadas, especialmente para chamadas de ferramentas, streaming, campos de uso e comportamento de fallback.

Checklist final

Sua configuração de roteamento multi-modelo com LangGraph está pronta para ir além de um modelo quando:

1. A rota do grafo está visível no estado e nos logs.
2. Cada rota mapeia para um alias de modelo nomeado.
3. A chave Flatkey pode chamar cada alias selecionado através da URL base compatível com a OpenAI.
4. Rotas com uso intensivo de ferramentas passam nos testes de esquema, argumento, limite e erro.
5. As condições de parada de orçamento e nova tentativa são executadas antes de outra chamada de modelo.
6. Os logs de uso ou de requisição do Flatkey confirmam a rota selecionada.
7. A reversão (rollback) é uma única mudança de configuração, não uma reescrita da aplicação.

Quando você estiver pronto para rotear o tráfego do agente LangGraph através de um único gateway, obtenha uma chave Flatkey, comece com uma única rota de grafo de baixo risco e expanda somente depois que os logs provarem que a política funciona.