实现 Multi-Agent 和 SubAgent 并发，让 Agent 团队跑得飞起

我们的 PaiCLI Agent 已经实现了 ReAct、Plan-and-Execute、Memory、RAG，一个单 Agent 已经能读文件、跑命令、搜代码、记住上下文了。

但我们还想要更多。

OK，今天我们就来完成 Multi-Agent，把一个全能型 Agent 拆成多个专职角色，让它们协作完成任务。

就像一个大型项目团队。

产品经理负责拆需求，开发负责写代码，测试负责验收。各司其职，互相制衡。Multi-Agent 也是同样的思路。

01、Multi-Agent 到底在解决什么问题

先不着急写代码，我们先搞清楚为什么需要 Multi-Agent。

Multi-Agent 的核心价值就是引入多个脚色。

规划者专门拆任务，执行者专门干活，检查者专门找茬。每个人只做一件事，做精、做深。

市面上的 Multi-Agent 框架也验证了这个趋势。微软的 AutoGen 已经拿到了 57.3K Star，CrewAI 也有 49.5K Star，两个项目都在强调“角色分工 + 协作”。

AutoGen 是偏对话驱动的多 Agent 协作，多个 Agent 围绕同一个问题展开讨论，适合需要反复沟通和协商的场景。

CrewAI 偏角色扮演+任务委派，先定义角色再分配任务，适合流程明确的执行类场景。

PaiCLI 选择了更接近 CrewAI 的方式——定义角色、分配任务、审查结果。

为了给大家讲清楚 Multi-Agent，我们是从 0 开始手写的，没有用 LangGraph4J 框架，我觉得下一期可以把这个框架引入进来。

02、主从模式+三角色分工

PaiCLI 选择了主从架构（Orchestrator-SubAgent），编排器是“主”，子 Agent 是“从”。

编排器负责任务分发和流程控制，子 Agent 只管干自己的活。

为什么选主从而不是对等模式？

因为对等模式下 Agent 之间需要直接通信。当然，后面我们也可以迭代一个新的版本。

主从模式把协调逻辑集中到编排器，子 Agent 之间不直接对话，所有消息都经过编排器路由。结构清晰，调试方便。

三个角色的定义非常清晰：

规划者（Planner）——拿到用户需求，拆成可执行的步骤列表，标注每一步的类型和依赖关系。

执行者（Worker）——拿到步骤描述，调用工具完成具体操作。读文件、写文件、跑命令，都是执行者的事。

检查者（Reviewer）——拿到执行结果，判断是否符合要求。通过就放行，不通过就把问题打回去，让执行者重新干。

代码结构上，这四个类各司其职：

AgentRole.java 定义角色枚举，三个值：PLANNER、WORKER、REVIEWER。每个角色有显示名和描述。

public enum AgentRole {
    PLANNER("规划者", "负责分析用户任务，制定执行计划，将复杂任务拆解为可执行的子任务"),
    WORKER("执行者", "负责执行具体任务步骤，调用工具完成文件操作、命令执行等操作"),
    REVIEWER("检查者", "负责检查执行结果的质量和正确性，提供改进建议");
}

AgentMessage.java 定义 Agent 间的通信消息，用 Java 17 的 record 实现。六种消息类型：TASK（任务）、RESULT（结果）、FEEDBACK（反馈）、APPROVAL（通过）、REJECTION（拒绝）、ERROR（错误）。

消息的状态就靠这六种类型。

public record AgentMessage(
        String fromAgent,
        AgentRole fromRole,
        String content,
        Type type
) {
    public enum Type {
        TASK, RESULT, FEEDBACK, APPROVAL, REJECTION, ERROR
    }
}

SubAgent.java 是子 Agent 的实现，每个子 Agent 有独立的角色、系统提示词和对话历史，但共享 LLM 客户端和工具注册表。

AgentOrchestrator.java 是编排器，管理整个协作流程——从规划到执行到审查到汇总。

整个架构用一句话概括：编排器拿着任务找规划者拆、找执行者干、找检查者验，全部通过后汇总结果返回给用户。

03、团队的指挥官

编排器是整个 Multi-Agent 系统的核心，所有协调逻辑都在这里。我们先看它的构造方法：

public AgentOrchestrator(GLMClient llmClient, ToolRegistry toolRegistry, MemoryManager memoryManager) {
    this.llmClient = llmClient;
    this.toolRegistry = toolRegistry;
    this.planner = new SubAgent("planner", AgentRole.PLANNER, llmClient, toolRegistry);
    this.workers = List.of(
            new SubAgent("worker-1", AgentRole.WORKER, llmClient, toolRegistry),
            new SubAgent("worker-2", AgentRole.WORKER, llmClient, toolRegistry)
    );
    this.reviewer = new SubAgent("reviewer", AgentRole.REVIEWER, llmClient, toolRegistry);
    this.memoryManager = memoryManager;
}

默认创建 1 个规划者、2 个执行者、1 个检查者。两个 Worker 做轮询分配，当一个 Worker 在干活的时候，另一个可以接下一个步骤。这是为并行执行做准备。

编排器的核心方法 run() 是整个协作的入口，流程分六个阶段：

• 第一阶段：规划。编排器把用户任务交给规划者，规划者输出一份 JSON 格式的执行计划。
• 第二阶段：解析计划。编排器把 JSON 解析成 ExecutionStep 列表，建立步骤间的依赖关系。
• 第三阶段：执行。按依赖顺序，把可执行的步骤分配给 Worker。同一批次内没有依赖关系的步骤可以并行。
• 第四阶段：审查。每个步骤执行完后，交给检查者验收。通过就标记完成，不通过就带上反馈重新执行。
• 第五阶段：处理残留步骤。如果某步失败导致后续依赖步骤无法执行，显式提示用户这些步骤被跳过了。
• 第六阶段：汇总结果。把所有步骤的状态和结果汇总，写入记忆，返回给用户。

代码如下：

public String run(String userInput) {
    // 1. 规划
    AgentMessage planResult = planner.execute(planMessage);

    // 2. 解析计划
    List steps = parsePlan(planResult.content());

    // 3. 执行 + 审查
    while (true) {
        List executable = getExecutableSteps(steps);
        if (executable.isEmpty()) break;
        // 单步串行，多步并行
    }

    // 4. 处理残留 + 汇总
    String finalResult = buildFinalResult(steps);
    return finalResult;
}

这里有个细节值得展开讲讲——依赖管理和可执行步骤的判定。

依赖关系怎么判定

每一步都有一组 dependencies，标注它依赖哪些步骤。

只有所有依赖步骤都完成后，这一步才能执行。getExecutableSteps() 的逻辑就是过滤出“状态为 PENDING 且所有依赖都 COMPLETED”的步骤：

List getExecutableSteps(List steps) {
    Map