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

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

| 分类 | 参数名称 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| **身份定义** | `name` | String | `simple_agent` | 智能体唯一标识，用于日志识别及会话历史存储。 |
| | `role` | String | / | 核心字段。角色描述，帮助模型识别自身角色或供团队调度。 |
| | `profile` | AgentProfile | / | 核心字段。挡案描述，帮助模型识别自身角色或供团队调度。 |
| **决策大脑** | `chatModel` | ChatModel | / | 执行物理调用的核心模型。与 `handler` 二选一。 |
| | `handler` | AgentHandler | / | **回退方案**。不使用 LLM 时，可自定义逻辑处理器。 |
| | `modelOptions` | Consumer | / | 用于精细控制模型参数（如 TopP、Temperature 等）。 |
| | `instruction` | String | / | 核心指令。告诉模型要怎么做，要注意什么。 |
| **执行控制** | `maxRetries` | int | 3 | 模型调用失败（如网络超时）后的最大自动重试次数。 |
| | `retryDelayMs` | long | 1000L | 采用指数退避算法的重试基础延迟（毫秒）。 |
| | `sessionWindowSize`| int | 5 | **记忆深度**。自动回溯并注入当前上下文的历史消息轮数。 |
| **输出约束** | `outputKey` | String | / | 任务结束后的结果自动回填至 `FlowContext` 的键名。 |
| | `outputSchema` | String/Type | / | **强制约束**。结构化输出。注入 JSON Schema 指令并开启 `json_object` 响应模式。 |
| **扩展定制** | `interceptors` | `List<SimpleInterceptor>` | / | 生命周期拦截器。支持监控、审计、或对消息进行二次加工。 |
| | `tools` | `Map<String, FunctionTool>` | / | 工具。 |
| | `toolContext` | `Map` | / | 工具调用时共享的上下文数据（如数据库连接、用户信息）。 |
| | `skills` | `List<Skill>` | / | 技能。 |


关键配置点补充说明

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


### 2、SimpleAgent 构建

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

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

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

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

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

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

```java
// 创建一个用户信息解析器
SimpleAgent userParser = SimpleAgent.of(chatModel)
        // --- 1. 基础定义 ---
        .name("user_parser")
        .retryConfig(3, 1500L) // 增强容错能力
        
        // --- 2. 注入业务工具 ---
        .defaultToolAdd(new UserCheckTool()) 
        .defaultToolContextPut("db_id", 1) // 注入工具运行环境参数
        
        // --- 3. 强制 JSON 输出 ---
        .outputSchema(UserDto.class)   // 自动生成 JSON Schema 指令
        .outputKey("parsed_user")      // 结果自动存入上下文
        
        // --- 4. 链路监控 ---
        .defaultInterceptorAdd(new SimpleInterceptor() {
            @Override
            public ChatResponse interceptCall(ChatRequest req, CallChain chain) throws IOException {
                LOG.info("开始处理...");
                return chain.doIntercept(req);
            }
        })
        .build();

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


### 3、SimpleAgent 运行流程


SimpleAgent 的内部执行逻辑如下：

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


### 4、SimpleInterceptor 接口参考

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


SimpleInterceptor

```java
package org.noear.solon.ai.agent.simple;

import org.noear.solon.ai.agent.AgentInterceptor;
import org.noear.solon.ai.chat.interceptor.ChatInterceptor;
import org.noear.solon.lang.Preview;

/**
 * 简单智能体拦截器
 */
public interface SimpleInterceptor extends AgentInterceptor, ChatInterceptor {
}
```

ChatInterceptor

```java
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 Flux<ChatResponse> interceptStream(ChatRequest req, StreamChain chain) {
        return chain.doIntercept(req);
    }
}
```