LangGraph Multi-Model Routing: Pemeriksaan Gateway untuk Workflow Agen

Routing multi-model LangGraph adalah masalah desain graph terlebih dahulu dan masalah gateway kedua. Graph menentukan jenis pekerjaan apa yang sedang berjalan, klien model menentukan rute OpenAI-compatible mana yang akan dipanggil, dan gateway seharusnya membuktikan apakah setiap panggilan tetap berada di dalam aturan budget, tool, retry, logging, dan stop-condition.

Flatkey cocok pada batas gateway itu. Situs publiknya menampilkan route chat OpenAI-compatible di https://router.flatkey.ai/v1/chat/completions, dengan satu key, visibilitas penggunaan, kontrol billing, dan routing model dalam satu tempat. Panduan ini menunjukkan setup routing multi-model LangGraph yang praktis untuk workflow agen tanpa berasumsi bahwa setiap alias model, perilaku tool, atau fallback route sudah divalidasi di akun Anda.

Jawaban singkat untuk routing multi-model LangGraph

Setup routing multi-model LangGraph yang aman memisahkan routing ke dalam tiga lapisan.

Jangan sembunyikan routing multi-model LangGraph di dalam satu prompt panjang. Letakkan kebijakannya di node graph, conditional edge, dan pemeriksaan gateway yang dapat ditinjau tim Anda.

Mengapa routing model berada di batas graph

Kebanyakan contoh LangGraph berfokus pada control flow graph: state, node, edge, tool, dan persistensi. Itu adalah titik awal yang tepat, tetapi agen produksi juga membutuhkan batas route yang bisa dipahami oleh tim platform dan finance.

Gunakan route tingkat graph ketika workflow memiliki profil biaya, latensi, atau risiko tool yang jelas berbeda:

Batas itu adalah tempat Flatkey dapat membantu. Alih-alih menyebarkan key provider terpisah di setiap node, setiap route dapat memanggil base URL API yang OpenAI-compatible sementara Flatkey menjaga visibilitas di level gateway. Untuk desain kebijakan terkait, lihat panduan Flatkey tentang kontrol gateway agen AI.

Pemeriksaan sumber sebelum Anda menghubungkan route

Gunakan dokumen terbaru dan pemeriksaan akun live sebelum memperlakukan template sebagai kode produksi.

Kode di bawah ini adalah template. Jalankan dengan versi langchain, langchain-openai, dan langgraph Anda yang terbaru sebelum merilis kebijakan routing multi-model LangGraph.

Konfigurasikan model chat berbasis Flatkey

Instal paket terbaru di environment yang menjalankan graph Anda.

pip install -U langgraph langchain langchain-openai

Jaga root API tetap terpisah dari path endpoint. Klien LangChain harus menerima base URL; klien akan menambahkan path Chat Completions untuk panggilan chat OpenAI-compatible.

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

Lalu buat klien model yang eksplisit untuk setiap 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,
)

Ini adalah bentuk terkecil yang berguna untuk LangGraph multi-model routing: setiap rute memiliki klien model bernama, tetapi semua panggilan menggunakan batas gateway yang sama. Jangan berasumsi bahwa alias model mendukung streaming atau tools hanya karena alias lain mendukungnya. Uji setiap rute secara terpisah.

Bangun template routing LangGraph

