多智能体路由：从场景定义到Agent解析的工程实践

大家好我是程序员小策。场景你正在做一个 AI 面试系统。产品经理说“我们不光要一个通用聊天机器人还要一个能自动出题、能给用户答案打分、还能分析用户表情神态的面试官。”你一拍脑袋行不就是多建几个 Agent 嘛每个 Agent 配一个不同的 Prompt 不就得了于是你噼里啪啦建了 5 个 Agent通用聊天官、出题官、答案评分官、神态分析官、提问官。然后在前端写了 5 个入口各自调用各自的路由。上线第一周一切顺利。第二周运营跑过来说能不能让用户在同一个会话里先跟通用聊天官聊两句然后无缝切到出题模式你愣了一下——哦对之前的架构里一个会话和一个 Agent 是硬绑定的中间没法换。更麻烦的是——后来老板说要加一个英文面试官你要改多少代码前端 5 个入口要变成 6 个后端每个 Controller 都加一个 switch case这就是我今天要聊的问题多智能体场景下怎么设计一个灵活、可扩展、对前端透明的 Agent 路由架构。项目来源https://github.com/lishuangqiang/AI-Meeting先看核心问题你面对的不是怎么调一个 Agent而是三个递进的工程问题如何定义场景与 Agent 的映射关系——谁来决定出题场景用哪个 Agent如何实现会话级别的 Agent 绑定——用户在这个会话里选了出题官下次发消息不能跳到评分官如何让这个映射关系的变更不炸代码——运营改了 Agent 配置不需要开发重新上线这三个问题如果你只用前端传 agentId后端直接用来回答那你很快就会踩坑。下面我们来拆解。核心概念Agent 场景路由Agent 场景路由将业务场景如面试出题与具体的智能体实例解耦通过配置层定义场景→Agent 的映射关系运行时根据场景标识 配置动态解析出目标 Agent同时对上层的 Controller 完全透明。说人话就是Controller 不关心用哪个 Agent它只告诉系统我是面试出题场景至于这个场景对应哪个 Agent、那个 Agent 的 API Key 是什么——这些由路由层搞定。打个比方这就像你去医院看病你去挂号窗口说我发烧了分诊台不会直接给你挂张三医生而是先判断科室——发烧挂内科骨折挂骨科。至于内科今天是张三坐诊还是李四坐诊你不关心分诊台根据排班表配置自动决定。如果你复查时还是这个病系统还会把你自动分回之前那个医生会话绑定。这个分诊台就是我们代码里的BusinessAgentResolver。代码实现从场景定义到 Agent 解析的完整链路来看真实代码。这是一个 AI 面试系统定义了 5 个业务场景publicenumBusinessAgentScene{GENERAL_AGENT_CHAT(general-agent-chat,通用智能体),INTERVIEW_QUESTION_EXTRACTION(interview-question-extraction,面试出题官,面试题出题官),INTERVIEW_ANSWER_EVALUATION(interview-answer-evaluation,用户答案评分官,面试答案评分官),INTERVIEW_DEMEANOR(interview-demeanor,神态分析官,神态评分面试官,表情分析面试官),INTERVIEW_QUESTION_ASKING(interview-question-asking,面试提问官);privatefinalStringcode;privatefinalStringdefaultAgentName;privatefinalListStringcandidateAgentNames;}看代码[BusinessAgentScene.java] 定义了 5 个业务场景每个场景有唯一 code、默认 Agent 名称、以及备选名称列表别名。注意看candidateAgentNames这个设计——每个场景除了一个默认名称还可以配多个别名。比如出题场景默认叫面试出题官但也匹配面试题出题官。为什么这么设计因为 Agent 的名称是由运营在后台配置的运营可能今天叫面试出题官明天改成了面试题出题官。如果你的代码里只认面试出题官这一个字符串运营改个名字你的系统就挂了。用候选名称列表同时匹配多个可能的名称让代码对运营操作更鲁棒。接下来看场景如何映射到具体的 Agent。映射关系不走硬编码走配置文件# application.ymlxunzhi-agent:agent-binding:general-agent-chat:通用聊天助手interview-question-extraction:面试出题官interview-answer-evaluation:面试答案评分官interview-demeanor:神态分析官interview-question-asking:面试提问官对应的配置类DataComponentConfigurationProperties(prefixxunzhi-agent.agent-binding)publicclassBusinessAgentBindingProperties{privateStringgeneralAgentChat;privateStringinterviewQuestionExtraction;privateStringinterviewAnswerEvaluation;privateStringinterviewDemeanor;privateStringinterviewQuestionAsking;publicStringresolveAgentName(BusinessAgentScenescene){if(scenenull){returnnull;}returnswitch(scene){caseGENERAL_AGENT_CHAT-generalAgentChat;caseINTERVIEW_QUESTION_EXTRACTION-interviewQuestionExtraction;caseINTERVIEW_ANSWER_EVALUATION-interviewAnswerEvaluation;caseINTERVIEW_DEMEANOR-interviewDemeanor;caseINTERVIEW_QUESTION_ASKING-interviewQuestionAsking;};}}看代码[BusinessAgentBindingProperties.java]ConfigurationProperties将 yml 配置映射到 Java 对象resolveAgentName()用 switch 表达式做场景→名称的映射。这里有个关键点虽然用了 switch但它开关的不是调哪个 Agent 的代码逻辑而是从配置中取哪个字符串名称。真正的 Agent 解析还在后面。核心解析器多级 Fallback 链ServiceRequiredArgsConstructorSlf4jpublicclassBusinessAgentResolver{privatefinalBusinessAgentBindingPropertiesbindingProperties;privatefinalAgentPropertiesLoaderagentPropertiesLoader;publicAgentPropertiesDOresolveRequired(BusinessAgentScenescene){SetStringcandidateAgentNamesnewLinkedHashSet();// 第一优先级配置文件指定的名称StringconfiguredAgentNamebindingProperties.resolveAgentName(scene);if(StrUtil.isNotBlank(configuredAgentName)){candidateAgentNames.add(configuredAgentName.trim());}// 第二优先级场景枚举自带的候选名称列表candidateAgentNames.addAll(scene.getCandidateAgentNames());// 按优先级依次查找for(StringcandidateAgentName:candidateAgentNames){AgentPropertiesDOagentPropertiesagentPropertiesLoader.getByAgentName(candidateAgentName);if(agentProperties!null){// 日志区分配置命中 vs Fallback 命中if(StrUtil.isNotBlank(configuredAgentName)!configuredAgentName.trim().equals(candidateAgentName)){log.warn(Configured agent not found, fallback matched scene{}, configuredName{}, matchedName{},scene.getCode(),configuredAgentName,candidateAgentName);}else{log.info(Resolved business agent scene{}, agentName{},scene.getCode(),candidateAgentName);}returnagentProperties;}}// 所有层级都找不到 → 明确报错log.error(No agent configuration found for scene{}, candidateNames{},scene.getCode(),candidateAgentNames);thrownewClientException(agent binding not found for scenescene.getCode(),InterviewErrorCodeEnum.AGENT_CONFIG_NOT_FOUND);}}看代码[BusinessAgentResolver.java]核心解析器实现多级 Fallback 链配置名 → 默认名 → 别名 → 报错。这个resolveRequired()方法的解析链路非常清晰yml 配置的名称 (最高优先级) ↓ 找不到 场景自带的默认名称 ↓ 找不到 场景自带的别名列表 ↓ 找不到 抛出 ClientException而不是返回 null 让上层 NPE为什么使用LinkedHashSet而不是List去重。如果运营在 yml 里配的名称和场景默认名称一模一样LinkedHashSet 自动去重但保留插入顺序优先级顺序确保不会重复查询数据库。会话层 Agent 绑定场景路由解决了新会话匹配哪个 Agent但同一个会话内的后续消息怎么办每次都重新解析不行——用户在会话里换了场景怎么办于是有了会话级别的 Agent 绑定——一旦会话创建时确定了 Agent后续消息自动沿用ServicepublicclassAgentResolver{privatefinalAgentConversationRepositoryagentConversationRepository;privatefinalAgentPropertiesLoaderagentPropertiesLoader;publicLongresolveAgentId(StringsessionId,LongrequestedAgentId){// 先查这个会话是否已经绑定了 AgentLongboundAgentIdfindBoundAgentId(sessionId);if(boundAgentId!null){// 已经绑定 → 直接返回绑定的 Agent忽略请求参数中的 agentIdif(requestedAgentId!null!requestedAgentId.equals(boundAgentId)){log.warn(Requested agentId {} overridden by session-bound agentId {},requestedAgentId,boundAgentId);}returnboundAgentId;}// 未绑定 → 使用请求参数中的 agentIdreturnrequestedAgentId;}publicLongfindBoundAgentId(StringsessionId){if(StrUtil.isBlank(sessionId)){returnnull;}returnagentConversationRepository.findBySessionIdAndDelFlag(sessionId,0).map(AgentConversation::getAgentId).orElse(null);}}看代码[AgentResolver.java] 会话级 Agent 解析器核心原则会话绑定优先于请求参数。这个设计的精妙之处在于对 Controller 完全透明。Controller 创建会话时调用BusinessAgentResolver后续发消息时调用AgentResolver——Controller 永远不需要知道具体用了哪个 Agent也永远不需要在前端传来传去 agentId。启动时预加载AgentPropertiesLoader每个 Agent 的 API Key、API Secret、工作流 ID 都存在数据库里agent_properties表。如果每次请求都去查库开销太大。这个系统用了启动时全量缓存的策略ComponentSlf4jRequiredArgsConstructorpublicclassAgentPropertiesLoaderimplementsCommandLineRunner{privatefinalAgentPropertiesServiceagentPropertiesService;privatefinalConcurrentHashMapLong,AgentPropertiesDOagentCacheByIdnewConcurrentHashMap();privatefinalConcurrentHashMapString,AgentPropertiesDOagentCacheByNamenewConcurrentHashMap();Overridepublicvoidrun(String...args){ListAgentPropertiesDOagentsagentPropertiesService.listActiveAgents();for(AgentPropertiesDOagent:agents){agentCacheById.put(agent.getId(),agent);agentCacheByName.put(agent.getAgentName(),agent);}log.info(Loaded {} agent properties into cache,agents.size());}publicAgentPropertiesDOgetByAgentId(LongagentId){returnagentCacheById.get(agentId);}publicAgentPropertiesDOgetByAgentName(StringagentName){returnagentCacheByName.get(agentName);}}看代码[AgentPropertiesLoader.java] 实现CommandLineRunner应用启动时一次性加载所有 Agent 配置到内存同时维护 ID 和 Name 两个索引。双索引设计byId byName让BusinessAgentResolver按名称查和AgentResolver按 ID 查都能 O(1) 命中。边界情况与陷阱陷阱一运营改了 Agent 名称缓存还是旧的。AgentPropertiesLoader只在启动时加载一次运行期如果运营在后台修改了 Agent 的名称或 API Key缓存不会自动刷新。解法提供一个refresh()方法供后台管理接口调用或者在更新 Agent 配置的接口里主动刷新缓存。当前这个系统的做法是重启生效——适合 Agent 变更频率低的场景。陷阱二场景找不到 Agent 时返回什么很多同学会写成return null然后上层代码agent.getId()直接 NPE线上排查到崩溃。这个项目的做法是直接抛ClientException带明确错误码。这样上层不用判空出了问题错误信息也一目了然AGENT_CONFIG_NOT_FOUND而不是NullPointerException at line 97。陷阱三会话绑定的 Agent 被删了怎么办如果一个会话正在进行中运营把对应的 Agent 删除了软删除del_flag1下一次消息请求时agentPropertiesLoader.getByAgentId()查不到会抛出Agent_NULL错误。解法在AgentPropertiesLoader中维护时可以只缓存del_flag0的记录但删除操作需要校验——如果 Agent 还有活跃会话提示运营先结束会话再删除。对比表格Agent 路由的几种方案方案核心思路优点缺点适用场景前端直传 agentId前端选择 Agent 后传 id 给后端实现最简单前端耦合重切换 Agent 要改前端代码只有 1-2 个 Agent 的原型项目后端 Switch-Case 硬编码Controller 里 if-else 判断场景调不同 Agent对前端透明每加一个场景要改 Controller 代码并重新上线Agent 数量和场景都不变的简单系统配置驱动 多级 Fallback本项目yml 配置 枚举定义 三级匹配链运营可配代码不改动别名机制防运营改名炸系统复杂度略高需要理解 Fallback 链多 Agent、运营频繁调整的中大型项目规则引擎Drools/表达式用规则引擎根据请求属性动态路由极度灵活可动态加规则学习成本高调试困难性能开销Agent 数量 50 的超大型系统一句话总结当你的 Agent 数量在 3-20 个之间且运营经常调整配置时配置驱动 多级 Fallback是最佳性价比方案。面试追问追问 1如果同一个用户的同一个会话里需要切换 Agent比如前 5 轮用通用聊天第 6 轮切到出题模式你的架构怎么支持→ 回答方向在AgentResolver.resolveAgentId()中当前逻辑是绑定优先于请求如果要支持切换可以引入Agent 升级逻辑——check 请求中的 agentId 是否合法不是任意 Agent而是允许切换的场景列表合法则更新会话绑定的 agentId。追问 2AgentPropertiesLoader 用 ConcurrentHashMap 满足需求吗如果 Agent 数量上万呢→ 回答方向当前场景 Agent 数量通常不超过 50ConcurrentHashMap 完全够用。如果上万水平考虑 Caffeine 或 Guava Cache 加过期策略。但更大的问题是——什么业务会有上万个 Agent可能需要反思 Agent 粒度的设计是否合理。追问 3BusinessAgentBindingProperties 用 Switch 表达式映射场景到配置如果场景扩展到 50 个怎么办→ 回答方向可以在 yml 里直接用 Map 结构agent-binding: { scene-code-1: agent-name-1, ... }然后用MapString, String接收动态 get。但当前 5 个场景用 Switch 的好处是编译期安全检查——yml 里拼错了一个 keyIDEA 里直接红线。总结多智能体路由的核心不是怎么调 Agent而是怎么让调用方不关心调的到底是哪个 Agent。读完这篇你应该能用枚举 配置文件定义业务场景到 Agent 的映射关系设计多级 Fallback 链让系统对运营操作更鲁棒实现会话级别的 Agent 绑定并知道在什么场景下需要支持切换在面试时说出配置驱动路由 LinkedHashSet 去重保序 启动预加载双索引缓存而不只是用 if-else 分一下