实现 Multi-Agent 和 SubAgent 并发,让 Agent 团队跑得飞起
大家好,我是二哥呀。
前四期我们给 PaiCLI 实现了 ReAct 循环、Plan-and-Execute、上下文管理和 RAG。
但如果把一个跨多个模块的大任务交给同一个 Agent 从头做到尾,很容易遇到两个问题。
第一个问题是职责乱。同一个模型既要拆解计划,又要根据工具的报错信息去修改代码,很容易在规划阶段就陷入某个细节不能自拔,导致 Plan 考虑不全面,前后步骤也对不上。
第二个问题是自己检查自己写的代码,标准容易主观。模型按自己的思路写完一段逻辑,紧接着在同一个上下文里检查这段逻辑有没有漏洞,它往往会沿用刚才的假设,把只完成了一半、或者缺少边界校验的结果判定为合格的。
解决这两个问题的常见做法是拆分角色,引入主从结构的 Multi-Agent 协作。
把原来什么都做的单个 Agent 拆分成规划者(Planner)、执行者(Worker)和检查者(Reviewer)三个子 Agent(Sub-agent),由编排器统一调度。
规划者不调用工具,只负责把任务拆分成带依赖关系的步骤;多个执行者从 Worker 池中领取步骤并行执行;检查者在一个不带历史对话的独立上下文里逐个验收步骤,不合格就退回重做。

这一期我们对照 PaiCLI 的最新源码,把这套 Multi-Agent 与 Sub-agent 并发协作的机制从头到尾讲清楚:
- 为什么选择主从编排架构,三类角色和七种消息类型怎么配合;
- 怎么隔离 Sub-agent 的工具权限,怎么按内容的变化频率组装各角色的提示词;
- 规划阶段怎么去掉 JSON 外层的代码块标记,怎么用拓扑排序拦截未知依赖和循环依赖;
- 执行阶段怎么用阻塞队列管理一组 Worker 并行执行,怎么用各自独立的内存缓冲区防止终端输出混在一起;
- Worker 之间怎么传递上下文和已授权的网址,Reviewer 怎么按默认拒绝(Fail-Closed)策略审查,以及审查不通过时怎么带着反馈重试。
01、为什么需要主从架构
目前主流的 Multi-Agent 协作方式大致分为两种。
一种是微软 AutoGen(57.3K Star)采用的对等对话方式,多个 Agent 围绕同一个议题互相发消息、协商结论,适合开放式的讨论。另一种是 CrewAI(49.5K Star)采用的主从委派方式,先明确每个角色的职责范围,再按固定流程分发任务、验收结果。

如果让终端里的多个子 Agent 两两之间自由对话,它们之间的调用关系很容易变成网状结构,既无法预估总共要进行多少轮对话、消耗多少 Token,出现死循环时也很难排查。
PaiCLI 选择了主从架构(Orchestrator-SubAgent)。编排器 AgentOrchestrator 是唯一的调度中心,每个 SubAgent 只和编排器交互。子 Agent 之间不直接通信,任务下发、结果收集、审查退回以及把上游结果传给下游,都由编排器统一处理。

在这个主从结构下,AgentRole 枚举定义了三类角色。
PLANNER(规划者):接收用户的原始需求,把需求拆解为带类型和依赖关系的步骤;只输出结构化的计划,不执行任何具体操作WORKER(执行者):接收单个步骤的描述以及前置步骤的结果,调用文件读写、代码检索和终端命令等工具完成这个步骤,再按约定格式汇报完成情况REVIEWER(检查者):对照步骤的原始要求,独立验收执行者提交的结果;验收通过后,依赖这个步骤的下游才能执行,验收不通过则列出具体问题,退回给执行者重做
// src/main/java/com/paicli/agent/AgentRole.java
public enum AgentRole {
PLANNER("规划者", "负责分析用户任务,制定执行计划,将复杂任务拆解为可执行的子任务"),
WORKER("执行者", "负责执行具体任务步骤,调用工具完成文件操作、命令执行等操作"),
REVIEWER("检查者", "负责检查执行结果的质量和正确性,提供改进建议");
}
编排器和三类子 Agent 之间传递的消息对象是 AgentMessage,它用 Java 17 的 record 定义,包含发送方名称 fromAgent、发送方角色 fromRole、消息正文 content 和消息类型 type 四个字段。
// src/main/java/com/paicli/agent/AgentMessage.java
public record AgentMessage(
String fromAgent,
AgentRole fromRole,
String content,
Type type
) {
public enum Type {
TASK,
RESULT,
PARTIAL,
FEEDBACK,
APPROVAL,
REJECTION,
ERROR
}
}
这里的 Type 枚举覆盖了协作全流程中的七种消息类型。
TASK是编排器派发给子 Agent 的任务;RESULT是子 Agent 正常完成后的输出;PARTIAL表示执行者在 Token 预算或对话轮数用完时提前结束,只交回了部分结果;FEEDBACK、APPROVAL和REJECTION分别表示审查阶段的反馈、通过和不通过;ERROR表示模型调用失败、或者在不允许的情况下调用了工具等错误。

