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

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

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

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

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

• 环境感知：TeamAgent 启动时，会在工作流上下文（FlowContext）中埋入一个 _current_trace_key。
• 生命周期注入：每个 Agent 执行时，其 run 方法会自动完成以下操作：
  • 读记忆：从 TeamTrace 提取历史记录，拼接到当前 Prompt 中，让 Agent 拥有"全局视野"。
  • 记轨迹：执行完成后，自动调用 trace.addRecord(ChatRole.ASSISTANT, name(), content, duration)，记录谁（Name）、说了什么（Content）、耗时多久（Duration）。

2、获取方式

从会话中提取"当前" TeamTrace

TeamTrace.getCurrent(session.getSnapshot());

从同步调用结果中获取

TeamResponse resp = agent.prompt("...").call();
TeamTrace trace = resp.getTrace();

从流式响应事件中获取

agent.prompt("...").stream()
    .doOnNext(event -> {
        if (event instanceof SupervisorDeltaEvent) {
            SupervisorDeltaEvent supervisorEvent = (SupervisorDeltaEvent) event;
            supervisorEvent.getTrace();
        }
    })
    .subscribe();

从拦截器中获取。具体参考拦截器资料。

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

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

场景：一个负责"复核"的 Agent

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

    @Override
    public AssistantMessage 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 < 1000) {
                // 通过协议上下文传递重审标记，让调度器知晓
                trace.getProtocolContext().put("needs_review", true);
            }

            // 3. 获取前一个 Agent 的输出作为上下文参考
            String lastContent = trace.getLastAgentContent();
            prompt = prompt.appendContext("上一个专家的输出: " + lastContent);
        }

        // 执行 LLM 调用
        return call(prompt);
    }
}

4、流式事件中的团队轨迹

在 TeamAgent 流式模式下，不仅会产生 Supervisor 调度决策事件，还会产生节点级生命周期事件：

注意：NodeChunk 已在 4.0.4 版本标记为 @Deprecated，请使用 NodeStartEvent / NodeEndEvent 替代。

从流式中获取团队轨迹的完整示例：

agent.prompt("策划一次团建活动").stream()
    .doOnNext(event -> {
        if (event instanceof TeamStartEvent) {
            TeamStartEvent e = (TeamStartEvent) event;
            System.out.println("🏁 团队任务开始: " + e.getTrace().getAgentName());
        } else if (event instanceof NodeStartEvent) {
            NodeStartEvent e = (NodeStartEvent) event;
            System.out.println("👤 专家开始工作: " + e.getNode().getId());
        } else if (event instanceof SupervisorDeltaEvent) {
            SupervisorDeltaEvent e = (SupervisorDeltaEvent) event;
            System.out.print(e.getResponse().getMessage().getContent()); // 调度器实时输出
        } else if (event instanceof NodeEndEvent) {
            NodeEndEvent e = (NodeEndEvent) event;
            System.out.println("✅ 专家完成: " + e.getNode().getId());
        } else if (event instanceof TeamEndEvent) {
            TeamEndEvent e = (TeamEndEvent) event;
            System.out.println("🎯 团队任务完成，最终答案: " + e.getMessage().getContent());
        }
    })
    .subscribe();

5、常用 API 快速查阅

6、最佳实践提示

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

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