无耳 Solon (OpenSolon) | react - ReActTrace 思考记忆与轨迹

在 ReAct（Reasoning and Acting）模式下，智能体不再是简单的“问答机”，而是一个具备“思考-行动-观察”循环的逻辑引擎。ReActTrace 正是记录这一循环过程的核心载体。它充当了智能体的运行时记忆和状态机，确保在复杂的推理过程中逻辑不丢失、状态可回溯。

1、核心职责：不仅是记录，更是驱动

ReActTrace 在一个典型的推理周期中承担了四种关键角色：

逻辑状态机：维护 REASON（推理）、ACTION（行动）、END（结束）的流转状态。
工作记忆 (Working Memory)：实时存储当前任务的所有上下文、模型思考内容、工具调用参数及其返回结果（Observation）。
度量审计：自动统计推理步数（Step Count）、工具调用次数以及 Token 消耗。
计划中枢：如果启用了 Planning 能力，它还负责动态维护执行计划及其进度。

2、常用 API 快速查阅

分类	方法	返回类型	功能描述
基础上下文	`getOriginalPrompt()`	`Prompt`	获取用户最初输入的任务指令。
	`getSession()`	`AgentSession`	获取当前会话上下文（持有对话历史）。
	`getContext()`	`FlowContext`	获取流程快照，用于跨节点数据共享。
状态控制	`getRoute() / setRoute()`	`String`	获取或更新当前的路由逻辑标识。
	`getStepCount()`	`int`	获取当前已进行的推理轮次。
	`nextStep()`	`int`	步数递增（通常由引擎在每一轮 Reason 前自动调用）。
执行计划	`setPlans(Collection)`	`void`	注入或更新智能体生成的执行计划列表。
	`getFormattedPlans()`	`String`	获取 Markdown 格式的计划列表，用于增强模型感知的有序性。
	`getPlanProgress()`	`String`	获取当前进度描述（如：总步数与当前进度的对比）。
结果与度量	`getFinalAnswer()`	`String`	获取最终生成的结论。
	`getMetrics()`	`Metrics`	获取性能度量指标（耗时、Token 消耗等）。
	`getFormattedHistory()`	`String`	获取人性化的对话与行动历史记录（Markdown 格式）。

3、自定义拦截器中的应用示例

在 AgentInterceptor 或 TeamInterceptor 中，你可以通过 ReActTrace 深度干预智能体的行为。

场景：防止推理无限循环

public class LoopGuardInterceptor implements AgentInterceptor {
    @Override
    public boolean shouldAgentContinue(AgentTrace trace, Agent agent) {
        if (trace instanceof ReActTrace) {
            ReActTrace rt = (ReActTrace) trace;
            // 如果推理步数超过 10 步且还没有结束迹象，强制熔断并报警
            if (rt.getStepCount() > 10) {
                LOG.warn("Agent [{}] 陷入逻辑死循环，强制停止", agent.name());
                rt.setFinalAnswer("任务过于复杂或陷入死循环，已由安全拦截器中止。");
                return false; 
            }
        }
        return true;
    }
}

4、技术特性解析

4.1 协议工具注入 (Protocol Tooling)

当智能体处于 TeamAgent 协作模式下，协作协议（TeamProtocol）可能会动态注入一些特殊工具（如 transfer_to）。这些工具被存储在 protocolToolMap 中，优先级高于智能体的默认工具。

4.2 结构化历史记录

getFormattedHistory() 会将复杂的消息列表转换为易于阅读的日志格式：

[User]: 原始指令
[Assistant]: 模型的思考（Thought）
[Action]: 调用的工具名及参数
[Observation]: 工具返回的结果

4.3 动态计划管理

如果开启了 options.setEnablePlanning(true)，智能体会先在 ReActTrace 中生成一份 plans。每一轮推理时，系统会自动将这份计划和当前进度（getPlanProgress()）注入提示词，显著提升 Agent 处理复杂长任务的成功率。

5、使用建议

调试神器：在开发阶段，打印 getFormattedHistory() 是排查智能体为什么“跑偏”的最快方式。

内存注意：对于长任务，workingMemory 会持续增长。在极高并发场景下，建议通过拦截器监控 stepCount 以防止内存异常增长。

结果提取：如果需要将 AI 的结果转换为 Java 对象，通常在 finalAnswer 产出后，配合 toBean(Class) 使用。

Solon v3.9.0