Supervisor 动态路由:structured output 路由、override、routingReason
实现一个 Supervisor 节点,用 structured output 动态决定路由到哪个子 Agent,并支持人工 override 与记录路由理由。
今日目标
- 能实现一个用 structured output 输出路由决策的 Supervisor 节点
- 能给路由结果加上 routingReason,方便调试和复盘
- 能实现一个 override 机制,在模型路由错误时人工纠正
昨天那张图有个明显的假:三条边全是写死的,入口之后永远是同一个处理节点。今天让其中一条边由模型在运行时决定走向,并且把「判错了怎么办」一次性想清楚。读完回到页面顶部把三条目标勾掉。
小白版讲解
接警台不办案,只负责判断这是谁的活
打 110 的时候,接你电话的那个人不会去抓小偷,也不会去救火。他只做一件事:听你说完前两句,判断这是治安、交通还是火警,然后把工单转给对应的部门。整个通话可能只有二十秒,但这二十秒决定了后面所有人的忙闲——转错了部门,出警的人到了现场才发现不对,再转一次,时间全耗在路上。
这就是监督者(Supervisor)模式:一个节点专门负责判断「这一单该谁接」,判完就交出去,自己不干活。 沿用我们的电商客服场景,接单的有三位,名字这一周都不会变:order_lookup 查订单状态与物流进度,refund_draft 按规则拟一份退款方案但不执行退款,smalltalk 负责闲聊与兜底。
为什么把「判断」单独设成一个节点,而不是让查订单那位自己看着办?因为判断和执行是两种完全不同的活。判断要看全局、要快、要便宜,通常几十个 token 就够;执行要看细节、要调工具、要遵守一堆规则。混在一起,你既没法给判断单独换个小模型,也没法单独统计「分诊准确率」——而这个指标恰恰是多 Agent 系统里最值得盯的一个。
技术上,Supervisor 靠的是条件边(conditional edge):这条边的终点在编译期是未知的,运行时才由一个选择函数决定。昨天那三条无条件边写死了顺序,今天这条边把「下一步去哪」交给了状态里的一个字段。
import { StateGraph, START, END } from '@langchain/langgraph'
// Supervisor 只写两个字段:交给谁(route)、为什么这么判(routingReason)。它不回答用户的问题
const supervisor = async (state) => decide(lastText(state))
// 选择函数只读状态、不调模型:判断已经在 supervisor 里做完了,这里只负责翻译成节点名
const selectRoute = (state) => state.route ?? 'smalltalk'
export const graph = new StateGraph(AgentAnnotation)
.addNode('supervisor', supervisor)
.addNode('order_lookup', orderLookup)
.addNode('refund_draft', refundDraft)
.addNode('smalltalk', smalltalk)
.addEdge(START, 'supervisor')
// 第三个参数是「选择函数的返回值 → 节点名」的映射表。写全它:返回一个没登记的名字
// 编译期就报错,而且登记了却没人指向的节点会让 compile() 直接抛 UnreachableNodeError
.addConditionalEdges('supervisor', selectRoute, {
order_lookup: 'order_lookup',
refund_draft: 'refund_draft',
smalltalk: 'smalltalk',
})
.addEdge('order_lookup', END)
.addEdge('refund_draft', END)
.addEdge('smalltalk', END)
.compile()from langgraph.graph import StateGraph, START, END
# Supervisor 只写两个字段:交给谁(route)、为什么这么判(routing_reason)。它不回答用户的问题
async def supervisor(state: AgentState) -> dict:
return decide(last_text(state))
# 选择函数只读状态、不调模型:判断已经在 supervisor 里做完了,这里只负责翻译成节点名
def select_route(state: AgentState) -> str:
return state.get("route") or "smalltalk"
graph = (
StateGraph(AgentState)
.add_node("supervisor", supervisor)
.add_node("order_lookup", order_lookup)
.add_node("refund_draft", refund_draft)
.add_node("smalltalk", smalltalk)
.add_edge(START, "supervisor")
# 第三个参数是「选择函数的返回值 → 节点名」的映射表,写全它,图才画得出来
.add_conditional_edges(
"supervisor",
select_route,
{"order_lookup": "order_lookup", "refund_draft": "refund_draft", "smalltalk": "smalltalk"},
)
.add_edge("order_lookup", END)
.add_edge("refund_draft", END)
.add_edge("smalltalk", END)
.compile()
)// Java 没有 LangGraph,这里用 JDK 17+ 的惯用法手写同一张图:
// 节点是一个函数,条件边就是「一次查表」。依赖:JDK 17+,无第三方库
enum Route { ORDER_LOOKUP, REFUND_DRAFT, SMALLTALK }
// EnumMap 的键空间就是枚举本身,配合下面的自检,漏配一个分支起不来,而不是跑到一半才崩
static final Map<Route, UnaryOperator<AgentState>> AGENTS = new EnumMap<>(Map.of(
Route.ORDER_LOOKUP, Graph::orderLookup,
Route.REFUND_DRAFT, Graph::refundDraft,
Route.SMALLTALK, Graph::smalltalk));
static {
for (Route r : Route.values())
if (!AGENTS.containsKey(r)) throw new IllegalStateException("路由 " + r + " 没有对应的子 Agent");
}
static AgentState run(AgentState input) {
AgentState routed = supervisor(input); // 只判断交给谁,不回答问题
return AGENTS.get(routed.route()).apply(routed); // 这一次查表就是条件边
}// Swift 也没有 LangGraph。这里用 enum + switch 手写同一张图:
// switch 对 enum 是穷尽的,漏一个分支**编译不过**——这是 Swift 版条件边最大的好处
enum Route: String {
case orderLookup = "order_lookup"
case refundDraft = "refund_draft"
case smalltalk
}
func nextAgent(for route: Route) -> (AgentState) async throws -> AgentState {
switch route {
case .orderLookup: return orderLookup
case .refundDraft: return refundDraft
case .smalltalk: return smalltalk
}
}
func run(_ input: AgentState) async throws -> AgentState {
let routed = try await supervisor(input) // 只判断交给谁,不回答问题
return try await nextAgent(for: routed.route)(routed)
}四份代码教的是同一件事:把「下一步去哪」从代码里的写死顺序,变成一次运行时查表。 到这里机械原理其实已经讲完了,剩下的全是那个真正难的问题——decide 里面该怎么写。让模型直接说一句「我觉得该找查订单的同事」,然后你去解析这句话,行不行?
面试题库
Supervisor 模式里的路由决策一般怎么实现?请说说这个节点该做什么、不该做什么。How is the routing decision usually implemented in a supervisor pattern? What should that node do, and what should it not do?
国内高频海外高频基础#multi-agent#routing#langgraph🔒 解锁本章后查看答题要点。
为什么要让模型输出 structured output 而不是自然语言来做路由?自然语言到底差在哪?Why use structured output rather than natural language for routing? What exactly goes wrong with free text?
国内高频海外高频进阶#structured-output#routing#reliability🔒 解锁本章后查看答题要点。
路由不确定或者路由错误时,系统应该怎么兜底?阈值该怎么定?How should the system handle an uncertain or wrong routing decision, and how do you pick the threshold?
国内高频海外高频深入#routing#fallback#reliability🔒 解锁本章后查看答题要点。
routingReason 这类调试信息在生产系统里有什么价值?只是打日志而已吗?What is a field like routingReason actually worth in production? Is it just logging?
国内高频海外高频进阶#observability#routing#debugging🔒 解锁本章后查看答题要点。
