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

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


### 1、内置协作模式概览


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



| 协议           | 模式    | 协作特征   | 核心价值                   | 最佳应用场景          |
|--------------|-------|--------|------------------------|---------------|
| NONE         | 透明式   | 无预设编排  | 完全的编排自由度，零框架干预         | 外部手绘流程、极高定制化业务 |
| HIERARCHICAL | 层级式   | 中心化决策  | 严格的任务拆解、指派与质量审计        | 复杂项目管理、多级合规审查、强质量管控任务 |
| SEQUENTIAL   | 顺序式   | 线性单向流  | 确定性的状态接力，减少上下文损失       | 翻译->校对->润色流水线、自动化发布流程  |
| SWARM        | 蜂群式   | 动态自组织  | 去中心化的快速接力，响应速度极快       | 智能客服路由、简单的多轮对话接力、高并发任务  |
| A2A          | 对等式   | 点对点移交  | 授权式移交，减少中间层干扰          | 专家咨询接力、技术支持转接、特定领域的垂直深度协作 |
| CONTRACT_NET | 合同网   | 招标投标制  | 通过竞争机制获取任务处理的最佳方案      | 寻找最优解任务、分布式计算分配、多方案择优场景    |
| MARKET_BASED | 市场式   | 经济博弈制  | 基于“算力/Token成本”等资源的最优配置 | 资源敏感型任务、高成本模型与低成本模型的混合调度    |
| BLACKBOARD   | 黑板式   | 共享上下文  | 异步协同，专家根据黑板状态主动介入      | 复杂故障排查、非线性逻辑推理、多源数据融合分析  |




### 2、应用示例


```java
// 创建一个基于层级协调模式的智能体团队
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 智能体编排的核心，它贯穿了从静态构建到运行期治理的全生命周期。


```java
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 提示词（在此处处理上下文衔接或状态同步）
     */
    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());
        }
    }
}
```


定制示例：


```java
public class NoneProtocol implements TeamProtocol {

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

    public NoneProtocol(TeamAgentConfig config) {

    }

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