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)

实现类：SequentialProtocol

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

• 优点：逻辑极其简单，结果可预测。
• 使用：TeamProtocols.SEQUENTIAL

层级协调 (HIERARCHICAL)

实现类：HierarchicalProtocol

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

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

合同网协议 (CONTRACT_NET)

实现类：ContractNetProtocol

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

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

蜂群协议 (SWARM)

实现类：SwarmProtocol

Swarm 模式下，每个 Agent 执行完后将控制权交还给中枢，由中枢动态指派下一个执行者。任务路径并非预先固定，而是根据每一步的中间结果实时决策下一位执行者，形成去中心化的快速接力链路。

• 优点：响应速度极快，适合任务路径不固定、需要根据中间结果动态决策执行顺序的场景（如复杂的多轮调研任务）。
• 使用：TeamProtocols.SWARM

点对点协议 (A2A)

实现类：A2AProtocol

Agent 完成当前任务后，可以直接将控制权 Handoff 给另一个 Agent，无需经过中枢协调，从而减少中转延迟。整个协作链路中各节点的交接关系在设计阶段即已明确。

• 优点：延迟低、链路清晰，适合流程固定、有明确交接关系的协作链路（如：数据采集 Agent → 分析 Agent → 报告 Agent）。
• 使用：TeamProtocols.A2A

黑板协议 (BLACKBOARD)

实现类：BlackboardProtocol

所有 Agent 共享一个"黑板"状态空间。各专家 Agent 持续监测黑板上的当前状态，在自身专长范围内主动介入并贡献结果，再由下一位专家接力，直至问题被解决。

• 优点：天然支持异步协同与非线性推理，适合多专家协同解决复杂问题的场景（如：多领域专家共同诊断）。
• 使用：TeamProtocols.BLACKBOARD

市场竞价协议 (MARKET_BASED)

实现类：MarketBasedProtocol

任务发布后，各 Agent 按照自身的能力、当前负载及资源成本进行竞标，由中枢择优选择最合适的执行者。与 CONTRACT_NET 侧重"最优方案"不同，MARKET_BASED 更关注"资源最优配置"（如算力成本、Token 消耗）。

• 优点：在有多个能力相似但专长或成本不同的 Agent 时，可实现智能匹配与资源利用率最大化，适合资源敏感型任务及高低成本模型混合调度场景。
• 使用：TeamProtocols.MARKET_BASED

4、选择建议

• 如果您需要严密的审核流程：请选择 HIERARCHICAL（由 Leader 负责最终把关）。
• 如果任务涉及多个独立环节且互不干扰：请选择 SEQUENTIAL。
• 如果您拥有大量功能重叠的 Agent 资源：请选择 MARKET_BASED 或 CONTRACT_NET 来优化效率。
• 如果您在处理不确定性极高的科学探索：请尝试 BLACKBOARD。
• 如果任务路径不固定、需根据中间结果动态决策执行顺序：请选择 SWARM。
• 如果协作链路固定且需要减少中转延迟：请选择 A2A。

所有的协作协议都完美支持 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>
 */
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 提示词（在此处处理上下文衔接或状态同步）。
     *
     * <p>入参通常是共享的 {@code TeamTrace.workingMemory}。
     * 若需要追加协议消息，必须先 {@link Prompt#copy()} 再改，避免污染跨 Agent / 跨轮次上下文。
     * 默认实现返回副本；子类增强时优先 {@code super.prepareAgentPrompt(...)} 后追加。</p>
     */
    default Prompt prepareAgentPrompt(TeamTrace trace, Agent agent, Prompt originalPrompt, Locale locale) {
        return originalPrompt == null ? Prompt.of() : originalPrompt.copy();
    }

    /**
     * 解析并适配 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.isDebugEnabled()) {
            LOG.debug("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) {
        // 显式留空，由外部编排驱动
    }
}