001/*
002 *  Copyright (c) 2023-2026, Agents-Flex (fuhai999@gmail.com).
003 *  <p>
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *  <p>
008 *  http://www.apache.org/licenses/LICENSE-2.0
009 *  <p>
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package com.agentsflex.core.agent.react;
017
018import com.agentsflex.core.message.UserMessage;
019import com.agentsflex.core.model.chat.tool.Tool;
020import com.agentsflex.core.message.Message;
021
022import java.util.List;
023
024public class ReActMessageBuilder {
025
026
027    /**
028     * 构建 ReAct 开始消息
029     *
030     * @param prompt    提示词
031     * @param tools 函数列表
032     * @param userQuery 用户问题
033     * @return 返回 HumanMessage
034     */
035    public Message buildStartMessage(String prompt, List<Tool> tools, String userQuery) {
036        UserMessage message = new UserMessage(prompt);
037        message.addMetadata("tools", tools);
038        message.addMetadata("user_input", userQuery);
039        message.addMetadata("type", "reActWrapper");
040        return message;
041    }
042
043
044    /**
045     * 构建 JSON 解析错误消息，用于 json 发送错误时，让 AI 自动修正
046     *
047     * @param e    错误信息
048     * @param step 发送错误的步骤
049     * @return 返回 HumanMessage
050     */
051    public Message buildJsonParserErrorMessage(Exception e, ReActStep step) {
052        String errorMsg = "JSON 解析失败: " + e.getMessage() + ", 原始内容: " + step.getActionInput();
053        String observation = "Action：" + step.getAction() + "\n"
054            + "Action Input：" + step.getActionInput() + "\n"
055            + "Error：" + errorMsg + "\n"
056            + "请检查你的 Action Input 格式是否正确，并纠正 JSON 内容重新生成响应。\n";
057        UserMessage userMessage = new UserMessage(observation + "请继续推理下一步。");
058        userMessage.addMetadata("type", "reActObservation");
059        return userMessage;
060    }
061
062    /**
063     * 构建 Observation 消息，让 AI 自动思考
064     *
065     * @param step   步骤
066     * @param result 步骤结果
067     * @return 步骤结果消息
068     */
069    public Message buildObservationMessage(ReActStep step, Object result) {
070        String observation = buildObservationString(step, result);
071        UserMessage userMessage = new UserMessage(observation + "\n请继续推理下一步。");
072        userMessage.addMetadata("type", "reActObservation");
073        return userMessage;
074    }
075
076
077    /**
078     * 构建 Observation 字符串
079     *
080     * @param step   步骤
081     * @param result 步骤结果
082     * @return 步骤结果字符串
083     */
084    public static String buildObservationString(ReActStep step, Object result) {
085        return "Action：" + step.getAction() + "\n" +
086            "Action Input：" + step.getActionInput() + "\n" +
087            "Action Result：" + result + "\n";
088    }
089
090    /**
091     * 构建 Action 错误消息，用于 Action 错误时，让 AI 自动修正
092     *
093     * @param step 步骤
094     * @param e    错误信息
095     * @return 错误消息
096     */
097    public Message buildActionErrorMessage(ReActStep step, Exception e) {
098        // 将错误信息反馈给 AI，让其修正
099        String observation = buildObservationString(step, "Error: " + e.getMessage()) + "\n"
100            + "请根据错误信息调整参数并重新尝试。\n";
101        UserMessage userMessage = new UserMessage(observation + "请继续推理下一步。");
102        userMessage.addMetadata("type", "reActObservation");
103        return userMessage;
104    }
105}