Solon v3.8.0

react - ReActAgent 配置与构建

</> markdown
2026年1月4日 下午11:19:09

1、ReActAgent 配置参考（可参考 ReActConfig 字段）

分类参数名称类型默认值说明
身份定义nameString/智能体唯一 ID，用于 Trace 记忆与日志追踪。
titleString/视觉标题，多用于可视化 UI 界面显示。
descriptionString/核心职责描述。在多智能体协作（Team）中至关重要。
能力底座chatModelChatModel/执行推理的大语言模型（LLM）底座。
toolMapMap/挂载的功能工具集，支持业务 API 实时调用。
运行策略maxStepsint10思考-行动循环的最大步数，防止逻辑死循环。
maxRetriesint3模型请求失败或异常时的自动重试次数。
retryDelayMslong1000L重试时间间隔（毫秒）。
协议约束finishMarkerString自动生成任务结束的“信号灯”。模型输出此标记即视为任务完成。
promptProviderReActPromptProvider英文模板定义“思考-行动-观察”提示词模板的格式。
扩展定制interceptorReActInterceptor/生命周期拦截器，可监听思考轨迹与工具执行。

身份标识与路由 (Identity & Routing)

  • name & description：在 ReActAgent 独立运行时，这仅作为标识；但在 TeamAgent 或 Supervisor 模式下，description 是其他 Agent 识别其功能的核心依据。系统会根据描述将合适的任务分发给该 Agent。

逻辑熔断机制 (Logical Breaker)

  • maxSteps：这是生产环境下非常关键的参数。AI 有时会因为指令模糊或工具反馈异常而陷入“无限思考循环”。通过设置 maxSteps（推荐 5-10），系统会在达到阈值后强制熔断并报错，保护您的 Token 消耗和响应时效。

工具集管理 (Tool Management)

  • toolMap：使用 LinkedHashMap 实现。这确保了在发送给大模型的提示词中，工具的排列顺序是确定性的。顺序的一致性有助于模型对工具优先级的稳定理解。

任务终结协议 (Termination Protocol)

  • finishMarker：这是 ReAct 协议的锚点。默认情况下，系统会自动生成一个如 [AGENT_NAME_FINISH] 的标记。当 LLM 认为问题已完全解决，它只需在输出末尾附上此标记，ReActAgent 就会立即停止循环并提取最终答案。

可观测性扩展 (Observability)

  • interceptor：通过挂载拦截器，开发者可以实现类似于“AI 思维轨迹”的实时输出。您可以捕获每一轮的 Thought（思考内容）和 Action（调用的工具及参数），从而在前端页面展示出 AI 正在“分析”还是正在“查询数据库”。

2、ReActAgent 构建

  • 基础版：快速上手 (Minimalistic)

适用于简单的问答和基础工具调用。

// 使用 Builder 模式创建一个具备基础订单查询能力的助手
ReActAgent simpleAgent = ReActAgent.of(chatModel)
        .name("order_helper")
        .title("订单查询助手")
        .addTool(orderQueryTool) // 注入具体的 FunctionTool
        .build();

// 执行调用
String result = simpleAgent.call(FlowContext.of("order-id"), "帮我看看单号为 SN123 的物流到哪了？");
  • 进阶版：生产级配置参考

展示了如何利用源代码中的 retryConfig、maxSteps 和 interceptor 等核心参数。

ReActAgent opsAgent = ReActAgent.of(chatModel)
        // --- 1. 身份定义 (用于计算图标识及 TeamAgent 协作) ---
        .name("ops_expert")
        .title("自动化运维专家")
        .description("负责系统监控分析及故障自愈执行")

        // --- 2. 运行策略控制 (对应配置类中的策略参数) ---
        .maxSteps(8)               // 限制 Reason <-> Action 循环次数，防止死循环
        .retryConfig(3, 2000L)     // LLM 调用失败时最多重试 3 次，间隔 2 秒
        
        // --- 3. 能力注入 (挂载到计算图的 ActionTask 节点) ---
        .addTool(logSearchTool)    // 日志搜索工具
        .addTool(instanceTool)     // 实例重启工具
        
        // --- 4. 深度定制 (模型参数与提示词模板) ---
        .chatOptions(options -> {
            options.setTemperature(0.1f); // 降低温度，确保逻辑推理的确定性
        })
        .promptProvider(new MyChinesePromptProvider()) // 使用自定义中文提示词模板
        
        // --- 5. 生命周期拦截 (对应 flowEngine.addInterceptor) ---
        .interceptor(new ReActInterceptor() {
            @Override
            public void onThought(ReActTrace trace, String thought) {
                System.out.println("🤔 思考中: " + thought);
            }
            @Override
            public void onAction(ReActTrace trace, String name, Map<String, Object> args) {
                System.out.println("🛠️ 执行工具: " + name + " 参数: " + args);
            }
        })
        .build();

3、ReActInterceptor 接口参考

public interface ReActInterceptor extends FlowInterceptor {
    /**
     * 思考时触发
     */
    default void onThought(ReActTrace trace, String thought) {
    }

    /**
     * 调用工具前触发
     */
    default void onAction(ReActTrace trace, String toolName, Map<String, Object> args) {
    }

    /**
     * 工具返回结果后触发
     */
    default void onObservation(ReActTrace trace, String result) {
    }

    /**
     * 调用结束时
     */
    default void onCallEnd(FlowContext context, Prompt prompt) {

    }
}


// /////////////


public interface FlowInterceptor {
    /**
     * 拦截执行
     *
     * @param invocation 调用者
     */
    default void doFlowIntercept(FlowInvocation invocation) throws FlowException {
        invocation.invoke();
    }

    /**
     * 节点运行开始时
     */
    default void onNodeStart(FlowContext context, Node node) {

    }

    /**
     * 节点运行结束时
     */
    default void onNodeEnd(FlowContext context, Node node) {

    }
}