编排系列收官篇。前两篇分别讲了多 Agent 编排的四种核心模式串行/并行/条件/竞争和 Agent 间的通信、状态共享与冲突解决。本篇从概念落地到真实代码以 Dream-SaaS 项目为例拆解 Supervisor Orchestrator 双层编排架构的设计思路与关键实现。一、开篇为什么需要两层编排单 Agent 应用通常不需要编排——一个 ChatClient 调一次 LLM拿到结果返回完事。但当系统里出现多个 Agent、多种工具、多种任务类型时谁先执行、走哪条路、结果怎么汇总就成了必须回答的问题。很多团队的第一反应是用一个 StateGraph 把所有逻辑塞进去路由、工具调用、安全检查、记忆管理、Provider 选择……节点越加越多边越连越密最终变成一个没人敢改的上帝图。Dream-SaaS 在实践中选择了双层编排外层 OrchestratorAgentOrchestratorService负责请求级编排——会话管理、PreLlm 规则链拦截、状态准备history/retrieval/provider、调用 Graph、结果提取、记忆维护。管的是一次对话的生命周期。内层 StateGraphdreamAgentGraph负责推理级编排——route 路由 → tools 工具执行/plan 计划生成 → synthesize 汇总回答。管的是一次推理内部的节点流转。两层的边界很清晰Client │ ▼ AgentOrchestratorService外层请求级编排 ├── 1. 会话ID Provider 选择 ├── 2. PreLlmRuleChain 规则链拦截第一层路由 ├── 3. 准备状态history / retrieval / provider ├── 4. 调用 dreamAgentGraph ──────────────────────┐ ├── 5. 提取 final answer tool outputs │ └── 6. 维护记忆 │ ▼ dreamAgentGraph内层推理级编排 START │ route ──┬── WITH_TOOLS ──→ tools ──┐ │ ├──→ synthesize → END └── PLAN_THEN_ANSWER → plan ┘外层管请求生命周期内层管推理流转。外层不关心 Graph 内部有几个节点、怎么走的条件边内层不关心会话记忆怎么存、Provider 怎么选。混淆两层的后果就是 Graph 膨胀成上帝对象——安全检查、记忆管理、Provider 路由全做成 Graph 节点图的拓扑复杂度指数级增长。这个划分不是拍脑袋决定的。外层的 PreLlm 规则链需要在 Graph 启动前拦截请求安全合规场景不能让请求进入推理流程记忆维护需要在 Graph 执行完后统一写入避免节点内部并发写记忆这些天然属于请求级关注点。而工具路由、计划生成、答案合成是推理级关注点它们需要共享 Graph 的 OverAllState、走条件边、可能循环——这些是 StateGraph 的强项。二、Supervisor 层三层路由的确定性梯度路由是编排的核心决策——这个请求该走哪条路。Dream-SaaS 没有把所有路由决策都交给 LLM而是设计了三层路由从快到慢、从确定性到不确定性依次执行。2.1 第一层PreLlmRuleChain 规则链——零延迟零成本的安全门规则链在 Graph 调用之前执行完全不调 LLM。它按Order排序遍历所有PreLlmRule实现任一规则判定拦截立即返回// PreLlmRuleChain.java — 按Order排序执行全部PreLlmRule public RuleEvaluationResult evaluate(PreLlmContext context) { if (!properties.isRulesBeforeLlm()) { return RuleEvaluationResult.allow(); } for (PreLlmRule rule : rules) { RuleEvaluationResult r rule.evaluate(context); if (!r.allowed()) { return r; // 任一规则拦截立即返回 } } return RuleEvaluationResult.allow(); }在AgentOrchestratorService.chat()中规则链的拦截结果直接返回给客户端不进入 Graph不调 LLMPreLlmContext preCtx new PreLlmContext(conversationId, userInput, provider); RuleEvaluationResult gate preLlmRuleChain.evaluate(preCtx); if (!gate.allowed()) { // 直接返回规则提示不进入Graph不调LLM return new AgentChatResponse(conversationId, provider, gate.userVisibleMessage(), List.of(strategy:preLlmBlocked: gate.reasonCode())); }设计哲学就一句话能不调 LLM 就不调。安全拦截、合规检查、高频简单意图——这些 100% 确定的场景用规则处理零延迟、零 Token 成本、零幻觉风险。如果一个请求包含违禁词规则链在毫秒级拦截并返回提示而不是花 3 秒钟让 LLM 生成一段我无法回答这个问题。2.2 第二层关键词启发式路由——needsTools 的 80% 场景通过了规则链的请求进入 Graph。Graph 的第一个节点是route它决定请求是走工具执行路径还是计划回答路径。这个决策同样不调 LLM而是用纯关键词匹配// AgentToolRunner.java — 纯关键词匹配 Override public boolean needsTools(String message) { String lower message.toLowerCase(Locale.ROOT); return lower.contains(时间) || lower.contains(date) || lower.contains(time) || lower.contains(天气) || lower.contains(工单) || lower.contains(ticket); }在 Graph 的 route 节点中使用graph.addNode(route, AsyncNodeAction.node_async(state - { String userInput state.value(AgentGraphKeys.USER_INPUT, ); String route toolRunner.needsTools(userInput) ? AgentGraphKeys.ROUTE_WITH_TOOLS : AgentGraphKeys.ROUTE_PLAN_THEN_ANSWER; return Map.of(AgentGraphKeys.ROUTE, route); }));查天气现在几点工单 TK-1024 什么状态——这些意图明确包含工具触发词关键词匹配的准确率足够高。不调 LLM 意味着省掉一次 2-5 秒的推理延迟和几千 Token 的成本。当然关键词匹配有盲区。帮我看看外面要不要带伞这种隐含天气查询的请求needsTools 会返回 false走 plan → synthesize 路径最终由 LLM 在 synthesize 环节理解意图。这不是 bug——关键词路由的目标是覆盖 80% 的高确定性场景剩下 20% 交给第三层。2.3 第三层LLM 语义路由——留给模糊场景前两层处理完剩下的请求进入 synthesize 节点由 LLM 理解用户意图并生成回答。这是三层中最慢、最贵但也最灵活的一层。值得注意的是Dream-SaaS 没有把路由判断本身做成一个 LLM 调用节点。很多编排框架喜欢加一个router节点让 LLM 输出{route: tools}这样的结构化 JSON 来决定走向。这种做法的问题在于路由判断本身需要一次 LLM 调用增加了延迟和成本而且 LLM 的路由输出不稳定可能返回格式错误的 JSON需要额外的解析和重试逻辑。Dream-SaaS 的做法是确定性的路由决策全部前置LLM 只在最终回答环节做语义理解。route 节点用关键词plan 节点用纯逻辑只有 synthesize 节点真正调用 LLM。这样一次对话最多只调一次 LLM工具路径下 tools 节点可能调外部 API 但不调 LLM延迟和成本都可控。2.4 UserHelpIntentRouter纯函数路由器的另一种实现除了通用对话 Graph 的 needsToolsDream-SaaS 还有一个UserHelpIntentRouter基于配置化的关键词短语匹配将用户问题路由到四个子图权限查询、账号问题、操作指南、通用聊天。它和 needsTools 的思路一致但粒度更细——不是要不要调工具的二元判断而是属于哪个领域的多元分类。配置化意味着新增意图类别不需要改代码只需要在配置文件中添加关键词短语。2.5 三层路由的本质是确定性梯度三层路由的本质是确定性梯度——越确定的决策越靠前越不确定的越靠后。规则链处理 100% 确定的安全/合规场景关键词处理 80% 确定的工具触发场景LLM 处理剩余需要语义理解的模糊场景。这不是过度设计而是成本和延迟的必然选择。很多人看到三层路由的第一反应是有必要这么复杂吗。算一笔账假设一次 LLM 调用平均 3 秒、消耗 2000 Token。如果规则链每天拦截 10% 的请求安全合规关键词路由每天覆盖 60% 的请求工具触发只有 30% 的请求需要 LLM 做语义理解——那么规则链和关键词每天省下的 LLM 调用量是 70%。这不是过度设计是真金白银的成本节约和用户体验提升。反过来看那些所有路由都交给 LLM的框架每次对话都要先让 LLM 判断意图再执行——延迟翻倍、成本翻倍而且路由结果还可能不稳定。三、Orchestrator 层StateGraph DAG 编排通过了规则链的请求进入内层 Graph。Dream-SaaS 的dreamAgentGraph拓扑非常精简START → route → [条件分支] ├─ WITH_TOOLS → tools → synthesize → END └─ PLAN_THEN_ANSWER → plan → synthesize → END3.1 Graph 拓扑条件边驱动的 DAG条件边是 Graph 的路由核心。addConditionalEdges根据 route 节点写入的 ROUTE 状态值决定下一个节点graph.addConditionalEdges( route, AsyncEdgeAction.edge_async( state - state.value(AgentGraphKeys.ROUTE, AgentGraphKeys.ROUTE_PLAN_THEN_ANSWER)), Map.of( AgentGraphKeys.ROUTE_WITH_TOOLS, tools, AgentGraphKeys.ROUTE_PLAN_THEN_ANSWER, plan)); graph.addEdge(tools, synthesize); graph.addEdge(plan, synthesize); graph.addEdge(synthesize, END);两条分支最终汇聚到synthesize节点。这是一个典型的 DAG有向无环图——没有循环每个节点只执行一次。循环场景如 critique-revise在领域专用 Graph 中实现通用对话 Graph 刻意保持无环降低调试复杂度。3.2 KeyStrategyFactory状态传递的契约StateGraph 的节点之间通过OverAllState传递数据。每个 state key 需要注册一个合并策略KeyStrategy决定当多个节点写同一个 key 时值如何合并。Dream-SaaS 的通用对话 Graph 中所有 key 都使用ReplaceStrategy——后写覆盖先写。这看起来简单但背后有明确的设计意图通用对话 Graph 的拓扑是 DAG不存在并行写同一 key 的场景tools 和 plan 是互斥分支所以不需要 AppendStrategy 或 MergeStrategy。ReplaceStrategy 语义最清晰每个节点写入的值就是最终值不存在合并带来的歧义。如果未来引入并行节点再为需要追加的 key如 toolOutputs切换策略。KeyStrategy 本质上是节点间的数据契约——它声明了这个 key 的值由谁写、怎么合并。和微服务中的 API 契约一样应该最小化、显式化、避免隐式约定。3.3 Plan 节点为什么不调 LLMplan 节点是 Dream-SaaS 编排设计中最反直觉的部分。它的名字叫plan但完全不调用 LLM而是通过AgentGraphPlanBuilder用纯逻辑生成结构化计划文本public static String buildPlanForDirectPath(String userInput, String retrievalSnippets) { boolean augmented hasSubstantiveRetrieval(retrievalSnippets); String kind augmented ? AgentGraphKeys.TASK_KIND_KNOWLEDGE : AgentGraphKeys.TASK_KIND_GENERAL; StringBuilder sb new StringBuilder(); sb.append(【任务类型】).append(kind).append(\n); sb.append(1) 先理解用户目标若问题含糊可先澄清再作答。\n); if (augmented) { sb.append(2) 下方「检索补充」含可参考材料事实与数字须与之对齐...\n); } else { sb.append(2) 当前无实质检索命中可结合常识与历史对话作答...\n); } // ... return sb.toString(); }它判断检索结果是否实质命中决定任务类型是知识问答还是通用对话然后按模板生成指令文本。这个文本会作为 synthesize 节点的 prompt 上下文引导 LLM 按正确的方式回答。Plan 节点不一定要调 LLM。很多编排框架把planning做成一个 LLM 调用节点让模型输出一个结构化的任务计划。但 Dream-SaaS 的实践表明当任务类型可以通过规则判断有没有检索结果、是不是多步问题用确定性逻辑生成计划模板更可靠——没有幻觉风险、没有额外延迟、没有额外 Token 消耗。LLM 应该用在真正需要语义理解的synthesize环节而不是机械地组装指令。这个设计还有一个好处可测试。纯函数的 PlanBuilder 可以写单元测试输入不同的 userInput 和 retrievalSnippets断言输出的计划文本包含正确的指令。LLM 驱动的 plan 节点几乎无法做确定性单元测试。3.4 synthesize 节点上下文组装的艺术synthesize 是 Graph 的最终节点也是唯一调用 LLM 的节点。它组装所有上下文——history、plan、retrieval、toolOutputs、userInput——然后调用 ChatClient 生成回答。上下文组装的顺序和格式直接影响 LLM 的回答质量。Dream-SaaS 的组装原则是System Prompt 在前定义角色和行为约束。Plan 指令紧随告诉 LLM 当前任务类型和回答策略。检索补充居中如果有 RAG 结果作为事实依据。工具结果其后如果走了工具路径附上工具返回数据。历史对话在后最近 N 轮对话记录。用户输入最后当前问题。这个顺序不是随意的——LLM 对 prompt 开头和结尾的内容更敏感 primacy 和 recency 效应。角色定义和任务类型放在最前面设定基调用户问题放在最后面确保不被忽略。工具路径下还有一个特殊处理如果工具返回空结果PlanBuilder 会调用buildPlanAfterTools()检测工具结果是否为空如果为空在 plan 文本中明确写入工具未返回有效数据请告知用户暂时无法获取该信息不要编造数据。这行指令能显著降低 LLM 基于工具被调用了这个信号编造数据的概率。假成功检测不能只靠输出端。编排系列中篇提到了 AgentOutputFailureDetector 在输出端检测异常内容但输入端的防护同样重要。空工具结果、降级提示、错误信息如果不做特殊处理就喂给 LLM模型可能基于不完整信息脑补出合理但错误的回答。输入端显式告知 LLM这个数据不可用比在输出端检测幻觉要可靠得多。四、领域专用 Graph 的两种模式通用对话 Graph 解决日常问答但 Dream-SaaS 还有两类需要特殊编排逻辑的领域场景。它们各自有独立的 Graph 实现。4.1 Human-in-the-Loop卖家入驻审核的 interruptBefore 模式卖家入驻审核流程需要人工审批——系统自动初审后在 review 节点暂停等待运营人员审核审核通过后继续执行后续步骤如签约、开通支付。Spring AI Alibaba Graph 通过interruptBefore支持这种模式。核心机制是三件套① RunnableConfig threadId 状态持久化RunnableConfig runConfig RunnableConfig.builder() .threadId(graphThreadId) .build(); OverAllState state sellerEnablementGraph.call(inputs, runConfig) .orElseThrow(() - new IllegalStateException(Graph 返回空状态));每次 Graph 调用携带一个threadIdGraph 的状态快照与 threadId 绑定。中断后状态被持久化不会因为 JVM 重启丢失前提是配置了持久化存储。② stateOf 检测中断点String nextNode sellerEnablementGraph.stateOf(runConfig) .map(StateSnapshot::next) .orElse(); boolean interrupted review.equalsIgnoreCase(nextNode);Graph 在 interruptBefore 指定的节点前暂停。通过stateOf查询当前状态快照的next字段可以判断流程是否停在了 review 节点。如果 next 是 review说明流程已暂停等待人工输入。③ updateState 注入人工决策恢复执行运营人员做出审核决定后调用resumeReview()方法通过updateState将审核结果注入 Graph 状态然后恢复执行// 伪代码注入人工决策后恢复 sellerEnablementGraph.updateState(runConfig, Map.of( reviewDecision, approved ? APPROVED : REJECTED, reviewComment, comment )); sellerEnablementGraph.call(resumeInputs, runConfig); // 从断点继续Human-in-the-Loop 不是加个审批。它需要状态持久化threadId、中断点检测stateOf、恢复机制updateState三件套缺一不可。很多团队以为 HITL 就是在流程中插一个审批节点但没有状态持久化审批人一刷新页面流程就丢了没有中断点检测不知道流程是在等待审批还是已经异常退出没有恢复机制审批结果无法回注到 Graph 中继续执行。此外SellerFlowOrchestratorService还有一个paymentMaxRetries参数取值范围 1-10限制支付环节的最大重试次数防止因支付网关临时故障导致无限重试。4.2 Critique-Revise 闭环内容生成的质量门控内容生成场景如商品描述、营销文案需要质量保证。Dream-SaaS 的EnhancedContentGraphConfig实现了 Critique-Revise 闭环draft → critique → qualityGate ├── PASS → merge → END └── REVISE → revise → critique循环关键设计条件属性开关通过ConditionalOnProperties控制enhanced-enabled开关关闭时退化为简单的 draft → END 流程便于灰度发布和回退。质量门控QualityGateNode读取 critique 的评审结果判断是否通过。不通过则路由到 revise 节点修订修订后重新进入 critique 评审。循环次数控制Graph 维护两个计数器——REVISION_COUNT修订总次数和GATE_RETRY_COUNT门控重试次数任一达到上限即跳出循环。这是必须的否则 critique 永远不满意Graph 会无限循环。并行分支与合并支持ParallelBranchNode并行生成多个版本通过MergeNode合并选优。并行节点使用独立的 state key 避免写冲突。FallbackStrategy 降级当闭环达到最大迭代次数仍未通过质量门控时执行降级策略——返回当前最佳版本并标记质量未达标而不是直接报错。ContentGraphMetrics 指标收集记录每次闭环的迭代次数、通过率、降级率用于监控内容质量和评估 prompt 效果。4.3 选型什么时候用哪种模式维度通用对话 GraphHITL GraphCritique-Revise Graph拓扑DAG无环DAG 中断点有环循环人工介入不需要必须审核节点不需要LLM 调用次数1 次0-多次多次critiquerevise延迟要求秒级分钟/小时级十秒级质量保障LLM 自检人工审核自动评审门控典型场景日常问答、工具调用入驻审核、合规审批文案生成、报告撰写选型原则很简单需要人做决策的用 HITL需要机器反复打磨质量的用 Critique-Revise一次性问答用通用 Graph。不要在通用对话 Graph 里加循环——那会让简单场景的延迟和成本不可控。五、状态管理请求生命周期外层 Orchestrator 的chat()方法是整个请求生命周期的编排入口。完整的 chat 流程public AgentChatResponse chat(AgentChatRequest request) { // 1. 准备会话ID和Provider String conversationId resolveConversationId(request); String provider clientSelector.normalizeProvider(request.provider()); // 2. PreLlm规则链拦截第一层路由 PreLlmContext preCtx new PreLlmContext(conversationId, request.userInput(), provider); RuleEvaluationResult gate preLlmRuleChain.evaluate(preCtx); if (!gate.allowed()) { return new AgentChatResponse(conversationId, provider, gate.userVisibleMessage(), List.of(strategy:preLlmBlocked: gate.reasonCode())); } // 3. 准备Graph输入状态 String history renderHistory(conversationId); MapString, Object inputs new HashMap(); inputs.put(AgentGraphKeys.CONVERSATION_ID, conversationId); inputs.put(AgentGraphKeys.USER_INPUT, request.userInput()); inputs.put(AgentGraphKeys.PROVIDER, provider); inputs.put(AgentGraphKeys.HISTORY_TEXT, history); inputs.put(AgentGraphKeys.RETRIEVAL_SNIPPETS, retrievalSnippetProvider.retrieve(preCtx).orElse()); // 4. 执行Graph OptionalOverAllState finished dreamAgentGraph.call(inputs); OverAllState state finished.orElseThrow(...); // 5. 提取结果 String answer state.value(AgentGraphKeys.FINAL_ANSWER, ); ListString executedTools extractExecutedTools(state); // 6. 维护记忆 appendMemory(conversationId, user, request.userInput()); appendMemory(conversationId, assistant, answer); return new AgentChatResponse(conversationId, provider, answer, executedTools); }记忆管理使用ConcurrentHashMapString, DequeString每个会话 ID 对应一个双端队列保留最近 12 轮MAX_TURNS12超出自动淘汰最早轮次。六、可观测性让黑盒变透明多 Agent 编排的可观测性比单 Agent 更难。Graph 内部的节点跳转对外部是黑盒——Controller 层只看到调用了dreamAgentGraph.call()返回了一个结果但中间 route 走了哪条路、tools 调了什么 API、synthesize 耗时多久全部不可见。6.1 为什么 Trace 必须在编排层捕获如果只在 Controller 层打日志看到的是10:00:01 POST /api/chat → 200 (3.2s)仅此而已。3.2 秒花在哪里route 判定用了多久tools 节点调用外部 API 耗时多少synthesize 调 LLM 用了几次完全不知道。Trace 必须在编排层捕获因为只有编排层知道 Graph 内部的节点流转。外层 Orchestrator 在chat()入口生成conversationId作为 traceId内层 Graph 通过OverAllState的 CONVERSATION_ID 传递这个 traceId每个节点在入口和出口记录耗时和状态。6.2 conversationId 作为 traceId 贯穿全链路// 外层生成traceId String conversationId resolveConversationId(request); // 写入Graph状态内层节点可读取 inputs.put(AgentGraphKeys.CONVERSATION_ID, conversationId); // 日志MDC MDC.put(traceId, conversationId);这样从 Controller → Orchestrator → Graph 节点 → 工具调用 → LLM 请求所有日志都可以通过同一个 traceId 串联。排查问题时用 conversationId 一搜整条链路的日志按时间线排列哪个节点慢、哪里报错一目了然。6.3 ToolTrace工具级调用记录各领域 Agent 有独立的 ToolTrace 实现SellerToolTrace、FulfillmentToolTrace、TicketMgmtToolTrace。它们记录每次工具调用的工具名称和输入参数调用开始/结束时间和耗时返回状态成功/失败/超时错误信息如有这些 Trace 数据与 conversationId 关联可以回溯这个回答用了哪些工具、工具返回了什么。6.4 WithAgentTrace AOP Span 树E1 模块E1 模块已交付 Prompt引入了WithAgentTrace注解和AgentTraceAspect切面自动为标注的方法创建 Span形成调用树chat() [3.2s] ├── PreLlmRuleChain.evaluate() [2ms] ├── retrievalSnippetProvider.retrieve() [180ms] └── dreamAgentGraph.call() [3.0s] ├── route [1ms] ├── tools [850ms] │ ├── WeatherAPI.call() [420ms] │ └── TicketAPI.query() [380ms] └── synthesize [2.1s] └── ChatClient.call() [2.0s]Span 树让耗时分析从猜变成看——synthesize 占了 65% 的时间主要是 LLM 推理tools 占了 27%外部 APIroute 和规则链几乎可以忽略。优化方向一目了然。6.5 跨层深链Graph 内部节点 → Orchestrator → Controller可观测性的最终目标是从一次用户请求能追溯到每一个内部步骤。Dream-SaaS 的跨层链路是Controller 层记录 HTTP 请求/响应、conversationId、总耗时。Orchestrator 层记录规则链拦截结果、检索命中情况、Graph 执行结果、记忆写入状态。Graph 层每个节点记录输入 state 摘要、输出 state 摘要、节点耗时。工具层ToolTrace 记录外部 API 调用详情。LLM 层记录 model、prompt tokens、completion tokens、调用耗时。所有层的日志通过 conversationId/traceId 串联。当用户反馈回答不对时可以完整复盘规则链是否放行了route 走了工具还是 plan工具返回了什么LLM 收到了什么 prompt、输出了什么这种级别的可观测性是多 Agent 系统在生产环境稳定运行的基础。七、结语编排架构的设计取舍三篇编排系列文章从四种模式到通信与冲突再到本篇的双层架构拆解覆盖了多 Agent 编排的核心议题。几个关键结论双层编排的核心是边界划分——外层管请求生命周期安全/记忆/检索/Provider 选择内层管推理流转节点路由/工具执行/答案合成。混淆两层会导致 Graph 膨胀成上帝对象维护成本指数级增长。路由决策遵循确定性梯度——规则链处理 100% 确定的场景关键词启发式覆盖 80% 的工具触发LLM 只在需要语义理解的模糊场景介入。越确定越靠前这是延迟和成本的必然选择不是过度设计。Plan 节点不一定要调 LLM——能用确定性逻辑生成的计划模板就不用 LLM。纯函数 PlanBuilder 可测试、无幻觉、零额外延迟。LLM 是稀缺资源应该用在真正需要语义理解的 synthesize 环节。Human-in-the-Loop 需要三件套——状态持久化threadId、中断点检测stateOf、恢复机制updateState缺一不可。加个审批节点不是 HITL只是一个需要人填的表单。可观测性必须在编排层建设——Graph 内部的节点跳转对 Controller 层是黑盒。conversationId 贯穿全链路 Span 树 ToolTrace让回答不对的排查从玄学变成工程。编排系列到此收官。但 Agent 工程化的挑战远未结束——当系统跑起来后下一个必须面对的问题是安全Prompt 注入、工具滥用、数据泄露、越权操作每一项都可能让精心构建的编排体系在攻击面前不堪一击。