multi - TeamAgent 协作协议（模式、策略）

在复杂的业务场景中，单一的智能体往往难以胜任。Solon AI 的 TeamAgent 允许我们将多个专注于不同领域的智能体（如：搜索专家、编码专家、审计专家）组合成一个强大的团队。

而 TeamProtocol（团队协议） 正是这个团队的“社交规则”或“组织架构”。它定义了任务如何在不同智能体之间流转、谁负责决策以及如何达成最终共识。

1、内置协作模式概览

可通过 TeamProtocols.xxx 常量获取

还可以支持“自由模式”（即无模式运行）

2、应用示例

// 创建一个基于层级协调模式的智能体团队
TeamAgent techTeam = TeamAgent.of(chatModel)
        .name("tech_center")
        .addAgent(coderAgent)   // 程序员
        .addAgent(testerAgent)  // 测试员
        .addAgent(managerAgent) // 主管
        .protocol(TeamProtocols.HIERARCHICAL) // 设置为层级协议
        .build();

// 团队协作处理任务
String result = techTeam.call(FlowContext.of(), "帮我实现一个权限管理模块，并完成测试。");

3、协议的应用逻辑

顺序流转 (SEQUENTIAL)

这是最直观的模式。类似于工业生产线，前一个智能体的输出直接作为后一个智能体的输入。

• 优点：逻辑极其简单，结果可预测。

层级协调 (HIERARCHICAL)

引入了“领导者”的概念。Leader 负责解析用户的 Prompt，将其拆分为子任务（Sub-tasks），指派给专门的 Worker，最后由 Leader 进行质量审核和总结。

• 优点：能处理逻辑深度大、需要统筹的任务。

合同网协议 (CONTRACT_NET)

这是一种经典的分布式协作机制。任务发起者向团队广播“需求”，各个 Agent 根据自己的状态和专长返回“投标书”，发起者选择最佳方案。

• 优点：极高的灵活性，能够自动避开繁忙或能力不匹配的 Agent。

4、选择建议

• 如果您需要严密的审核流程：请选择 HIERARCHICAL（由 Leader 负责最终把关）。
• 如果任务涉及多个独立环节且互不干扰：请选择 SEQUENTIAL。
• 如果您拥有大量功能重叠的 Agent 资源：请选择 MARKET_BASED 或 CONTRACT_NET 来优化效率。
• 如果您在处理不确定性极高的科学探索：请尝试 BLACKBOARD。

所有的协作协议都完美支持 ReActTrace 状态回溯。无论协作过程多复杂，您都可以在日志中清晰地查看到任务是在哪一环、根据哪种协议规则进行了转办。

5、TeamProtocol 接口参考

import org.noear.solon.flow.FlowContext;
import org.noear.solon.flow.GraphSpec;

import java.util.Locale;

/**
 * 团队协作协议接口
 * <p>定义 Agent 团队的协作模式（如顺序、蜂群、层级等），负责拓扑构建、提示词注入及路由决策干预。</p>
 *
 * @author noear
 * @since 3.8.1
 */
public interface TeamProtocol {
    /**
     * 获取协议唯一标识（如: SWARM, SEQUENTIAL）
     */
    String name();

    /**
     * [生命周期：构建期] 构建团队协作图的拓扑结构
     *
     * @param config 团队配置
     * @param spec   图规格定义
     */
    void buildGraph(TeamConfig config, GraphSpec spec);

    /**
     * [生命周期：初始化] 注入协议固有的静态系统提示词指令
     *
     * @param config 团队配置
     * @param locale 语言环境
     * @param sb     用于追加指令的字符串构建器
     */
    void injectInstruction(TeamConfig config, Locale locale, StringBuilder sb);

    /**
     * [生命周期：决策前] 准备运行时的动态指令补充信息
     * <p>例如：在智能决策前注入当前的竞标书内容、黑板摘要或 Agent 执行次数统计。</p>
     *
     * @param context 流上下文
     * @param trace   协作跟踪状态
     * @param sb      用于追加动态信息的字符串构建器
     */
    default void prepareInstruction(FlowContext context, TeamTrace trace, StringBuilder sb) {
    }

    /**
     * [生命周期：执行拦截] 拦截主管（Supervisor）的通用执行逻辑
     *
     * @return true 表示协议已接管执行流程，不再进入智能路由决策（如顺序模式的直接跳转）
     */
    default boolean interceptExecute(FlowContext context, TeamTrace trace) throws Exception {
        return false;
    }

    /**
     * [生命周期：路由干预] 在智能决策完成后，干预路由跳转结果
     *
     * @param context  流上下文
     * @param trace    协作跟踪状态
     * @param decision LLM 给出的原始决策内容
     * @return true 表示协议已根据决策内容完成路由处理，跳过通用的 Agent 匹配逻辑
     */
    default boolean interceptRouting(FlowContext context, TeamTrace trace, String decision) {
        return false;
    }

    /**
     * [生命周期：路由转向] 路由确定后的回调钩子
     * <p>当下一个执行对象（Agent 或 End）被确定后触发。常用于更新执行统计、状态机流转等。</p>
     *
     * @param context   流上下文
     * @param trace     协作跟踪状态
     * @param nextAgent 即将执行的 Agent 名称（或结束标识）
     */
    default void onRouting(FlowContext context, TeamTrace trace, String nextAgent) {
    }

    /**
     * [生命周期：任务结束] 团队任务彻底完成或异常中断后的清理工作
     */
    default void onFinished(FlowContext context, TeamTrace trace) {
        // 用于清理 context 中的临时数据，释放资源
    }
}

定制示例：

public class BlackboardProtocol extends HierarchicalProtocol {
    @Override
    public String name() {
        return "BLACKBOARD";
    }

    @Override
    public void injectInstruction(TeamConfig config, Locale locale, StringBuilder sb) {
        if (Locale.CHINA.getLanguage().equals(locale.getLanguage())) {
            sb.append("1. **黑板机制**：历史记录即公共黑板，请检查哪些信息缺失或需要修正。\n");
            sb.append("2. **按需补位**：指派能填补空白或纠正错误的 Agent 执行。");
        } else {
            sb.append("1. **Blackboard Mechanism**: History is a public board; check for missing or incorrect info.\n");
            sb.append("2. **Gap Filling**: Assign the Agent best suited to fill gaps or correct errors.");
        }
    }
}