Solon TeamAgent 协作协议：从 SEQUENTIAL 流水线到 HIERARCHICAL 主管团队

如果单个智能体是专家，那团队就是组织架构。难点不在"多加几个 Agent"，而在于：下一步谁说话、谁审核、何时停机。

Solon AI 的 TeamAgent 把这件事做成一等公民------协作协议（TeamProtocol）。换协议、保留成员，同一支队伍就能从线性流水线切到主管制层级协作，而不必重写业务逻辑。

本文梳理内置协议、生产环境真正有用的构建参数，以及两个最常落地的模式：SEQUENTIAL 流水线 与 HIERARCHICAL 主管团队。

为什么多智能体需要协议

单个超长 Prompt 常见失败原因很无聊，但很致命：

• 上下文膨胀，模型丢主线
• 角色边界模糊，人人都想包办
• 交接变成临时字符串，而不是可治理的图

TeamAgent 用三块结构解决：

1. 成员（Members） --- 有清晰 name / role 的专长智能体
2. 协议（Protocol） --- 团队的"社交规则 / 组织架构"
3. 主管模型（Supervisor ChatModel） --- 负责任务理解、分派与总结

依赖：

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-agent</artifactId>
</dependency>

内置协议一览

通过 TeamProtocols.xxx 获取：

协议	模式	优化目标	最佳场景
NONE	透明式	零框架编排	外部手绘流程、极高定制
HIERARCHICAL	层级式	拆解、指派、质量审计	复杂项目、合规审查、强质控
SEQUENTIAL	顺序式	确定性状态接力	翻译→校对→润色、发布流水线
SWARM	蜂群式	去中心化快速接力	客服路由、高并发多轮
A2A	对等式	点对点专家移交	垂直领域深度协作
CONTRACT_NET	合同网	竞争选出最佳执行者	最优解选择、分布式分配
MARKET_BASED	市场式	成本/资源敏感调度	高低成本模型混合路由
BLACKBOARD	黑板式	共享上下文异步协同	故障排查、多源数据融合

默认协议是 HIERARCHICAL。这是有意设计：大多数产品团队都需要一个能拆任务、做质检的主管。

最小构建：成员 + 协议

ReActAgent coder = ReActAgent.of(chatModel)
        .name("coder")
        .role("负责编写高质量 Java 代码")
        .build();

ReActAgent tester = ReActAgent.of(chatModel)
        .name("tester")
        .role("负责编写和运行单元测试")
        .build();

TeamAgent techTeam = TeamAgent.of(chatModel)
        .name("dev_group")
        .agentAdd(coder)
        .agentAdd(tester)
        .protocol(TeamProtocols.SEQUENTIAL)
        .build();

String result = techTeam.prompt("帮我实现一个排序工具并附带测试。")
        .call()
        .getContent();

关键点：

• TeamAgent.of(chatModel) --- 团队级模型充当 Supervisor
• agentAdd(...) --- 成员可以是 ReActAgent、SimpleAgent，甚至嵌套团队
• protocol(...) --- 拓扑开关
• SEQUENTIAL 下按 添加顺序 执行

模式 1：SEQUENTIAL 流水线

路径已知、希望确定性接力时用它：

翻译 → 润色 → 总结

TeamAgent simpleTeam = TeamAgent.of(chatModel)
        .name("translator_group")
        .role("负责多语言翻译与内容优化的团队")
        .agentAdd(ReActAgent.of(chatModel)
                .name("translator")
                .role("将中文翻译为英文")
                .build())
        .agentAdd(ReActAgent.of(chatModel)
                .name("polisher")
                .role("润色英文表达，使其地道")
                .build())
        .protocol(TeamProtocols.SEQUENTIAL)
        .build();

String result = simpleTeam.prompt("你好，很高兴认识你")
        .call()
        .getContent();

为什么有效：

• 前一个输出直接成为后一个输入
• 比自由多 Agent 对话更少上下文抖动
• 故障点清晰、可预期

阶段固定且有序时选 SEQUENTIAL。如果后段经常要推翻前段重规划，别硬套流水线。

模式 2：HIERARCHICAL 主管团队

这是"真实公司"模式：主管解析用户需求，调度专家，再汇总终答。

TeamAgent techTeam = TeamAgent.of(chatModel)
        .name("tech_support_center")
        .role("技术支持专家中心")
        .instruction("负责处理复杂的客户技术问题，包括查询数据库和排查日志")

        .agentAdd(ReActAgent.of(chatModel)
                .name("db_expert")
                .role("数据库专家，擅长编写 SQL 查询用户信息")
                .defaultToolAdd(dbTool)
                .build())
        .agentAdd(ReActAgent.of(chatModel)
                .name("log_analyser")
                .role("日志分析专家，负责从服务器日志中提取异常")
                .defaultToolAdd(logTool)
                .build())

        .protocol(TeamProtocols.HIERARCHICAL)
        .maxTurns(12)
        .retryConfig(3, 2000L)
        .modelOptions(options -> {
            options.setTemperature(0.1f); // 分发更严谨
        })
        .build();

