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.model.client.StreamContext;
019import com.agentsflex.core.model.chat.tool.Tool;
020import com.agentsflex.core.model.chat.response.AiMessageResponse;
021
022import java.util.List;
023
024/**
025 * ReActAgent 的监听器接口，用于监听执行过程中的关键事件。
026 */
027public interface ReActAgentListener {
028
029    /**
030     * 当 LLM 生成响应时触发
031     *
032     * @param response 原始响应内容
033     */
034    default void onChatResponse(AiMessageResponse response) {
035    }
036
037    /**
038     * 当 LLM 生成响应时触发
039     *
040     * @param context  上下文信息
041     * @param response 原始响应内容
042     */
043    default void onChatResponseStream(StreamContext context, AiMessageResponse response) {
044    }
045
046
047    /**
048     * 当未命中工具时触发
049     *
050     * @param response 原始响应内容
051     */
052    default void onNonActionResponse(AiMessageResponse response) {
053    }
054
055    /**
056     * 当未命中工具时触发
057     */
058    default void onNonActionResponseStream(StreamContext context) {
059    }
060
061
062    /**
063     * 当检测到最终答案时触发
064     *
065     * @param finalAnswer 最终答案内容
066     */
067    default void onFinalAnswer(String finalAnswer) {
068    }
069
070
071    /**
072     * 当需要用户输入时触发
073     */
074    default void onRequestUserInput(String question) {
075
076    }
077
078    /**
079     * 当调用工具前触发
080     *
081     * @param step 当前步骤
082     */
083    default void onActionStart(ReActStep step) {
084    }
085
086    /**
087     * 当调用工具完成后触发
088     *
089     * @param step   工具名称
090     * @param result 工具返回结果
091     */
092    default void onActionEnd(ReActStep step, Object result) {
093    }
094
095    /**
096     * 当达到最大迭代次数仍未获得答案时触发
097     */
098    default void onMaxIterationsReached() {
099    }
100
101
102    /**
103     * 当解析步骤时发生错误时触发
104     *
105     * @param content 错误内容
106     */
107    default void onStepParseError(String content) {
108
109    }
110
111    /**
112     * 当未匹配到任何工具时触发
113     *
114     * @param step      当前步骤
115     * @param tools 可用的工具列表
116     */
117    default void onActionNotMatched(ReActStep step, List<Tool> tools) {
118
119    }
120
121    /**
122     * 当工具执行错误时触发
123     *
124     * @param e 错误对象
125     */
126    default void onActionInvokeError(Exception e) {
127
128    }
129
130    /**
131     * 当工具返回的 JSON 格式错误时触发
132     *
133     * @param step  当前步骤
134     * @param error 错误对象
135     */
136    default void onActionJsonParserError(ReActStep step, Exception error) {
137
138    }
139
140    /**
141     * 当发生异常时触发
142     *
143     * @param error 异常对象
144     */
145    default void onError(Exception error) {
146    }
147
148
149}