
ReActAgent有何不同?
传统LLM擅长生成文本,但在与现实世界交互,如查数据库、拉取实时数据、做计算时就无能为力。`ReActAgent`(Reason + Act)打破了这一局限,实现了一个认知循环:思考 → 行动 → 观察 →(重复或结束)。Agent先思考下一步行动,接着行动(调用工具),再观察结果,最后决定继续还是交出最终答案。Solon AI的`ReActAgent`已在自动客服、智能数据分析、多步工作流自动化等生产场景中得到验证。
1. 添加依赖
首先,在项目中添加 `solon - ai - agent` 模块:
<dependency>
<groupId>org.noear</groupId>
<artifactId>solon-ai-agent</artifactId>
</dependency>若使用了Solon的父POM,版本会自动管理;否则需指定最新的Solon版本。
2. 构建ChatModel(Agent的大脑)
每个Agent都需要一个负责推理的“大脑”——`ChatModel`。可以用Builder API快速构建:
import org.noear.solon.ai.chat.ChatModel;
ChatModel chatModel = ChatModel.of("https://api.moark.com/v1/chat/completions")
.apiKey("your-api-key-here")
.model("Qwen3-32B")
.build();也可通过YAML配置后注入:
solon.ai.chat:
demo:
apiUrl: "http://127.0.0.1:11434/api/chat"
provider: "ollama"
model: "llama3.2"
@Inject("${solon.ai.chat.demo}")
ChatModel chatModel;
3. Hello World:你的第一个ReActAgent
先从一个简单例子开始,创建一个获取时间的工具和一个基础Agent:
import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.annotation.Param;
import org.noear.solon.ai.chat.tool.AbsToolProvider;
import java.time.LocalDateTime;
// 1. 定义工具
public class TimeTool extends AbsToolProvider {
@ToolMapping(description = "获取当前的日期和时间")
public String getCurrentTime() {
return LocalDateTime.now().toString();
}
}
// 2. 构建并运行Agent
public class HelloAgent {
public static void main(String[] args) throws Throwable {
ChatModel chatModel = ChatModel.of("https://api.moark.com/v1/chat/completions")
.apiKey("***")
.model("Qwen3-32B")
.build();
ReActAgent agent = ReActAgent.of(chatModel)
.role("你是一个可以查询时间的助手。")
.defaultToolAdd(new TimeTool())
.build();
String response = agent.prompt("现在几点了?")
.call()
.getContent();
System.out.println(response);
}
}运行时,Agent会:
1. 思考:“用户想知道时间,我有一个 `getCurrentTime` 工具”
2. 行动:调用 `getCurrentTime()`
3. 观察:拿到时间戳
4. 回答:“当前时间是2026 - 07 - 04T14:30:22……”
4. 实战:客服支持Agent
构建一个更实用的场景——支持查询订单和库存的客服Agent。
#### 第1步:定义工具
import org.noear.solon.ai.chat.tool.AbsToolProvider;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.annotation.Param;
public class OrderTool extends AbsToolProvider {
@ToolMapping(description = "根据订单ID查询订单状态")
public String getOrderStatus(@Param(description = "订单ID") String orderId) {
// 模拟数据库查询
if ("ORD-1001".equals(orderId)) {
return "订单ORD-1001:已发货,预计7月7日送达";
} else if ("ORD-1002".equals(orderId)) {
return "订单ORD-1002:待处理,付款未确认";
}
return "未找到订单:" + orderId;
}
@ToolMapping(description = "根据商品ID查询库存")
public String checkInventory(@Param(description = "商品SKU") String sku) {
if ("SKU-A100".equals(sku)) {
return "库存充足:42件";
} else if ("SKU-B200".equals(sku)) {
return "库存紧张:仅剩3件";
}
return "未找到商品:" + sku;
}
}
#### 第2步:构建Agent
ReActAgent supportAgent = ReActAgent.of(chatModel)
.name("customer_support")
.role("客服支持Agent----处理订单查询和库存检查。")
.defaultToolAdd(new OrderTool())
.maxTurns(8) // 最大推理步数
.autoRethink(true) // 卡住时自动重新思考
.retryConfig(3, 1000L) // 重试3次,间隔1秒
.modelOptions(options -> {
options.temperature(0.1); // 低温度,确定性决策
})
.build();
String result = supportAgent.prompt("客户ORD-1002想知道订单什么时候到,能帮忙查一下吗?")
.call()
.getContent();
System.out.println(result);Agent会:
1. 意识到需要查 `ORD-1002`
2. 调用 `getOrderStatus("ORD-1002")`
3. 读到结果:“待处理,付款未确认”
4. 向客户解释:付款尚未确认,所以还未发货
5. 添加拦截器:可观测性
生产环境中,需要看到Agent的思考过程。`ReActInterceptor`提供了完整的生命周期钩子:
import org.noear.solon.ai.agent.react.ReActInterceptor;
import org.noear.solon.ai.agent.react.ReActTrace;
import org.noear.solon.ai.agent.react.task.ToolExchanger;
ReActAgent observableAgent = ReActAgent.of(chatModel)
.name("observable_agent")
.role("我帮你处理各种任务。")
.defaultToolAdd(new OrderTool())
.defaultInterceptorAdd(new ReActInterceptor() {
@Override
public void onAgentStart(ReActTrace trace) {
System.out.println("🤖 Agent启动。提示词:" + trace.getOriginalPrompt().getUserContent());
}
@Override
public void onThought(ReActTrace trace, String thoughtContent,
AssistantMessage assistantMessage) {
System.out.println("💭 思考:" + thoughtContent);
}
@Override
public void onAction(ReActTrace trace, ToolExchanger toolExchanger) {
System.out.println("🛠️ 工具:" + toolExchanger.getToolName()
+ ",参数:" + toolExchanger.getArgs());
}
@Override
public void onObservation(ReActTrace trace, ToolExchanger toolExchanger,
ChatMessage observation, Throwable error,
long durationMs) {
if (error != null) {
System.err.println("❌ 工具调用失败:" + error.getMessage());
} else {
System.out.println("✅ 工具结果返回,耗时 " + durationMs + "ms");
}
}
@Override
public void onAgentEnd(ReActTrace trace) {
System.out.println("✅ Agent任务完成。");
}
})
.build();这样就有了Agent每次决策的完整审计轨迹。
6. 流式响应
对于长时间运行的任务,使用 `stream()` 获取实时输出:
agent.prompt("分析我们的Top 10商品,给我一份销售摘要。")
.stream()
.doOnNext(resp -> {
System.out.print(resp.getMessage().getContent());
})
.doOnComplete(() -> {
System.out.println("\n✅ 分析完成!");
})
.subscribe();
7. 进阶:单次调用选项
通过 `.options()` 可以为单次调用调整行为:
agent.prompt("分析这个复杂数据集,生成JSON报告。")
.session(mySession) // 复用已有会话
.options(o -> o
.maxTurns(15) // 复杂任务给更多步数
.planningMode(true) // 启用规划阶段
.temperature(0.3) // 平衡创造性与精确性
.outputSchema("{\"type\":\"object\",\"properties\":{...}}" // 结构化输出
.toolAdd(new ReportingTool()) // 临时添加一个工具
)
.call();
#### 选项一览
| 分类 | 方法 | 说明 | 默认值 |
| --- | --- | --- | --- |
| 控制 | `maxTurns(int)` | 最大推理步数 | 8 |
| 控制 | `autoRethink(boolean)` | 自动重新思考 | false |
| 控制 | `retryConfig(int, long)` | 重试次数与间隔 | 3, 1000ms |
| 模型 | `temperature(double)` | 随机性(0 - 2) | 0.5 |
| 模型 | `max_tokens(long)` | 最大生成Token | -- |
| 工具 | `toolAdd(FunctionTool)` | 临时添加工具 | -- |
| 工具 | `talentAdd(Talent)` | 添加技能模块 | -- |
| 扩展 | `interceptorAdd(interceptor)` | 添加拦截器 | -- |
8. 会话与轨迹(Sessions & Traces)
`ReActAgent`的会话支持带记忆的长时间对话:
import org.noear.solon.ai.agent.session.InMemoryAgentSession;
import org.noear.solon.ai.agent.AgentSession;
// 创建或复用会话
AgentSession session = InMemoryAgentSession.of("user-session-123");
// 第一轮
String r1 = agent.prompt("帮我找找50元以下的商品")
.session(session)
.call()
.getContent();
// 第二轮(Agent记得上下文)
String r2 = agent.prompt("最便宜的那个运费多少?")
.session(session)
.call()
.getContent();
// 查看轨迹
ReActTrace trace = agent.getTrace(session);
System.out.println("总步数:" + trace.getStepCount());
// 或获取格式化摘要
System.out.println(trace.getFormattedHistory());Trace对象提供:
- 完整的思考/行动/观察历史(`getFormattedHistory()`)
- 步数和指标(`getStepCount()`、`getMetrics()`)
- 工具调用参数和结果
- 原始提示词和会话(`getOriginalPrompt()`、`getSession()`)
9. 轻量模型的STRUCTURED_TEXT模式
不是所有模型都原生支持工具调用。`ReActAgent`支持 **Text ReAct模式**,它通过正则从模型输出的文本中提取 `Action: {json}` 标签来执行工具,这使得它兼容更小、更轻量的模型,适合边缘部署和对成本敏感的场景。执行风格(`ReActStyle`)在构建时通过 `ReActAgentConfig` 配置,可选择 `ReActStyle.NATIVE_TOOL`(原生工具调用,默认)和轻量的 `ReActStyle.STRUCTURED_TEXT`(结构化文本)。使用STRUCTURED_TEXT模式时,Agent从模型输出中解析 `Action: {json}` 标签并执行对应的工具。
完整示例:电商支持Agent
可直接复制运行的完整代码:
import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.agent.react.ReActInterceptor;
import org.noear.solon.ai.agent.react.ReActTrace;
import org.noear.solon.ai.agent.react.task.ToolExchanger;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.annotation.Param;
import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.tool.AbsToolProvider;
import org.noear.solon.ai.chat.message.ChatMessage;
public class ECommerceSupportApp {
public static void main(String[] args) throws Throwable {
// 1. 构建模型
ChatModel model = ChatModel.of("https://api.moark.com/v1/chat/completions")
.apiKey("${API_KEY}")
.model("Qwen3-32B")
.build();
// 2. 构建Agent
ReActAgent agent = ReActAgent.of(model)
.name("ecommerce_support")
.role("电商客服支持Agent")
.defaultToolAdd(new OrderTool())
.defaultToolAdd(new InventoryTool())
.defaultInterceptorAdd(new LoggingInterceptor())
.defaultInterceptorAdd(new ContextCompressionInterceptor(...)) //【可选】如果轮数过多,需要压缩上下文
.maxTurns(10)
.autoRethink(true)
.build();
// 3. 运行
String answer = agent.prompt(
"客户想下单SKU-A100,但发现ORD-1001还没收到。查一下两个情况,给客户解释。"
).call().getContent();
System.out.println(answer);
}
}
// 工具
class OrderTool extends AbsToolProvider {
@ToolMapping(description = "根据订单ID查询订单状态")
public String getOrderStatus(@Param(description = "订单ID") String orderId) {
return "ORD-1001:已发货";
}
}
class InventoryTool extends AbsToolProvider {
@ToolMapping(description = "根据SKU查询商品库存")
public String checkStock(@Param(description = "商品SKU") String sku) {
return "SKU-A100:42件库存充足";
}
}
// 拦截器
class LoggingInterceptor implements ReActInterceptor {
@Override
public void onThought(ReActTrace trace, String thought,
AssistantMessage msg) {
System.out.println("💭 " + thought);
}
@Override
public void onAction(ReActTrace trace, ToolExchanger tool) {
System.out.println("🛠️ " + tool.getToolName());
}
}
要点总结
1. **ReActAgent** 遵循 **思考 -> 行动 -> 观察** 循环,可实现推理、行动、学习
2. **工具** 通过 `@ToolMapping` 和 `@Param` 注解定义,就是普通的POJO
3. **拦截器** 让你对Agent的决策过程有完整的可观测性
4. **单次调用选项** 让你在不重建Agent的前提下灵活调整行为
5. **Text ReAct模式** 兼容不支持原生工具调用的轻量模型
6. **会话和轨迹** 支持带完整审计日志的持久化对话
279



被折叠的 条评论
为什么被折叠?



