技术原理可视化方法论时序图在 Agent 协作流程中的实战运用一、深度引言与场景痛点技术文档里最让人头疼的部分不是代码而是那些用文字描述了半天但你依然看不明白的交互流程。比如下面这段话当用户发起请求后Orchestrator 首先将任务分解为子任务然后向 Search Agent 和 Analyze Agent 分别发送任务请求。Search Agent 完成搜索后将结果返回给 Orchestrator。Orchestrator 检查搜索结果的完整性如果不足重新发起搜索如果满足则将结果转发给 Report Agent 生成最终报告。这是很清晰的文字描述但读完你还是不知道到底有几个并发请求Search Agent 返回结果后Analyze Agent 是不是干等着如果搜索不足重试几次这些问题在文字里都可以一带而过但在时序图里每一个交互都会被精确地落在时间轴上。时序图Sequence Diagram是 UML 中专门用来表达谁在什么时候给谁发了什么消息的图表。它天生适合画 Agent 协作流程因为它能同时表达时序关系谁先谁后、并发关系谁和谁同时、条件分支什么情况下走哪条路、循环重试 N 次——这些恰好是 Agent 协作中最核心的信息。本文不重讲时序图的画法而是分享一个Agent 协作流程的五步可视化方法——从识别参与者到标注异常路径帮助你画出一张连产品经理都能看懂的 Agent 交互图。二、底层机制与原理深度剖析画好 Agent 协作时序图核心是掌握五要素flowchart TD A[Agent 协作五要素] A -- B1[参与者 Participants] A -- B2[生命线 Lifeline] A -- B3[消息 Messages] A -- B4[激活框 Activation] A -- B5[组合片段 Fragments] B1 -- C1[用户 / Agent / 外部服务] B2 -- C2[参与者从创建到销毁的时间线] B3 -- C3[同步/异步/返回] B4 -- C4[参与者处于活跃处理状态的时段] B5 -- C5[alt/opt/loop/par/break] C1 -- D{参与者识别} D -- E[外部: 用户、外部 API] D -- F[内部: Orchestrator, Worker Agent] D -- G[服务: 数据库、消息队列] C5 -- H{组合片段选择} H -- I[alt: 条件选择 if/else] H -- J[par: 并行执行] H -- K[loop: 循环/重试] H -- L[opt: 可选操作] H -- M[break: 异常中断]这五要素在 Agent 协作中的实际应用参与者用户、Orchestrator、Search Agent、Analyze Agent、Report Agent、Redis、向量数据库、LLM API激活框最容易被忽略但最有用的元素——它告诉你每个 Agent 的工作时段有多长par 片段Agent 协作中最关键的组合片段——多个 Agent 同时工作用par显式标注并行关系alt 片段条件分支——如果搜索结果不足就重试否则继续三、生产级代码实现这里不是代码而是一张精心设计的 Agent 协作时序图外加多个典型 Agent 协作模式的可视化范式。3.1 完整 Agent 协作时序图sequenceDiagram actor User as 用户 participant Orch as Orchestrator participant Redis as Redis 缓存 participant Search as Search Agent participant Analyze as Analyze Agent participant Report as Report Agent participant LLM as LLM API User-Orch: 分析近一周的用户反馈趋势 activate Orch Orch-Orch: 拆解任务: 搜索 分析 报告 par 并行阶段 1: 独立子任务 Orch-Search: 搜索用户反馈 activate Search Search-Redis: 检查缓存 Redis--Search: miss Search-Search: 向量检索 Search--Orch: 返回 15 条反馈数据 deactivate Search and Orch-Analyze: 分析趋势指标 activate Analyze Analyze--Orch: 返回趋势分析模板 deactivate Analyze end alt 搜索结果不足 Orch-Search: 补充搜索改用关键词 activate Search Search--Orch: 追加 8 条数据 deactivate Search end Orch-Analyze: 分析反馈数据传入搜索结果 activate Analyze Analyze-LLM: 请求趋势分析 LLM--Analyze: 返回分析结论 Analyze--Orch: 返回结构化分析结果 deactivate Analyze Orch-Report: 生成报告传入分析结果 activate Report Report-LLM: 请求生成 Markdown 报告 LLM--Report: 返回报告内容 Report--Orch: 返回完整报告 deactivate Report Orch-Redis: 缓存最终结果 Orch--User: 返回趋势分析报告 deactivate Orch3.2 四种典型 Agent 协作模式模式 1并行扇出Fan-out ParallelsequenceDiagram participant Orch as Orchestrator participant A1 as Worker 1 participant A2 as Worker 2 participant A3 as Worker 3 Orch-Orch: 将任务拆分为 3 个独立子任务 par 并行执行 Orch-A1: 子任务 1 A1---Orch: 结果 1 and Orch-A2: 子任务 2 A2---Orch: 结果 2 and Orch-A3: 子任务 3 A3---Orch: 结果 3 end Orch-Orch: 聚合 3 个结果模式 2管道串联Pipeline SequentialsequenceDiagram participant Orch as Orchestrator participant W1 as Stage 1 participant W2 as Stage 2 participant W3 as Stage 3 Orch-W1: 原始输入 W1---Orch: 阶段 1 结果 Orch-W2: 阶段 1 结果 W2---Orch: 阶段 2 结果 Orch-W3: 阶段 2 结果 W3---Orch: 最终输出模式 3重试循环Retry LoopsequenceDiagram participant Orch as Orchestrator participant W as Worker Orch-W: 执行任务 loop 最多重试 3 次 alt 任务失败 W--Orch: 失败 错误信息 Orch-Orch: 等待退避延迟 Orch-W: 重试任务 else 任务成功 W--Orch: 成功 结果 end end break 超过最大重试次数 Orch--Orch: 记录失败通知用户 end deactivate W模式 4基于条件的动态路由Conditional RoutingsequenceDiagram actor User as 用户 participant Orch as Orchestrator participant Simple as 简易 Agent participant Complex as 复杂 Agent User-Orch: 发起查询 alt 简单问题 Orch-Simple: 直接回答 Simple---Orch: 回答 else 复杂问题需要多步推理 Orch-Complex: 深度分析 Complex-Complex: 步骤 1: 检索 Complex-Complex: 步骤 2: 分析 Complex-Complex: 步骤 3: 验证 Complex---Orch: 结构化回答 end Orch--User: 返回最终答案四、边界分析与架构权衡1. 时序图的信息密度问题一张时序图如果包含超过 6 个参与者和 20 条消息阅读体验就会急剧下降。解决方法是分层画图先画一张概览图只包含核心参与者和高层次的交互然后为每个复杂环节单独画详图。比如上文的主图展示了完整的 Agent 交互而四个模式图分别聚焦于特定的协作模式。2. 激活框的误用激活框activate/deactivate的意义在于显示一个参与者正在做事的时间段。但在异步系统中参与者发完消息后可能并没有闲着——它可能在处理其他请求。这时激活框应该只覆盖与该交互相关的处理时段而不是参与者的整个生命周期。3. 何时用状态图何时用时序图需要展示一个 Agent 内部的状态变化 → 用状态图State Diagram需要展示多个 Agent 之间的消息交换 → 用时序图Sequence Diagram需要展示数据和控制的流动方向 → 用流程图Flowchart4. 时序图无法表达的资源约束和排队时序图默认所有消息传输都是即时的但在真实系统中消息可能在队列中排队、请求可能因为连接池耗尽而等待。这些非功能性的约束在时序图里无法直接表示需要通过注释Note或独立的容量规划图来补充。五、总结画好 Agent 协作时序图的核心理念是用图的精确性弥补文字的模糊性。五个实用技巧从参与者入手先把所有参与交互的角色列出来这是画图的第一步par 是你的好朋友Agent 协作中并行执行是常态用 par 标注出来能让性能瓶颈一目了然激活框不能省它能让读者看出每个 Agent 的忙碌时段帮助识别串行瓶颈复杂流程分层画总览图 细节图而不是把 50 条消息塞进一张图模式和变体单独抽象把可复用的协作模式如重试循环抽象出来减少重复绘图工作Mermaid 语法参考sequenceDiagram、participant、actor、activate/deactivate、par/and/end、alt/else/end、loop/end、break/end、Note over。下一篇是本系列 0707 的收官之作——Agent 任务调度引擎DAG 图驱动 vs LLM 动态决策到底该选哪一个。