String finalAnswer = techTeam.prompt("用户 ID 为 9527 的反馈登录失败，请排查原因并给出建议。")
        .call()
        .getContent();

生产配置里真正重要的旋钮：

参数	默认值	作用
protocol	HIERARCHICAL	团队组织方式
maxTurns	8	全队最大协作轮次，防无限踢皮球
maxRetries	3	主管决策/解析失败重试
retryDelayMs	1000L	重试间隔
modelOptions	---	调主管温度等采样参数
graphAdjuster	---	微调协议生成的执行图
interceptors	空	观测或干预交接

maxTurns 在生产里不是可选项。多智能体更常死在"互相确认到死"，而不是"少了一个工具"。

工具仍然走标准写法

成员就是普通 Agent。工具挂在真正拥有该能力的成员上：

public static class WeatherService extends AbsToolProvider {
    @ToolMapping(description = "获取指定城市的实时天气预报")
    public String query(@Param(description = "城市名称，例如：东京") String city) {
        return "【气象警报】" + city + "目前遭遇特大暴雨，户外景点暂时关闭。";
    }
}

TeamAgent travelTeam = TeamAgent.of(chatModel)
        .name("auto_travel_agent")
        .agentAdd(ReActAgent.of(chatModel)
                .name("searcher")
                .role("天气查询专家")
                .defaultToolAdd(new WeatherService())
                .build())
        .agentAdd(ReActAgent.of(chatModel)
                .name("planner")
                .role("行程规划专家")
                .instruction("天气差时必须优先室内方案。")
                .build())
        .maxTurns(8)
        .build(); // 默认协议 = HIERARCHICAL

AgentSession session = InMemoryAgentSession.of("sn_travel_2026_001");
TeamResponse resp = travelTeam.prompt("我现在在东京，请帮我规划一天的行程。")
        .session(session)
        .call();

响应里重点看：

• resp.getContent() --- 团队终答
• resp.getTrace() --- 协作轨迹 / 交接路径

没有 trace，多 Agent 只是"看起来很智能"；有了 trace，凌晨两点才能排障。

怎么选协议

实用决策树：

1. 阶段固定、顺序明确 → SEQUENTIAL
2. 需要拆解 + 质检 → HIERARCHICAL
3. 多名能力重叠专家，择优执行 → CONTRACT_NET / MARKET_BASED
4. 专家直连移交，少管理层开销 → A2A
5. 共享事件板，异步专家介入 → BLACKBOARD
6. 已有外部编排器 → NONE

大多数产品团队应从 HIERARCHICAL 或 SEQUENTIAL 起步。更花哨的协议很强，但前提是角色描述和停机条件已经扎实。

角色描述不是装饰

在团队里，role / instruction 是给主管看的路由数据。弱角色只会带来弱分派：

• 差："助手"
• 更好："数据库专家；负责用 SQL 检查用户登录状态与近期鉴权事件"

成员 name 也要稳定。轨迹、会话恢复、嵌套团队路由，都依赖稳定身份。

支持嵌套团队

TeamAgent 本身可以成为更大团队的成员。这样可以从两人流水线长成多层组织，而不需要第二套框架。

适合：

• 客服中心内嵌账单子团队
• 发布团队内嵌安全审查子团队
• 研究团队内嵌检索 + 综合子团队

不建议的做法

• 没有 maxTurns 就放任 Agent 自由互聊
• 把所有工具挂给所有成员"以防万一"
• 角色还分不清就上 CONTRACT_NET / MARKET_BASED
• 自造 Tool 接口------继续用 AbsToolProvider + @ToolMapping
• 排障时不看 trace

上线前检查清单

• 每个成员都有可区分的 name 和可执行 role
• 协议匹配真实业务拓扑
• maxTurns 覆盖最长健康路径
• 主管温度足够低，保证分派纪律
• 工具挂在真正的专家成员上
• 具备 session + trace，方便恢复与排障

结语

多智能体系统不会因为"模型更多"而自动可靠。可靠来自 交接是显式的。

Solon 的 TeamAgent 把这件事说清楚了：

• 成员定义能力
• TeamProtocols 定义组织
• 主管 + maxTurns 定义控制
• 轨迹让全流程可观察

先从两人 SEQUENTIAL 流水线开始。当任务需要重规划与质检时，切到 HIERARCHICAL。成员保留，协议切换------这正是它的价值。

参考

• TeamAgent 构建您的 AI 数字团队
• TeamAgent 配置与构建
• TeamAgent 协作协议
• Team Hello World
• 示例1 - 旅行安排
• 点、圈、网的协同演进