6.1 从单体 Agent 到多智能体架构 (Multi-Agent System)
本节目标:把当前 Demo 级别的“单体 Agent + 一次性 Prompt”演进为可扩展、可观测、可并行的多智能体协作系统,并且能在现有 NestJS + BullMQ + Redis + WebSocket/SSE 的技术栈里自然落地。
6.1.1 现状回顾:单体 Agent 的上限在哪里
以 ai-data-analyzer 为例,目前后端的分析入口集中在一个服务中完成(如 AnalysisService 的 analyzeData / analyzeText 一类方法)。这类单体设计的优势是简单、能快速跑通流程,但随着需求增长,会出现典型瓶颈:
- 上下文过载:数据、用户意图、工具调用、图表配置、解释文本全部塞进一次上下文,Token 成本和混乱度快速上升
- 角色混杂:同一个 Agent 既要“规划任务”,又要“写处理逻辑”,还要“校验结果”,很难稳定
- 可观测性不足:很难回答“这一步为什么这么做”“在哪里失败”“重试了几次”“哪一次输出被采用”
- 可复用性差:某些能力(清洗、聚合、图表、解释、异常检测)很难拆成可组合模块
- 并行做不到:例如“同时生成 3 个图表 + 同时做质量诊断”在单体里只能串行
因此,第一个真正从 Demo 走向工程化的改造点,就是把“一个大脑”拆成“多个可控的脑区”,并明确它们之间的协议。
6.1.2 架构目标:Supervisor/Worker + 明确协议 + 强可观测
推荐采用 Supervisor-Worker(主管理者 + 工作者) 的经典模式:
- Supervisor(主管理者):负责理解用户意图、拆解任务、调度 Worker、合并产出、兜底重试
- Workers(专业工人):每个 Worker 只做一类事,并以结构化产出为边界
为了让系统“稳定而可扩展”,要给多智能体系统加三条工程约束:
- 所有 Agent 之间交互必须走结构化协议(JSON Schema / Zod),禁止“自由发挥传话”
- 所有中间步骤都可追踪(可存储/可回放/可重试),而不是只存最终文本
- 每个 Worker 都有明确输入输出、失败语义、超时策略、最大步数
6.1.3 角色拆分:最小可用的 4 Agent 编制
从“能落地”出发,第一版就拆到 4 个角色即可(多了会先把工程复杂度拉爆):
A. Router Agent(路由与拆解)
职责:
- 从用户输入中提取:目标(Goal)、数据范围(Scope)、输出形态(Text / Charts / Tables)、约束(时序/维度/单位)
- 生成一个结构化的任务计划(Plan),每一步明确交给哪个 Worker
- 识别风险与缺失信息(列名不一致、单位不明确、时间格式异常)并生成澄清问题(可选)
输出(示例):
{
"goal": "分析销售趋势并找出异常月份",
"tasks": [
{ "id": "t1", "type": "data_profile", "inputs": { "focus": ["date", "amount"] } },
{ "id": "t2", "type": "compute_metrics", "inputs": { "metrics": ["MoM", "YoY"] } },
{ "id": "t3", "type": "chart_spec", "inputs": { "charts": ["line_sales", "bar_growth"] } },
{ "id": "t4", "type": "review", "inputs": { "checks": ["unit", "outlier", "chart_consistency"] } },
{ "id": "t5", "type": "final_report", "inputs": { "style": "bullet", "audience": "business" } }
]
}
B. Data Coder Agent(数据处理/计算)
职责:
- 把任务转成可执行的计算(优先工具调用,其次代码执行器,最后才是“口算”)
- 输出结构化结果:指标表、分组统计、异常点列表、字段映射等
注意:
- 第一版不需要真的“写 TypeScript 代码并跑”,先做到“输出结构化计算结果 + 可复核的计算过程”即可
- 到 6.2 章再把它升级为“写 Python/SQL 并执行”
C. Viz Agent(图表编排)
职责:
- 根据 Data Coder 的结构化结果,生成前端可消费的图表配置(例如 ECharts option)
- 强制要求图表来源数据可追溯(引用 resultKey / 数据表名 / 字段名)
输出(示例):
{
"charts": [
{
"id": "line_sales",
"library": "echarts",
"option": { "xAxis": { "type": "category" }, "yAxis": {}, "series": [{ "type": "line" }] },
"dataRef": { "resultKey": "monthly_sales_table" }
}
]
}
D. Reviewer Agent(审阅与守门)
职责:
- 校验链路:数据结果是否自洽、图表与数据是否匹配、单位/口径是否一致
- 失败时输出“可执行的修复指令”(回到 Supervisor 触发重跑某一步),而不是输出长篇解释
输出(示例):
{
"status": "fail",
"issues": [
{ "type": "chart_mismatch", "message": "line_sales 的 xAxis 使用 date,但数据表字段是 month", "fix": { "rerunTaskId": "t3" } }
]
}
6.1.4 状态机与共享上下文:把 Agent 系统工程化的关键
多智能体一旦落地,就会产生两个“必答题”:
- 共享上下文怎么设计,才能既可追踪又不爆 Token?
- 任务状态怎么管理,才能支持失败重试与断点续跑?
推荐采用“强结构化上下文 + 弱文本上下文”组合:
- 强结构化上下文(写入 Redis / DB):Plan、每一步的输入输出、工具调用参数、耗时、错误
- 弱文本上下文(只给模型看):每一步的摘要(Summary)+ 当前需要的局部数据片段
共享上下文最小数据结构
以 analysisId 为会话主键(可复用你现有的分析结果实体/JobId),定义一份可序列化的上下文:
type AgentRole = 'router' | 'data_coder' | 'viz' | 'reviewer' | 'writer';
type TaskStatus = 'pending' | 'running' | 'success' | 'failed' | 'skipped';
interface AgentTask {
id: string;
type: string;
status: TaskStatus;
inputs: Record<string, unknown>;
outputs?: Record<string, unknown>;
error?: { message: string; code?: string };
startedAt?: string;
finishedAt?: string;
tokens?: { input?: number; output?: number; total?: number };
}
interface AnalysisRunContext {
analysisId: string;
datasetId?: string;
userPrompt: string;
plan?: { goal: string; tasks: AgentTask[] };
artifacts: Record<string, unknown>;
summaries: Array<{ role: AgentRole; text: string; at: string }>;
}
其中:
artifacts用来存放“可以复用的产物”:清洗后的表、聚合后的表、图表 option、异常列表summaries用来控制 Token:每完成一个 task,就产出 3~8 行摘要供后续 Agent 使用
状态机(推荐)
以 Plan 为中心的状态机,比“自由对话式”更稳:
ROUTED:Router 生成 planEXECUTING:Supervisor 按 tasks 执行(可并行)REVIEWING:Reviewer 审阅与决策(通过/重跑/降级)FINALIZING:Writer 汇总产出(文本 + 图表元数据)DONE:写入最终结果,发送完成事件
6.1.5 在 NestJS + BullMQ 上落地:一步一步实现
这一节的“实现”指:把多 Agent 的骨架、协议与编排跑通;具体的“代码执行器/RAG/鉴权/计费”在 6.2~6.5 逐步叠加。
Step 1:抽象 Agent 接口(让换模型/换角色变简单)
目标:每个 Agent 都长一样,Supervisor 只需要按 role 调用。
建议接口:
interface Agent<Input, Output> {
role: string;
run(input: Input, context: AnalysisRunContext): Promise<Output>;
}
落点:
- 把 prompt 模板按 role 拆分(Router/Data/Viz/Reviewer),并统一走 Zod 验证
- 当前项目已经有
zod依赖,可用于“结构化输出 + 校验 + 失败重试”
Step 2:在 BullMQ 中引入“分析编排 Job”
目标:把“长链路、多步骤”放到 Worker 里跑,API 只负责接收请求与返回 JobId。
做法:
- 一个
analysis-orchestrator队列:负责按 plan 执行 tasks - 可选拆分:
analysis-data-worker、analysis-viz-worker,让不同步骤按资源隔离
Step 3:共享上下文存储(Redis 优先,DB 用于审计)
建议策略:
- Redis 存
AnalysisRunContext(短 TTL,例如 24 小时,用于实时进度与断点) - DB 存
AnalysisRun/AgentStep(长期保存,用于回放、审计、计费、复盘)
你当前项目已集成 Redis(用于 BullMQ 与 CacheManager),可以复用。
Step 4:实时进度推送(WebSocket 给状态,SSE 给文本)
建议分工:
- WebSocket:推结构化的 step 更新(task status、artifacts keys、错误)
- SSE:推“可读文本流”(例如 Writer 的报告逐字输出,或 Supervisor 的进度日志)
当你把每一步结构化记录下来后,前端就可以做出“任务看板式”的可视化,而不只是输出一段文字。
Step 5:失败语义与重试策略(工程化的稳定性来源)
分层重试:
- LLM 输出不符合 schema:同一步内部重试(最多 N 次)
- 计算/工具执行失败:重跑该 task(最多 N 次),必要时降级策略(例如跳过某个图表)
- Reviewer 判定失败:只重跑相关 task(按
rerunTaskId),不从头开始
必须设置:
maxSteps:防止死循环maxTokensBudget:防止无限烧钱timeoutMs:防止任务永久挂起
6.1.6 验收标准(做到这些就算“多智能体骨架跑通”)
当你完成本节改造后,应能满足以下验收点:
- 能生成结构化 Plan,并按 Plan 执行至少 3 类 Worker(计算、图表、审阅)
- 任何一步失败都能定位到 task,并能针对性重跑
- 每一步都有可回放记录(至少 Redis,最好 DB 也有审计)
- 前端能实时看到每一步状态变化(running/success/failed)与主要产物 key
做到这里,你的项目就从“会跑的 Demo”迈入“可持续演进的工程系统”,后续 6.2~6.5 的能力才能稳定叠加上去。
