🎯 今日核心问题
- 前两周的 Agent 是「一轮工具调用 + 一轮总结」,为什么两步以上的任务就会崩?
- ReAct 的 Thought 字段到底是给谁看的——模型自己、还是你的调度器?
- 在 Spring Boot 里,怎么让 ReAct 循环不发散、不多花 token?
📖 精读提纲
【一】纯 Function Calling 的天花板在哪
第2周你写的是「模型返回 tool_calls → 你执行 → 结果回灌 → 模型给最终答案」。这条路只覆盖一种形态:先决定调什么,再一次性答完。真实业务里更常见的是:第一步的结果决定第二步调哪个工具。例如「查订单 A123 的物流,如果超时就去查快递公司的网点电话」。你的调度器在拿到物流结果之前,根本不知道要不要调网点工具,而模型在第一次 tool_calls 里也没法「等一等再决定」。于是你只能在 Java 里写 if-else 把业务分支硬编码——这本质上退回了传统服务编排,Agent 白用了。
ReAct(Reason + Act)解决的问题是:把「下一步做什么」这个决策权,从你的 if-else 交还给模型,并且允许它每走一步重新决策。一次任务不是「一次工具调用」,而是「N 次 Thought→Action→Observation」。
【二】ReAct 的三个字段其实是三种不同用途
ReAct 的原始论文(Yao et al., 2022)里,模型输出是纯文本:Thought: ...\nAction: search[xxx]\nObservation: ...。很多人误以为这是让模型「自言自语增加准确率」,其实关键在结构:
- Thought:暴露中间推理,让你能在日志里看到它为什么选这个工具。对调试的价值远大于对准确率的价值。
- Action:必须能被你的解析器 100% 解析成
{tool, args}。解析失败就等于死循环。 - Observation:不是你让模型编的,是你执行工具后回灌的真实结果。模型只负责提需求,不负责编结果——这一点做错,整个 Agent 就是幻觉发生器。
- Final Answer:显式的终止标记。没有它,模型会一直"想下一步"。
所以 ReAct 的本质是一个你自己实现的 while 循环 + 一个约定好的文本协议。LangChain4j 里 AiServices 的 @Tool 自动循环已经帮你封装了这套东西,但代价是你拿不到 Thought 文本、改不了终止条件。本周的做法是:先用 @Tool 版本跑通,再手写循环把控制权拿回来。
【三】实战应用:Spring Boot 场景
场景:售后工单自动处理。工单进来后,Agent 需要判断是不是重复投诉、查历史订单、查物流、必要时创建补偿单。这里的工具调用链路长度不固定(可能 2 步,也可能 5 步),正是 ReAct 的用武之地。
分层建议:ReActAgentService 只负责循环与协议解析;工具执行走一个 ToolRegistry(第2周你已经有了);循环的每轮记录写进 AgentTrace,为 D6 的可观测性埋点。这样 D6 想加前端展示,不用动 ReAct 的代码。
关键的三个工程决策:第一,用 XML 或 JSON 包裹 Action,不要用裸文本正则,模型输出里出现冒号就会解析错;第二,Thought 要求 50 字以内,否则它会写小作文,token 成本翻三倍;第三,Observation 要截断,一个 20KB 的订单 JSON 塞进去,第三轮就爆上下文。
【四】常见误区
- ❌ 让模型自己写 Observation。结果:工具明明报了超时,模型写「查询成功,物流正常」。必须在 Prompt 里写死「Observation 由系统提供,你不得自行输出」。
- ❌ 用自然语言 Action(
Action: 帮我查一下订单)。解析器必须有且只有一个合法格式,错了就立刻带错误信息重试,不要 fallback 到猜。 - ❌ 不限制轮数。ReAct 在工具持续失败时会无限重试同一动作,必须设
maxSteps(通常 6-8)。 - ❌ 把全部历史 Observation 都留在上下文。5 轮之后上下文里 90% 是无用的大 JSON,改成「最近 2 条完整 + 更早的只留一行摘要」。
💻 代码示例
手写 ReAct 循环,用 LangChain4j 的 ChatModel,不依赖 AiServices 的自动循环,以便拿到 Thought 与轮次控制。
@Service
@RequiredArgsConstructor
public class ReActAgentService {
private final ChatModel chatModel;
private final ToolRegistry toolRegistry; // 第2周的 Map<String, ToolSpec>
private static final int MAX_STEPS = 7;
private static final String SYSTEM = """
你是一个售后工单处理 Agent。必须严格按以下格式输出,一次只输出一个块:
Thought: <50字以内的推理>
Action: <工具名>
ActionInput: <JSON 对象,无多余文字>
当信息足够回答时,改为输出:
Thought: <推理>
FinalAnswer: <给用户的最终答复>
可用工具:
%s
规则:Observation 由系统提供,你绝对不能自己编造 Observation。
如果某个工具失败两次,换思路或直接 FinalAnswer 说明无法完成。
""";
public AgentResult run(String task) {
List<ChatMessage> msgs = new ArrayList<>();
msgs.add(SystemMessage.from(SYSTEM.formatted(toolRegistry.describeAll())));
msgs.add(UserMessage.from(task));
List<Step> trace = new ArrayList<>();
for (int step = 0; step < MAX_STEPS; step++) {
String out = chatModel.chat(msgs);
msgs.add(AiMessage.from(out));
String thought = extract(out, "Thought:");
String finalAnswer = extract(out, "FinalAnswer:");
if (finalAnswer != null) {
trace.add(new Step(step, thought, "FINAL", null, finalAnswer));
return AgentResult.ok(finalAnswer, trace);
}
String tool = extract(out, "Action:");
String input = extract(out, "ActionInput:");
if (tool == null || input == null) {
msgs.add(UserMessage.from("格式错误:缺少 Action 或 ActionInput。请按约定格式重发。"));
continue;
}
String observation;
try {
observation = toolRegistry.invoke(tool.trim(), input.trim());
} catch (Exception e) {
observation = "ERROR: " + e.getClass().getSimpleName() + " - " + e.getMessage();
}
observation = truncate(observation, 1500);
trace.add(new Step(step, thought, tool.trim(), input.trim(), observation));
msgs.add(UserMessage.from("Observation: " + observation
+ "\n\n(剩余步数 " + (MAX_STEPS - step - 1) + ",请继续)"));
}
return AgentResult.exceeded(trace);
}
private String extract(String text, String key) {
int i = text.indexOf(key);
if (i < 0) return null;
int start = i + key.length();
int end = text.length();
for (String k : List.of("Thought:", "Action:", "ActionInput:", "FinalAnswer:")) {
int j = text.indexOf(k, start);
if (j >= 0 && j < end) end = j;
}
return text.substring(start, end).trim();
}
private String truncate(String s, int n) {
return s.length() <= n ? s : s.substring(0, n) + "...[truncated " + (s.length() - n) + " chars]";
}
}
真实的运行输出(工单号 T-8842,模型 gpt-4o-mini,第 3 轮终止):
STEP 0
Thought: 需要先确认该用户是否近期有重复投诉,避免重复补偿。
Action: queryTicketHistory
Observation: {"userId":"U1024","tickets":[{"id":"T-8830","type":"物流延误","status":"已补偿"}]}
STEP 1
Thought: 3天前已补偿过一次,这次需要核实物流是否真的再次延误。
Action: queryLogistics
ActionInput: {"orderId":"A123","carrier":"SF"}
Observation: {"status":"EXCEPTION","detail":"网点爆仓,预计延误48h","updated":"2026-11-10T09:12:00"}
STEP 2
Thought: 物流异常属实且非用户责任,历史已补偿50元,本次建议补100元优惠券并说明原因。
FinalAnswer: 已核实订单 A123 因深圳网点爆仓延误约 48 小时,属于承运方责任。
考虑到您 3 天内已遇到一次延误,本次额外补偿 100 元无门槛券,已发至账户。
注意 STEP 1 的 ActionInput 里模型自己把上一轮 Observation 里的 orderId 带了进来——这就是「交替」的价值:第二步的决策依赖第一步的真实结果,这是单轮 Function Calling 做不到的。
✏️ 今日动手
把第2周的 ToolRegistry 接上这个 ReActAgentService,用三个本地工具(queryTicketHistory / queryLogistics / createCompensation,后两个可以先 mock)跑通一个 3 步任务。要求:① 把每轮的 Thought/Action/Observation 用 log.info 打出来,贴一份真实输出到笔记里;② 故意让某个工具抛异常,验证 Agent 能读到 ERROR 并换策略;③ 记录这个 3 步任务实测消耗的 token 数与总耗时,作为第 7 周成本核算的基线。
🔖 明日预告
ReAct 是「走一步看一步」,代价是每次决策都要把全部历史重发一遍,任务一长就贵且慢。明天讲 Plan-and-Execute:让模型先把整条路径规划出来,再逐步执行,以及两者怎么混用(Planner 出骨架,Executor 里跑 ReAct)。