team - TeamAgent 协作协议

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

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

1、内置协作模式概览

通过协议，您可以将 “一群 Agent” 转变为 “一个组织”。可通过 TeamProtocols.xxx 常量获取：

2、应用示例

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

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

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 接口参考

TeamProtocol 接口是 Solon AI 智能体编排的核心，它贯穿了从静态构建到运行期治理的全生命周期。

import org.noear.solon.ai.agent.Agent;
import org.noear.solon.ai.chat.prompt.Prompt;
import org.noear.solon.ai.chat.tool.FunctionTool;
import org.noear.solon.flow.FlowContext;
import org.noear.solon.flow.GraphSpec;
import org.noear.solon.lang.NonSerializable;
import org.noear.solon.lang.Preview;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Locale;
import java.util.function.Consumer;

/**
 * 团队协作协议 (Team Protocol)
 *
 * <p>核心职责：定义多智能体协作的拓扑结构、指令干预逻辑与路由治理机制。</p>
 *
 * @author noear
 * @since 3.8.1
 */
@Preview("3.8.1")
public interface TeamProtocol extends NonSerializable {
    static final Logger LOG = LoggerFactory.getLogger(TeamProtocol.class);

    /**
     * 获取协议唯一标识（如 SEQUENTIAL, SWARM, HIERARCHICAL）
     */
    String name();

    // --- [阶段 1：静态构建] ---

    /**
     * 构建协作拓扑图（定义节点间的连接关系）
     */
    void buildGraph(GraphSpec spec);

    // --- [阶段 2：成员 Agent 运行期] ---

    /**
     * 注入 Agent 协议专属工具（如转交、抄送等控制工具）
     */
    default void injectAgentTools(FlowContext context, Agent agent, Consumer<FunctionTool> receiver) { }

    /**
     * 注入 Agent 行为约束指令（定义角色规范）
     */
    default void injectAgentInstruction(FlowContext context, Agent agent, Locale locale, StringBuilder sb) { }

    /**
     * 动态生成 Agent 提示词（在此处处理上下文衔接或状态同步）
     */
    default Prompt prepareAgentPrompt(TeamTrace trace, Agent agent, Prompt originalPrompt, Locale locale) {
        return originalPrompt;
    }

    /**
     * 解析并适配 Agent 输出（在记录轨迹前进行内容转换）
     */
    default String resolveAgentOutput(TeamTrace trace, Agent agent, String content) {
        return content;
    }

    /**
     * Agent 节点执行结束回调
     */
    default void onAgentEnd(TeamTrace trace, Agent agent) { }

    // --- [阶段 3：主管 Supervisor 治理] ---

    /**
     * 注入 Supervisor 协议专属工具（如转交、抄送等控制工具）
     */
    default void injectSupervisorTools(FlowContext context, Consumer<FunctionTool> receiver){

    }

    /**
     * 注入 Supervisor 静态系统指令（定义全局调度准则）
     */
    default void injectSupervisorInstruction(Locale locale, StringBuilder sb) { }

    /**
     * 注入 Supervisor 动态决策指令（如实时进度、环境感知）
     */
    default void prepareSupervisorInstruction(FlowContext context, TeamTrace trace, StringBuilder sb) { }

    /**
     * 注入 Supervisor 决策上下文（如待办事项、黑板状态）
     */
    default void prepareSupervisorContext(FlowContext context, TeamTrace trace, StringBuilder sb) { }

    /**
     * 决策准入干预（返回 false 则跳过 LLM 智能决策，用于固定流程）
     */
    default boolean shouldSupervisorExecute(FlowContext context, TeamTrace trace) throws Exception {
        return true;
    }

    /**
     * 解析路由目标（将决策文本语义化为节点 ID）
     * @return 目标节点 ID；返回 null 则由系统默认逻辑解析
     */
    default String resolveSupervisorRoute(FlowContext context, TeamTrace trace, String decision) {
        return null;
    }

    /**
     * 路由决策预干预（允许协议在此处强行改变跳转方向）
     */
    default boolean shouldSupervisorRoute(FlowContext context, TeamTrace trace, String decision) {
        return true;
    }

    /**
     * 确定路由目标后的最终回调
     */
    default void onSupervisorRouting(FlowContext context, TeamTrace trace, String nextAgent) {
        if (LOG.isDebugEnabled()) {
            LOG.debug("Protocol [{}] routing to: {}", name(), nextAgent);
        }
    }

    // --- [阶段 4：生命周期销毁] ---

    /**
     * 协作任务结束清理
     */
    default void onTeamFinished(FlowContext context, TeamTrace trace) {
        if (LOG.isTraceEnabled()) {
            LOG.trace("Protocol [{}] session finished for trace: {}", name(), trace.getConfig().getTraceKey());
        }
    }
}

定制示例：

public class NoneProtocol implements TeamProtocol {

    @Override
    public String name() {
        return "NONE";
    }

    public NoneProtocol(TeamAgentConfig config) {

    }

    /**
     * 不定义内部流转逻辑，使 TeamAgent 仅作为 Agent 资源池使用
     */
    @Override
    public void buildGraph(GraphSpec spec) {
        // 显式留空，由外部编排驱动
    }
}