🎯 今日核心问题

  1. 前两周的 Agent 是「一轮工具调用 + 一轮总结」,为什么两步以上的任务就会崩?
  2. ReAct 的 Thought 字段到底是给谁看的——模型自己、还是你的调度器?
  3. 在 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: ...。很多人误以为这是让模型「自言自语增加准确率」,其实关键在结构:

所以 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 塞进去,第三轮就爆上下文。

【四】常见误区

💻 代码示例

手写 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)。