围绕这套主从结构,agent/ 包下的八个核心类分工如下。
AgentRole:定义规划者、执行者、检查者三类角色AgentMessage:编排器和子 Agent 之间传递的不可变消息对象,带有七种消息类型SubAgent:子 Agent 实例,各自维护角色提示词、对话历史和上下文压缩,共用同一个工具注册表和模型客户端AgentOrchestrator:编排器,按顺序完成规划、按 DAG 分批并发执行、审查重试和结果汇总TeamStructuredReply:按严格规则把三类角色的最终回复解析成 JSON,负责去掉外层的代码块标记,并拒绝重复的键和 JSON 后面多余的文字TeamPlanParser:校验规划者输出的 JSON 计划,负责给步骤重新编号、拦截未知依赖,并用 Kahn 拓扑排序检测循环依赖TeamWorkerReport:解析执行者的结构化交付报告,区分已完成(completed)和受阻(blocked)两种状态TeamReviewVerdict:解析检查者的审查结论,按默认拒绝原则判定是否通过,并按优先级提取退回原因
02、三类 Sub-agent
规划者、执行者和检查者虽然都是 SubAgent 类的实例,但它们能使用的工具和系统提示词是严格区分开的。
在 SubAgent.shouldUseTools 中,只有角色为 WORKER 的实例才会返回 true。
// src/main/java/com/paicli/agent/SubAgent.java
private boolean shouldUseTools() {
return role == AgentRole.WORKER;
}
SubAgent 向大模型发起请求时,会先根据 shouldUseTools() 判断请求里要不要带上工具定义。对于 PLANNER 和 REVIEWER,传给 llmClient.chat 的工具列表是 null。
如果允许规划者在制定计划时调用 read_file 或 execute_command,就会变成一边执行一边拆解,很难再从整体上安排步骤;同样,检查者如果能调用写文件工具,就可能直接修改执行者的代码,做不属于自己职责的事。此外,评测审计测试 TeamRequestAudit 也会检查,发给规划者和检查者的请求里,不能包含任何工具 Schema。
如果底层模型没有遵守约定,请求里明明没有提供工具,响应里却依然带有 tool_calls,或者在正文里留下了 <|DSML|function_calls> 这类没有被执行的工具调用标签,该怎么处理?
SubAgent 会在收到响应后进行检查。只要满足 !shouldUseTools() && response.hasToolCalls(),就立即结束本次调用,在终端打印“本角色不提供工具,工具调用未执行”,并返回 AgentMessage.error,让编排器按失败处理。对于正文里残留的工具调用标签,则先通过 llmClient.looksLikeUnexecutedToolCall 进行识别并提示用户,随后这段不符合格式的文本会被 JSON 解析器拒绝。
// src/main/java/com/paicli/agent/SubAgent.java
if (response.hasToolCalls() && !shouldUseTools()) {
streamRenderer.finish();
String reason = "本角色不提供工具,工具调用未执行";
conversationLedger.appendMessage("team", name, "llm_response", LlmClient.Message.assistant(
response.reasoningContent(), response.content(), response.toolCalls()));
out.println(AnsiStyle.subtle(reason));
return AgentMessage.error(name, role, reason);
}
划清工具权限之后,还要通过系统提示词约束每个角色的行为。
SubAgent.getSystemPrompt 没有把提示词硬编码在 Java 字符串里,而是先把当前角色对应到 PromptMode 中的 TEAM_PLANNER、TEAM_WORKER 或 TEAM_REVIEWER,再统一交给 PromptAssembler.assemble 组装。
// src/main/java/com/paicli/agent/SubAgent.java
private String getSystemPrompt() {
return promptAssembler.assemble(promptMode(), PromptContext.builder()
.projectMemoryContext(buildProjectMemoryContext())
.externalContext(buildExternalContext())
.skillIndex(shouldUseTools() ? buildSkillIndex() : "")
.toolsEnabled(shouldUseTools() && llmClient.supportsTools())
.build());
}
PromptAssembler 拼接提示词时,如果当前角色的 toolsEnabled 为 false,会先调用 stripToolSections,删掉基础提示词 base.md 里的 ## Tools 和 ## Tool Policy 两节,再补上一节 ## Tool Availability,告诉规划者“把需要读取文件、执行命令等操作写成计划步骤,交给执行者”,告诉检查者“根据收到的任务与执行结果进行审查,证据不足时在 issues 中说明”。
整份系统提示词按内容变化的频率从低到高依次排列。
- 最前面是整个会话期间都不变的内容:
base.md、性格设定calm.md、角色模式文件(team-planner.md/team-worker.md/team-reviewer.md)、审批规则、上下文管理说明和输出格式说明 - 其次是只提供给 Worker 的
## Skills索引,只有在启用或停用 Skill 时才会变化 - 系统提示词中的
## Project Context放 PAI.md 等文件里的项目规范。可用的 Skill 目录排在项目规范后面;如果模型窗口足够大,而且外部服务提供了资源,末尾还会附上 MCP 资源索引。 - 日期和时区放在本轮任务的开头。
把不变的规则放在开头、经常变化的上下文放在末尾,同一个 ...
未能定位到原文的划线
企业级Agent工作流编排项目PaiFlow
Vibe Coding版本的PaiAgent
派聪明RAG AI知识库Java版本+Go版本
微服务 PmHub、技术派、MYDB
求职派JobClaw(OpenClaw/Hermes架构
PaiCLI(类似Claude Code的Agent
派简历(代码已完成)
等实战项目。
1. 微信扫右侧的优惠券加入知识星球
2. 解锁星球的实战项目教程和源码: 项目源码+教程获取
暂无评论
回复