Rain9Rain9
首页
AI 岗位
AI 目录
前端
后端
桌面端
WebGL
Web3
  • 算法与面试
  • 面试八股
  • Vim 练级
  • Github
  • 掘金
  • 公众号《与 IT 有约》
首页
AI 岗位
AI 目录
前端
后端
桌面端
WebGL
Web3
  • 算法与面试
  • 面试八股
  • Vim 练级
  • Github
  • 掘金
  • 公众号《与 IT 有约》
  • 2026 · AI 时代

    • 程序员的出路:AI 时代的价值思考
    • 从零开始构建智能体(Hello-Agents 课程通俗笔记)

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 只做一类事,并以结构化产出为边界

为了让系统“稳定而可扩展”,要给多智能体系统加三条工程约束:

  1. 所有 Agent 之间交互必须走结构化协议(JSON Schema / Zod),禁止“自由发挥传话”
  2. 所有中间步骤都可追踪(可存储/可回放/可重试),而不是只存最终文本
  3. 每个 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 系统工程化的关键

多智能体一旦落地,就会产生两个“必答题”:

  1. 共享上下文怎么设计,才能既可追踪又不爆 Token?
  2. 任务状态怎么管理,才能支持失败重试与断点续跑?

推荐采用“强结构化上下文 + 弱文本上下文”组合:

  • 强结构化上下文(写入 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 为中心的状态机,比“自由对话式”更稳:

  1. ROUTED:Router 生成 plan
  2. EXECUTING:Supervisor 按 tasks 执行(可并行)
  3. REVIEWING:Reviewer 审阅与决策(通过/重跑/降级)
  4. FINALIZING:Writer 汇总产出(文本 + 图表元数据)
  5. 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 的能力才能稳定叠加上去。

最近更新: 2026/10/31 10:01