多 Agent 团队编排系统的设计与实测：agent-workflow

多 Agent 团队编排系统的设计与实测：调度、评审链与上下文经济

一个"调度—编码—评审"三岗协作的 LLM 编排系统：评审不通过自动退回重试，交付物经纯代码核验后才算完成。岗位记忆隔离在同批任务实测中节省 95.5% 的 prompt token。

背景与动机

让 LLM 独立承担编码任务时，"假完成"是高频故障：模型声明任务完成，但文件并未生成，或代码未经运行验证。单人单会话的结构存在三个固有缺陷：

本文介绍我近期完成的一个多 Agent 团队编排系统（仓库见文末），目标是把"分工"和"验收"做成系统能力，而不是依赖单模型的自觉。

系统架构

系统由三个岗位组成，各岗位绑定独立的 prompt 文件与记忆空间：

执行流程：需求进入 → 调度岗拆解为任务表 → 编码岗执行 → 评审岗实测 → 不通过则退回编码岗、计数加一 → 通过后经交付核验（纯代码检查声明文件的存在性）→ 完成。退回次数上限由调度代码兜底，超限判失败并完整打印现场。

系统提供终端与 Web 双入口（FastAPI + SSE 事件流），浏览器内总览流程图随执行逐节点点亮，轨迹图按时间生长、退回路径绘制为带编号的回边；每次运行结束自动结算本轮 token 消耗。

关键机制设计

星型调度：调度权在代码，不在模型

岗位间的协作通过信号 [请求协作:岗位key] 发起，由代码解析并派发，转派限一层。相比模型自由互调的链式结构：

• 转派由确定性代码执行，命中率不受模型输出格式漂移影响；
• 从机制上杜绝调用链自发扩散，避免上下文成本失控。

模型负责判断，代码负责路由。

任务表契约：管理岗的产出同样受约束

调度岗必须输出结构化任务表（任务编号、执行岗位、评审对象、依赖关系），由纯代码解析校验：编号必须连续、每个产出型任务必须绑定评审任务。问候、纯问答等无需拆解的输入走直接回复通道，不硬拆任务。

设计意图：系统里不存在"特权角色"，调度者的产出和管理执行者一样受合同约束。

评审链闭环与交付核验

评审岗的结论只代表"实测运行未报错"。系统在此基础上叠加第二道闸——交付核验：编码岗声明的文件清单由纯代码逐项检查存在性（含路径归一化，声明带前缀的相对路径亦正确判验）。声称生成而未生成，判失败。

原则：凡是能写成确定性代码的判断，不交给模型。

岗位记忆隔离与上下文经济

每个岗位的记忆按（工程，岗位）双键隔离；工具调用的中间消息执行后沉淀丢弃，仅结论进入历史；历史按滑动窗口裁剪。

实验数据

同批任务对照实验（3 个需求 × 双岗位，同模型同工具，唯一变量为记忆架构）：

补充对照：同批任务不带工具调用时，两种架构差距仅为 1.40×。说明上下文经济的主要收益来自工具循环——工具消息在共享会话中逐轮回灌，其体积被记忆架构差异放大。工具调用越密集，岗位记忆隔离的收益越大。

工程实践与踩坑记录

解析器的全半角兼容。 用户以中文全角括号输入协作信号（【请求协作:tester】，全角冒号），解析失败。修复：所有面向模型自由输出的正则解析统一全半角一视同仁。对自由输出的解析，宽容度即健壮性。

分类判据的结构性表述。 需求"做个自我介绍，网页版"曾被调度岗判为闲聊走直接回复通道——提示词示例中"自我介绍"一词与"让 Agent 自我介绍"撞词。修复后判据改为结构性特征：凡要求产出交付物的需求一律拆解，与关键词解耦。

截断的感知与恢复。 编码岗工具循环中两次出现 completion 精确等于 max_tokens（4096）的截断：输出被掐断、工具参数 JSON 残缺、解析失败被静默吞掉后以空参数空跑。修复分三层：截断感知（finish_reason == "length" 打标记）、工具轮数上限（超限回灌收尾提示，假完成由交付核验兜底）、参数解析失败按截断错误回灌；被掐断的关键调用同轮补发一次。

配置的显式化。 排查发现请求超时时间 30 秒全代码库无赋值点，实际生效值一直来自参数字段默认值，配置化改动无法生效。已改为显式模块常量并接入配置。

局限与路线图

当前版本定位为架构验证原型，局限如实列出：

• 每次运行为全新团队且工作区清零，跨运行的修改型需求（“在此基础上调整”）尚不支持——工作区与记忆的跨运行保留已列入路线图；
• 直接回复通道的输出无结构化兜底，偶发不符合预期的答复格式；
• 回归测试为 18 个打桩场景（零 API 消耗），覆盖调度、契约、评审链主路径，尚不含端到端压测。

已支持：Docker 单命令部署（镜像 273MB，运行时 7 个真实依赖）、终端与浏览器同一调度内核、每轮 token 账单结算。

总结

这套系统验证了三件事：

仓库地址：github.com/LiMuBai-QiuWuJi/agent-workflow，含完整文档、小白向上手指南与一次真实运行的交付示例，欢迎 Issue 交流。

如果这篇文章对你的多 Agent 实践有参考，欢迎转发交流。