team - TeamTrace 协作记忆与轨迹治理

在多智能体（Multi-Agent）协作中，如何让 Agent 知道“别人刚才说了什么”？如何统计整个团队的消耗？如何防止 Agent 之间陷入死循环？

TeamTrace 是 Solon AI 提供的协作轨迹模型。它像一个随身的“黑匣子”，全程记录团队内部每个智能体的发言、耗时及决策路径。

1、自动收集原理：数据是怎么进来的？

开发者不需要手动为每个 Agent 写抓取代码。其核心秘密在于 Agent 接口的默认执行逻辑：

环境感知：TeamAgent 启动时，会在工作流上下文（FlowContext）中埋入一个 _current_trace_key。

生命周期注入：每个 Agent 执行时，其 run 方法会自动完成以下操作：

• 读记忆：从 TeamTrace 提取历史记录，拼接到当前 Prompt 中，让 Agent 拥有“全局视野”。
• 记轨迹：执行完成后，自动调用 trace.addStep(...)，记录谁（Name）、说了什么（Content）、耗时多久（Duration）。

2、示例参考：在自定义 Agent 中利用 TeamTrace

当你实现自定义 Agent 时，可以通过 TeamTrace 实现更复杂的逻辑判断，例如“根据前一个人的反馈来调整自己的策略”。

场景：一个负责“复核”的 Agent

public class ReviewAgent implements Agent {
    @Override
    public String name() { return "reviewer"; }

    @Override
    public String call(FlowContext context, Prompt prompt) throws Throwable {
        // 1. 获取当前 TeamTrace 实例
        TeamTrace trace = TeamTrace.getCurrent(context);

        if (trace != null) {
            // 2. 检查最近一次协作
            long duration = trace.getLastAgentDuration();
            
            // 如果前一个 Agent 耗时过短，可能产生了幻觉，要求重审
            if (duration < 500) {
                 return "检测到前置任务处理过快，请重新生成详细逻辑。";
            }
            
            // 3. 获取完整的格式化历史，用于自定义 Prompt 构造
            String history = trace.getFormattedHistory();
            System.out.println("当前协作进展：\n" + history);
        }

        return "审核通过。";
    }
}

3、高级功能：协作治理与死循环检测

TeamTrace 不仅记录数据，还负责“监督”协作质量。

• 迭代安全计数 (getTurnCount)：底层会自动维护 turnCounter。每经过一轮决策或执行，计数器加一。这可用于在拦截器中判断是否达到了“最大轮次”从而强制熔断。

• 协议私有上下文 (protocolContext)：这是智能体之间的“小纸条”。如果你需要传递非文本数据（如：数据库连接对象、权限状态位），应存放在这里。

• 最终结果设置 (setFinalAnswer)：在复杂流程或自由编排模式下，必须手动调用此方法设置团队的“最终答复”，否则 team.call().getContent() 将无法获取结果。

4、常用 API 快速查阅

5、最佳实践提示

• 内存与长度管理：对于超长对话，getFormattedHistory() 会产生巨大的字符串。如果 LLM 窗口受限，建议使用 getFormattedHistory(windowSize) 仅获取最近 N 步。
• 结构化通信：如果你的团队在执行过程中需要传递中间变量（如：提取出的订单号），不要试图让下一个 Agent 去解析上一人的文本，直接使用 getProtocolContext().put(key, value) 更加可靠。
• 如何获取实例？：

// 在任何能拿到 FlowContext 的地方执行
TeamTrace trace = TeamTrace.getCurrent(context);