Gunakan node classifier untuk menulis rute ke state. Lalu biarkan conditional edges memutuskan node mana yang dijalankan berikutnya.

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. Ganti dengan lookup read-only Anda yang sebenarnya."""
    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="Batas panggilan tool telah tercapai.")] }
    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()

Template ini membuat LangGraph multi-model routing tetap terlihat. Seorang reviewer dapat melihat mengapa sebuah permintaan diarahkan ke simple_answer, complex_answer, tool_answer, atau stop tanpa perlu membalikkan rekayasa sebuah prompt.

Node tool_answer di atas memverifikasi rute model yang dapat mengajukan panggilan tool. Jika graph Anda harus mengeksekusi tools, tambahkan LangGraph ToolNode atau eksekutor Anda sendiri setelah node model itu, lalu arahkan hasil tool kembali ke graph dengan pemeriksaan budget dan kondisi berhenti yang sama.

Tambahkan pemeriksaan gateway di sekitar setiap panggilan model

Rute graph tidak boleh menjadi satu-satunya pagar pengaman. Tambahkan wrapper kecil yang memeriksa budget sebelum panggilan model dan mencatat bukti setelah panggilan model.

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:
    # Ganti ini dengan logging terstruktur. Sertakan label kunci yang telah direduksi,
    # nama route, alias model, timestamp permintaan, dan metadata respons.
    print(
        {
            "route": decision.route,
            "model_alias": decision.model_alias,
            "allowed": decision.allowed,
            "reason": decision.reason,
            "started_at": decision.started_at,
            "response_type": response.type,
        }
    )

Dalam produksi, jangan berhenti pada log lokal. Cocokkan timestamp dan alias model terhadap penggunaan atau log permintaan Flatkey. Itulah bukti bahwa LangGraph multi-model routing menggunakan rute gateway yang Anda inginkan.

Periksa tools sebelum Anda memercayai rute yang sarat tools

Node yang berat pada tool layak mendapatkan paket verifikasi mereka sendiri. Sebuah model mungkin bagus untuk chat biasa tetapi gagal pada skema tool Anda, mengalirkan delta tool dengan cara yang berbeda, atau menghasilkan argumen tool yang ditolak oleh executor Anda. Untuk pemeriksaan kompatibilitas yang lebih mendalam, gunakan panduan Flatkey tentang kompatibilitas tool-calling lintas provider.

Di sinilah Anda juga memutuskan apakah sebuah route termasuk Chat Completions atau Responses. Pisahkan keluarga endpoint; jika Anda mengevaluasi route agen bergaya Responses, pasangkan panduan ini dengan Flatkey router API Responses yang kompatibel dengan OpenAI.

Kebijakan retry, fallback, dan kondisi berhenti

Retry dapat menyamarkan kesalahan routing. Kebijakan LangGraph multi-model routing yang ketat harus menjelaskan kapan harus retry, kapan harus fallback, dan kapan harus berhenti.

Middleware LangChain dapat membantu dengan retry level agen, fallback, dan batas panggilan. Untuk workflow LangGraph yang dibuat вручную, pertahankan kebijakan yang sama di dekat node yang memanggil model, lalu buktikan hasilnya di log Flatkey.

Daftar periksa pengujian pra-publikasi

Jalankan pemeriksaan ini sebelum menjadikan Flatkey sebagai route default untuk sebuah agen.

1. Kirim satu request langsung curl ke https://router.flatkey.ai/v1/chat/completions dengan key dan alias model yang dimaksud.
2. Panggil masing-masing client model LangChain sekali di luar LangGraph.
3. Jalankan graph dengan satu prompt untuk route sederhana, satu untuk route kompleks, dan satu untuk route yang berat pada tool.
4. Paksa jalur berhenti dengan mengatur budget_cents ke 0.
5. Paksa batas retry dengan mengatur errors ke nilai maksimum yang diizinkan.
6. Pastikan setiap request muncul di log Flatkey dengan timestamp, label key, nama route, dan alias model yang diharapkan.
7. Bandingkan field biaya atau penggunaan dengan pemilik yang menyetujui budget workflow. Halaman harga Flatkey adalah tempat publik yang tepat untuk memulai peninjauan itu.

Hasil daftar periksa ini menjadi paket penerimaan untuk LangGraph multi-model routing. Ini lebih berguna daripada tangkapan layar prompt yang berhasil karena membuktikan bahwa graph, client model, dan gateway semuanya sepakat.

Memecahkan masalah LangGraph multi-model routing

Jika route pertama gagal, jaga agar permukaan debugging tetap kecil: key, base URL, alias model, satu client model, satu node graph, dan satu pencarian log Flatkey.

FAQ

Apakah LangGraph multi-model routing sama dengan failover provider?

Tidak. LangGraph multi-model routing menentukan route mana yang paling cocok untuk tugas sebelum atau selama eksekusi graph. Failover provider adalah apa yang terjadi ketika route yang dipilih tidak dapat selesai. Anda dapat menggunakan keduanya, tetapi keduanya harus diuji secara terpisah.

Haruskah setiap node LangGraph menggunakan model yang berbeda?

Tidak. Mulailah dengan dua atau tiga rute yang eksplisit. Terlalu banyak alias model membuat log, anggaran, dan rollback lebih sulit ditinjau.

Bisakah saya menggunakan Flatkey dengan rute Chat Completions dan Responses sekaligus?

Flatkey mengekspos keluarga endpoint yang kompatibel dengan OpenAI, tetapi setiap jalur klien tetap memerlukan pengujian sendiri. Pisahkan pemeriksaan Chat Completions dan Responses, terutama untuk panggilan tool, streaming, field usage, dan perilaku fallback.

Daftar periksa akhir

Setup LangGraph multi-model routing Anda siap melampaui template ketika:

1. Rute graph terlihat di state dan log.
2. Setiap rute dipetakan ke alias model yang dinamai.
3. Key Flatkey dapat memanggil setiap alias yang dipilih melalui base URL yang kompatibel dengan OpenAI.
4. Rute yang banyak menggunakan tool lulus pengujian schema, argumen, batas, dan error.
5. Kondisi berhenti anggaran dan retry berjalan sebelum panggilan model lainnya.
6. Usage atau log permintaan Flatkey mengonfirmasi rute yang dipilih.
7. Rollback adalah satu perubahan konfigurasi, bukan penulisan ulang aplikasi.

Ketika Anda siap merutekan traffic agen LangGraph melalui satu gateway, dapatkan key Flatkey, mulai dengan satu rute graph berisiko rendah, dan perluas hanya setelah log membuktikan kebijakan tersebut berfungsi.