simple - SimpleAgent 配置与构建

SimpleAgent 是 Solon AI 中最轻量级的智能体实现。不同于 ReAct 模式的复杂推理循环，它专注于 “直接响应”。通过指令增强、自动重试、历史窗口管理以及强制 JSON 约束等特性，它非常适合处理确定性高、逻辑直接的任务。

1、SimpleAgent 配置参考（可参考 SimpleAgentConfig 字段）

关键配置点补充说明

• 关于输出约束 (outputSchema)：当配置了 outputSchema 时，SimpleAgent 会自动在 System Prompt 中追加 [IMPORTANT: OUTPUT FORMAT REQUIREMENT] 指令，并尝试开启模型的 response_format: {type: "json_object"} 模式（需模型支持）。
• 关于自动重试：重试机制采用了简单的指数延迟，即：retryDelayMs * (retry_count + 1)，有效应对网络抖动或模型瞬时限流。
• 关于历史窗口：SimpleAgent 会自动从 AgentSession 中拉取最近的 N 条对话记录，无需开发者手动拼接上下文，实现了开箱即用的多轮对话能力。

2、SimpleAgent 构建

• 基础版：极简任务处理器

适用于单一职责的对话或指令执行场景。

// 创建一个中英文润色专家
SimpleAgent polisher = SimpleAgent.of(chatModel)
        .name("polisher")
        .description("负责润色用户的文本，使其更符合学术规范")
        .systemPrompt(ctx -> "你是一个学术翻译专家。请直接返回修改后的文本。")
        .historyWindowSize(3) // 维持简单的上下文记忆
        .build();

// 发起调用
String result = polisher.prompt("The weather is very good today.")
                        .call()
                        .getContent();                     

• 进阶版：具备工具调用与 JSON 强约束

适用于作为业务逻辑中的“结构化数据处理器”。

// 创建一个用户信息解析器
SimpleAgent userParser = SimpleAgent.of(chatModel)
        // --- 1. 基础定义 ---
        .name("user_parser")
        .retryConfig(3, 1500L) // 增强容错能力
        
        // --- 2. 注入业务工具 ---
        .toolAdd(new UserCheckTool()) 
        .defaultToolsContextPut("db_id", 1) // 注入工具运行环境参数
        
        // --- 3. 强制 JSON 输出 ---
        .outputSchema(UserDto.class)   // 自动生成 JSON Schema 指令
        .outputKey("parsed_user")      // 结果自动存入上下文
        
        // --- 4. 链路监控 ---
        .defaultInterceptorAdd((index, invocation) -> {
            LOG.info("SimpleAgent 开始处理...");
            invocation.invoke();
        })
        .build();

// 执行调用
userParser.prompt("我叫张三，今年25岁，住在上海").call();

3、SimpleAgent 运行流程

SimpleAgent 的内部执行逻辑如下：

• 组装消息：合并 SystemPrompt + OutputSchema 指令 + HistoryWindow (从 Session) + CurrentPrompt。
• 消息归档：将当前请求立即存入 AgentSession 历史。
• 物理调用：根据重试配置调用 ChatModel 或回退到自定义 Handler。
• 状态回填：如果配置了 outputKey，将结果写入 FlowContext 快照。
• 会话更新：将 AssistantMessage 存入历史并持久化 Session。

4、ChatInterceptor 接口参考

在 SimpleAgent 中，拦截器可以对请求和响应进行切面处理：

package org.noear.solon.ai.chat.interceptor;

import org.noear.solon.ai.chat.ChatRequest;
import org.noear.solon.ai.chat.ChatResponse;
import org.reactivestreams.Publisher;

import java.io.IOException;

/**
 * 聊天拦截器
 *
 * @author noear
 * @since 3.3
 */
public interface ChatInterceptor extends ToolInterceptor {
    /**
     * 拦截 Call 请求
     *
     * @param req   请求
     * @param chain 拦截链
     */
    default ChatResponse interceptCall(ChatRequest req, CallChain chain) throws IOException {
        return chain.doIntercept(req);
    }

    /**
     * 拦截 Stream 请求
     *
     * @param req   请求
     * @param chain 拦截链
     */
    default Publisher<ChatResponse> interceptStream(ChatRequest req, StreamChain chain) {
        return chain.doIntercept(req);
    }
}