先说我遇到的一个真实现场某个客服Agent上线不到一周用户大量反馈“我问发票怎么给我推荐商品”查trace才发现所有含“发票”的会话全部走进了售前节点。问题不在模型而在路由——当时只写了一个“让LLM输出一个词”的简易Router既不校验、也没兜底更没人记录决策依据。这件事之后我把LangGraph工程里最不被重视、却最影响大局的Router环节彻底重做了一遍也决定把这套经验完整写出来。这篇文章不讲概念直接按工程落地的顺序把Router的选型逻辑、状态设计、条件边实现、可靠性兜底、性能调优和真实深坑全部拆开讲明白。有一点先说清楚Route不是“用大模型选个分支”那么简单。LangGraph把Agent流程建模成节点加边的有向图Router就是图上的决策点。这个点分错了后面再好的工具、再强的模型都白搭。文章里我会用一个实际能跑通的客服工单分诊场景贯穿全程把代码、设计思路和排错链路都摆出来适合正在用LangGraph做正式项目的团队也适合刚接触LangGraph、想理解Router工程化边界的读者。1. Router在LangGraph里的真实定位决策点即架构1.1 为什么说Agent的能力上限由路由决定Agent本身做的事情其实是“把输入调度到正确的处理逻辑”。用户一句话进来系统需要判断这句话应该交给哪个工具、哪个子Agent、哪一段业务流程。这个判断动作就是Router。判断错了后续环节再精密也只会沿着错误方向越跑越远。拿快递分拣来类比最直观Router就是传送带上的那个岔口。包裹在岔口被拨错方向后面所有运输和投递流程都会跟着错而且越错越深。很多团队花大量时间调优某个业务节点的prompt却忽略了入口处那个看起来“很简单”的Router结果是业务节点做得再完美线上数据依然一塌糊涂。从LangGraph的实现视角看路径选择就是一条“条件边”conditional edge。条件边的函数接收当前状态返回一个字符串图根据这个字符串决定跳到哪里。所以Router的输入输出就是状态的变更和方向的选择它的工程质量会直接决定整条链路的稳定性和可调试性。我见过很多Agent项目最初只有一条线性链路跑着跑着需求变复杂才开始加入各种分支判断——这时候如果没有从一开始就按工程化方式设计Router重构成本会非常高。1.2 路由节点的职责边界只做决策不做业务这是我在实战里最想强调的一点Router节点应该只负责“决策”不负责“执行业务”。所谓业务指的是真正处理用户问题的那部分逻辑比如生成回复、调用API、写工单。Router的职责是分析当前状态算出“下一步该走哪条路”然后把这个决策结果放回状态里让条件边去跳转。这样说听起来很简单但实际项目里有个极常见的反模式Router函数里顺手把业务字段改了。比方说Router判断出用户意图是“售后”就直接把state[topic]改成了“售后”然后在后面的业务节点里topic被当作真实用户诉求来使用。看起来没什么问题可是当业务节点本身的处理逻辑依赖topic做更细的分类时这个字段已经被Router污染了业务节点拿到的就不是原始信息而是Router的“二手判断”。我之前提到的发票事故就是这个原因——Router把“售后”写进了topic售前节点又把topic当成用户意图自然就把“发票询问”导向了商品推荐。所以我的规矩是路由产生的所有信息一律放进router_meta这个专用字段里。业务字段保持“原始输入”语义路由字段单独存放。这样即使路由判断出错业务节点拿到的信息也是原始可追溯的排错时一眼就能看出问题出在哪个环节。还有一个工程细节值得提LangGraph条件边的目标节点可以是普通节点也可以是子图。当多个分支都需要走同一套“信息收集-确认-完成”流程时别把流程复制到每个分支里直接定义一个子图然后把路由目标指向子图入口。子图内部可以再做二次路由这样整个图结构不会因为分支增多而爆炸每个分支的可维护性也高得多。2. 三类常见Router的选型逻辑与工程取舍2.1 提示词Router原型期够用生产期别依赖最原始、也最常被采用的Router实现方式是提示词Router给LLM一段指令比如“你是路由助手只能输出一个词售后、售前、物流、人工”然后把LLM返回的文本拿去匹配条件边映射表。它的优点非常明显实现快、思路直观、任何自然语言模型都能跑用于Demo和原型验证效率极高。但它的缺点也足够致命。第一输出不稳定模型可能输出“售后。”、“售后\n\n用户想申请退款”甚至输出一段解释文字第二没有置信度你无法知道模型做这个判断时到底是笃定还是犹豫第三输出没有结构后续想做拦截、记录、归因分析非常困难。我见过不少团队在原型阶段用这套方案跑得很开心上线第一周就被真实流量打回原形——真实用户的话术远比测试集丰富稍微一模糊模型就开始“自由发挥”。如果你只是在本地跑通一个LangGraph Demo用提示词Router没问题。但只要你打算把Agent部署到正式环境建议直接跳过它做结构化方案不要在它上面投入任何调优时间。2.2 结构化输出Router生产环境的首选生产环境里我优先推荐结构化输出Router。核心做法是用Pydantic定义一个结果模型让LLM直接输出结构化的对象而不是纯文本。这样后续代码可以直接读取字段做校验和阈值判断。举一个具体的模型定义from typing import Literal from pydantic import BaseModel, Field class IntentResult(BaseModel): intent: Literal[售后, 售前, 物流, 人工, 闲聊] confidence: float Field(ge0, le1, description模型对意图判断的置信度) reason: str Field(description用一句话解释判断依据)定义好之后配合with_structured_output使用llm ChatOpenAI( modelroute-model-v2, base_urlhttp://llm-gateway.internal/v1, temperature0 ) result llm.with_structured_output(IntentResult).invoke(user_input)结构化输出的价值不在于“格式好看”而在于它把不可控的文本变成了可控的编程对象。你可以做三件之前做不到的事第一用confidence做低置信度拦截不确定时转人工第二把reason和intent一起记录下来方便后续分析判断逻辑第三模型输出的字段严格受Schema约束不存在“多出一个没注册的意图”这种问题。整套链路下来Router就从“碰运气”变成了“可观测、可拦截、可审计”。2.3 向量语义Router高频固定意图的低成本选择如果你的业务意图域非常固定比如客服场景里的“改地址”“查物流”“退款”而且希望路由延迟降到几十毫秒、成本趋近于零那就不需要用大模型做分类直接用向量语义Router更合适。做法也不复杂把每个意图准备若干条示例话术通过Embedding模型转换成向量存起来用户输入进来时同样转成向量和所有意图示例向量算余弦相似度取最高分对应的意图作为路由结果。如果所有相似度都很低说明命中不了任何已知意图就走默认兜底。下面这张表是我在实际项目里做技术选型时会参考的对比维度提示词Router结构化Router向量语义Router延迟高一次大模型调用中一次大模型结构化调用最低Embedding相似度计算成本大模型Token大模型TokenEmbedding调用成本极低灵活度高意图域可随时改高字段可扩展低新增意图需要准备新样本可解释性中高有意图与置信度低只有相似度分数输出稳定性低依赖模型发挥高受Schema校验高取决于样本质量适用阶段原型验证生产标配高频固定场景实际工程里这三种Router并不是互斥选项。我现在的项目里经常把它们组合成“分级路由”先向量粗分再结构化精判。这个放在后面的性能调优章节再详细展开。3. 一个可落地的客服路由Agent状态设计与条件边实现3.1 场景定义与状态字段拆分为了把Router的工程链路讲透我用一个具体的客服工单分诊Agent作为贯穿案例。假设用户输入是一句话Agent需要判断这句话应该进入售后工单、售前咨询、物流查询、人工客服还是闲聊。目标不是实现完整客服系统而是把路由环节完整跑通并且暴露足够的工程细节。先定义状态结构。这是整个LangGraph工程的地基定义不好后面所有节点都会跟着遭殃from typing import TypedDict class AgentState(TypedDict): user_input: str router_meta: dict final_answer: str可以看到我刻意把状态拆成了三个区域user_input原始用户输入业务节点需要时可以读取但它永远不会被Router改写。router_meta路由决策产生的所有元信息包括意图、置信度、理由、模型版本、耗时等。final_answer最终要返回给用户的回复内容。你可能会觉得“多拆一个字段很麻烦”但正是这一个小小的隔离动作能避免掉我在前面提到的“发票事故”一整类问题。路由字段和业务字段混在一起短期看省事长期看是给未来排错埋雷。3.2 条件边与路由函数完整实现接下来是完整的核心实现。先写路由节点它负责调用模型、解析结果、把决策信息写入router_metafrom langgraph.graph import StateGraph, START, END def intent_router_node(state: AgentState) - AgentState: llm ChatOpenAI( modelroute-model-v2, base_urlhttp://llm-gateway.internal/v1, temperature0 ) result llm.with_structured_output(IntentResult).invoke(state[user_input]) state[router_meta] { intent: result.intent, confidence: result.confidence, reason: result.reason, raw: result.model_dump(), } return state然后写路由函数它是条件边的核心决定“返回什么字符串”def route_by_intent(state: AgentState) - str: intent state[router_meta][intent] confidence state[router_meta][confidence] if confidence 0.6: return human return intent最后把它们装配成图builder StateGraph(AgentState) builder.add_node(intent_router, intent_router_node) builder.add_node(after_sales, after_sales_node) builder.add_node(pre_sales, pre_sales_node) builder.add_node(logistics, logistics_node) builder.add_node(human_handoff, human_handoff_node) builder.add_node(smalltalk, smalltalk_node) builder.add_node(fallback, fallback_node) builder.add_edge(START, intent_router) builder.add_conditional_edges( intent_router, route_by_intent, { 售后: after_sales, 售前: pre_sales, 物流: logistics, 人工: human_handoff, 闲聊: smalltalk, human: human_handoff, __default__: fallback, } ) builder.add_edge(after_sales, END) builder.add_edge(pre_sales, END) builder.add_edge(logistics, END) builder.add_edge(human_handoff, END) builder.add_edge(smalltalk, END) builder.add_edge(fallback, END) graph builder.compile()这段代码里有几个细节需要特别说明。第一条件边返回的字符串必须是映射表的key。如果route_by_intent返回了一个没有在映射表里注册的值比如“退款”而映射表里没有“退款”这个keyLangGraph在运行时就会抛KeyError。这是个很隐蔽的坑后面专门讲。第二我在映射表里同时注册了“人工”和“human”因为低置信度时route_by_intent返回的是human而正常意图识别结果里的“人工”中文会被直接返回。两个都注册才能保证无论走哪条路径都不会漏配。第三__default__是条件边的兜底分支。当返回值不在任何映射key里时会走到__default__指向的节点。它很重要但不能作为唯一的兜底防线因为本质上你还是依赖“返回了一个错误值”才触发它。更可靠的方案是让路由函数自己把返回值约束在白名单内这一点后面排错章节会详细说。3.3 为什么用条件边而不是节点内手动跳转经常有读者问既然intent_router_node里都已经拿到了意图为什么不直接在节点内部调用after_sales_node或其他节点函数而非要通过条件边跳转这个问题的答案是工程上的不是写法上的。LangGraph的图结构能做的事情远不止“按代码顺序执行”。它支持断点重放、时间旅行、并发分支、可视化调试这些能力全部依赖于“显式的边”。如果你在节点内部手动调用业务函数等于绕过了图引擎把控制流藏进了业务代码里。一旦线上出现问题你想在某个分支的中间位置暂停、修改状态、重新执行根本无从下手。使用显式条件边路由决策的结果清晰可见一个节点负责计算方向一条边负责跳转下一个节点只处理自己的业务。这种单一职责的拆分在Agent逻辑越来越复杂的今天不是“优雅”而是“保命”。我自己的习惯是Router节点里的代码量应该非常少最好只是一个“识别意图并写入状态”的壳子。如果这个节点里开始出现大量分支处理逻辑那一定是设计出了问题该考虑拆子图了。4. 路由结果不可靠怎么办兜底、重试与可观测性4.1 路由错误的三种类型与应对方向即使你用了结构化输出Router路由环节依然会出错。我把实际生产中遇到的路由错误归纳成三类方便你对照处理。第一类是格式性失误。模型输出“售后”或者“售后\n”甚至带有额外解释文字。这类问题最轻用结构化输出基本能解决万一底层模型网关返回异常再做一层字符串清理和类型判断也能兜住。第二类是语义性模糊。用户说“我说了不算bug你要怎么赔礼道歉”这到底是投诉、售后还是售前咨询人都不一定能分清模型更不可能稳定判断。这类问题没有绝对正确答案核心策略是识别出低置信度把这单转给人工而不是硬着头皮走某个业务分支。第三类是系统性超时。模型网关抖动、服务过载、网络问题导致路由节点没有返回结果。这个问题不在“判断对错”而在“有没有结果”。处理方式要围绕超时和重试来做。三种错误对应三套策略格式问题用结构化与校验语义问题用置信度阈值系统问题用超时控制与兜底链路。4.2 三层兜底链路与重试上限我给Router设计了一个三层兜底链路每一层解决不同的问题。第一层在路由函数内部把模型输出做归一化处理。字符串去空格、去换行、转意图别名比如把五花八门的表达映射到白名单意图集。同时做白名单校验一旦结果不在允许集合里直接强转“人工”。这层解决的是“模型输出了合法但不是预期值”的情况。第二层在条件边映射表注册__default__让任何未注册的返回值都走兜底节点。这层解决的是“路由函数有疏漏、有值漏配”的情况。兜底节点可以做成一个安全策略节点不做任何后续业务直接返回转人工话术。第三层在业务节点本身如果某个业务节点发现router_meta缺失或异常它不应该继续执行原有业务逻辑而应该返回安全话术或转人工。这层解决的是“上游节点提前崩溃或状态被外部覆盖”的情况。三层都做完Router才算有了基本的防御能力。重试方面有一条铁律路由入口的重试次数一定要严格控制。路由是链路第一跳它每多卡一秒整个用户的等待时间就被放大一秒。我给路由调用默认配置是timeout5、max_retries1超过就直接转人工。不要做无限重试也不要因为“这个请求很简单应该能成功”而放开超时限制。入口的鲁棒性永远比入口的准确率优先级更高。4.3 路由决策的完整记录位设计路由决策一定要记录这直接决定了你能不能对线上路由质量做闭环分析。我在router_meta里固定记录四类信息决策信息意图、置信度、判断理由。模型信息使用的模型版本、提示词版本或Schema版本。性能信息从发起调用到拿到结果花了多少毫秒。原始信息模型未经过任何处理的完整返回内容。这样设计的理由是后续做路由归因分析时你能回答四类关键问题。比如“上线新版提示词之后售后意图的命中率为什么掉了10个百分点”你只需要对比prompt_version和intent的分布变化就能看出来。“某些模糊表达一直在误判”你需要看raw和reason才能定位到具体是哪类话术带偏了模型。“最近系统变慢是不是路由拖了后腿”你需要latency_ms来验证。没有这些记录路由调优就只能靠猜。有了这些记录一次线上事故调优可能只需要十几分钟。可观测性做在路由环节比做在任何其他环节都值得。5. 性能调优从串行路由到并行分发5.1 路由延迟是整条链路的放大器很多Agent项目做性能优化时注意力都放在业务节点上却忘了用户请求的第一跳就是路由。如果路由做一次大模型调用需要1到2秒那整条链路不管后面多快用户感知到的延迟都已经加上这1到2秒了。所以在做延迟预算时我通常会单独给路由划一块时间。举个例子如果目标是接口P95延迟小于3秒路由这段我一般只给它500毫秒以内的预算。超出这个预算就要考虑换更快的模型、做缓存、或者用向量语义Router替代大模型分类。这不是苛刻是因为路由之后往往还有好几层业务节点要用大模型你不可能把时间全部预留在最前面。5.2 并行扇出一次入口同时做多路判断有些场景下路由不只是要做意图判断还想同时做情绪识别、实体抽取、语种检测。如果串行处理一次判断结束再做下一次延迟就是线性叠加的。LangGraph支持多个节点之间的并行分发你可以从入口节点同时连到多个分析节点等它们都返回后再进入汇聚节点统一处理。这种并行扇出能显著降低整体延迟但不是没有代价。每个并行分支都会产生一次模型调用都会写入状态最后汇聚时还要处理字段合并和冲突。我的建议是如果另外几个分析结果在后续节点里根本用不上就别并行只有当多个分析结果都是后续链路必需输入时并行才有正收益。在实际的客服场景里我见过一个很好的实践入口节点同时跑“意图识别”和“紧急程度判断”两个轻量任务等两个结果都出来后再决定走普通售后节点还是紧急应对节点。这样既没有牺牲整体延迟又避免了“紧急用户被普通流程耽误”的问题。5.3 分级路由粗分快判困难样本精判性能优化里性价比最高的一招是分级路由。思路很简单先用便宜的、低延迟的模型做粗分粗分结果置信度高就直接走对应分支粗分结果模糊再升级到大模型精判。具体落地时我通常用向量语义Router做第一级粗分计算用户输入和所有意图示例的相似度。如果最高相似度大于0.85直接采用该意图整个过程只需一次Embedding计算延迟很低成本几乎为零。如果最高相似度介于0.6到0.85之间说明表达比较模糊进入第二级用结构化LLM Router做精判。如果最高相似度低于0.6说明完全命中不了已知意图直接转人工避免浪费大模型调用。这套方案上线后大概能覆盖60%到70%的简单请求在粗分阶段快速返回只有模糊样本才需要消耗更大模型的Token。整体路由延迟的中位数下降非常明显同时模型成本也控制住了。工程里永远不要追求“所有请求都用最强模型处理”按难度分级才是长期可维护的架构。6. 我踩过的五个Router实战深坑与修复记录6.1 映射表不完整导致KeyError我踩的第一个坑是条件边映射表漏配导致线上直接报KeyError。当时路由函数返回了一个“退款”意图但映射表里只注册了“售后”“售前”“物流”LangGraph发现返回值没有对应key立刻抛异常整个请求直接失败。这个坑的麻烦之处在于开发和测试阶段很难触发。开发用的测试集覆盖不到“退款”这种边缘意图只有真实用户的表达多样性才能把它逼出来。修复方法有两个第一在映射表里把实际业务中可能碰到的意图域都注册上第二也是最有效的在路由函数里做白名单强制归一化allowed {售后, 售前, 物流, 人工, 闲聊} def normalize_intent(intent: str) - str: if intent in allowed: return intent return 人工现在我的所有路由函数都有这行白名单校验宁可多转到人工也不能让整个图因为一个未注册值直接崩溃。6.2 路由结果污染业务状态这就是文章开头那个发票案例的根因。当时Router判断出用户意图是售后就直接写进了state[topic]后续售前节点把topic当作用户真实诉求给出了“推荐商品”的答案。整个排查过程花了两个多小时最后在trace里看到topic被Router覆盖的那一刻真的很想骂人。修复方案前面已经说了所有路由决策统一放进router_meta业务字段保持原始输入语义。这个规矩我在团队里定成了代码评审的红线——凡是发现Router节点写业务字段的一律打回。别觉得这是小题大做线上这种坑踩一次就一定够长了。6.3 结构化输出偶尔仍是字符串你以为使用了with_structured_output就安全了但真实世界没那么理想。有一次底层模型网关出了异常返回了一个纯字符串而不是结构化对象结果在解析阶段直接抛异常路由节点崩溃。从那以后我给所有结构化输出都包了一层安全解析函数from typing import Optional def safe_parse_intent(raw) - Optional[IntentResult]: if isinstance(raw, IntentResult): return raw if isinstance(raw, dict): try: return IntentResult(**raw) except Exception: return None return None解析失败时的行为很明确放弃本次路由判断转人工。同时把异常信息写进router_meta方便事后定位为什么底层网关会返回异常格式。安全解包这个动作看似多余但它在关键时刻能避免一个全局崩溃。6.4 单轮输入误判率高有一段时间我发现一个诡异的现象单独测试每一轮对话都能正确分类但线上数据一统计误判率接近30%。后来排查发现问题出在输入上——我当时只传了用户最后一句话去做路由。客服场景经常会有“多轮才说清楚”的情况。用户先问“我有一个订单”再追问“发货了没”单独拿后面这句话去路由缺乏上下文几乎所有模型都会懵。修复方法是在路由前增加一个轻量的上下文摘要节点把最近几轮对话压缩成一段摘要和当前问题一起传给Router。这样一个轻微的成本增加换来的是意图判断准确率明显提升。要说清楚的是上下文摘要会增加一次小模型调用。但相比错误路由带来的后续无效链路消耗这笔开销通常划算得多。如果你做的场景里用户表达高度依赖上下文语境这个节点基本是必需的。6.5 超时默认值导致整链路卡死最后一个坑来自调用侧的默认配置。有一次内部模型网关配置的超时上限是120秒路由调用也没有额外设置超时参数结果一个简单的用户请求在路由节点整整卡了两分钟。用户早就走了Agent还在等模型返回。这个问题的本质是路由入口的鲁棒性比准确率更重要。我后来给所有路由调用统一加上了timeout5和max_retries1超时直接按转人工处理。不管后续业务节点有多复杂用户在入口处绝不能因为路由等待而失去耐心。路由快不一定是好事但路由卡死一定是灾难。