🎯 今日核心问题

  1. Agent 的一轮循环里,"模型在想"和"代码在执行"是怎么交替的?谁在什么时候交出控制权?
  2. Think / Act / Observe / Repeat 四个阶段,分别对应你 Spring Boot 代码里的哪一行?
  3. 为什么"观察"(工具返回值)必须以原始数据回灌,而不能塞一句"查到了"了事?

📖 精读提纲

【一】四个阶段的精确分工

Think(思考):把当前完整消息链丢给模型,模型输出两选一——要么一段自然语言(任务完成或反问用户),要么一个工具调用请求(tool_calls 数组)。注意:模型在这一步没有执行任何东西,它只是"说"了一句"我要调 queryWeather,参数 city=杭州"。这句话本身是文本,不是调用。

Act(行动):你的代码解析这段 JSON,找到 Spring 容器里对应的 Bean 方法,真去执行。这是整个循环里唯一有真实副作用的一步:发 HTTP、查库、写文件都发生在这里。执行的合法性、权限、超时、重试全归你管,模型不参与。

Observe(观察):把工具的返回值(原始 JSON、异常堆栈、空结果都算)包装成一条 role=tool 的消息,追加进消息链。这一步的关键是如实回灌——模型下一轮做决策的唯一依据就是这条消息。

Repeat:回到 Think,带上变长的消息链再请求一次。循环由代码驱动,决策由模型给出。这是必须建立的心智模型:没有"模型自己循环"这回事,永远是你的 for/while 在转,模型只是每一轮被问一次。

【二】控制权交接:一次典型的三轮往返

用户问"杭州今天要带伞吗"。第一轮 Think:模型看到工具清单里有 queryWeather 和 queryForecast,选择调前者。Act:你调天气 API 拿到 {"city":"杭州","weather":"小雨","temp":18}。Observe:这条 JSON 进消息链。

第二轮 Think:模型看到是小雨,可能直接判定"要带伞"就收尾,也可能再调 queryForecast 查未来 6 小时。所以循环次数不固定——简单任务 1-2 轮,复杂任务 5-8 轮。这直接引出 D5 的核心问题:什么时候强制收手。

还有一个容易忽略的点:多工具可以并行。如果模型一次性输出两个 tool_calls(查天气 + 查空气质量),聪明的实现会用 CompletableFuture 并行执行,再把两条 observe 一起回灌。串行执行会让延迟翻倍。

【三】实战应用:Spring Boot 场景——把循环写成可观测的状态机

直接在 Service 里写 for 循环能跑,但线上排查困难。推荐把四个阶段显式化:定义一个 AgentStep 枚举(THINK / ACT / OBSERVE / DONE),每轮产出一个 StepRecord{step, phase, payload, costMs},存进 List<StepRecord> 一起返回。这样 Controller 可以返回 {answer, steps:[...]},前端能画出"思考链",你也能在日志里一眼看出卡在哪个阶段。

另外,Think 阶段的超时(模型慢)和 Act 阶段的超时(下游接口慢)要分开配置:模型调用一般给 60s,工具调用按下游 SLA 给 3-5s 并加熔断。两者的失败语义完全不同——模型超时要重试整轮,工具超时则应该把"工具超时"这个事实回灌给模型让它换个思路。

循环体务必放异步线程,别在 Tomcat 工作线程上跑 8 轮共 40 秒的推理,连接会打满。生产做法:接口返回 taskId,Agent 在 @Async 线程池或消息队列里跑,前端轮询或走 SSE 推步骤。

【四】常见误区

💻 代码示例

public enum AgentPhase { THINK, ACT, OBSERVE, DONE }

public record StepRecord(int step, AgentPhase phase, String payload, long costMs) {}

@Service
@RequiredArgsConstructor
@Slf4j
public class LoopAgentService {
    private final OpenAiChatModel model;
    private final ToolRegistry toolRegistry;      // name -> (argsJson) -> String
    private final SessionStore sessionStore;
    private static final int MAX_STEPS = 6;

    public AgentResult run(String sessionId, String userText) {
        List<Message> msgs = sessionStore.load(sessionId);
        msgs.add(Message.user(userText));
        List<StepRecord> trace = new ArrayList<>();

        for (int i = 1; i <= MAX_STEPS; i++) {
            // ── Think ──
            long t0 = System.nanoTime();
            AiMessage reply = model.chat(msgs);
            msgs.add(reply);
            trace.add(new StepRecord(i, AgentPhase.THINK,
                    reply.hasToolExecutionRequests() ? "tool_calls" : "text",
                    (System.nanoTime() - t0) / 1_000_000));

            if (!reply.hasToolExecutionRequests()) {
                sessionStore.save(sessionId, msgs);
                trace.add(new StepRecord(i, AgentPhase.DONE, reply.text(), 0));
                return new AgentResult(reply.text(), trace);
            }

            // ── Act + Observe(多个 tool_call 并行执行)──
            List<CompletableFuture<ToolExecutionResultMessage>> futures =
                    reply.toolExecutionRequests().stream()
                          .map(req -> CompletableFuture.supplyAsync(() -> {
                              long s = System.nanoTime();
                              String out;
                              try {
                                  out = toolRegistry.invoke(req.name(), req.arguments());
                              } catch (Exception e) {                 // 失败也要回灌
                                  out = "{\"error\":\"" + e.getClass().getSimpleName() + "\"}";
                              }
                              trace.add(new StepRecord(i, AgentPhase.OBSERVE,
                                      req.name(), (System.nanoTime() - s) / 1_000_000));
                              return ToolExecutionResultMessage.from(req, out);
                          }))
                          .toList();

            futures.forEach(f -> msgs.add(f.join()));   // 保序:按 tool_calls 原顺序追加
            log.info("step={} msgCount={}", i, msgs.size());
        }
        sessionStore.save(sessionId, msgs);
        return new AgentResult("未能在 " + MAX_STEPS + " 步内完成,请补充信息。", trace);
    }
}

public record AgentResult(String answer, List<StepRecord> trace) {}

✏️ 今日动手

  1. 把今天的 LoopAgentService 落进项目,先只注册一个假工具 queryWeather(city),内部返回硬编码 JSON({"city":"杭州","weather":"小雨"}),不接真实 API ——目的是先跑通循环骨架。
  2. 在 Controller 里加 GET /api/agent/{sessionId}?q=杭州今天要带伞吗,返回 AgentResult,用 Postman 发两次请求(同 sessionId),确认第二次能带上历史。
  3. 画一张时序图(纸笔即可):左侧 User,中间 Spring(AgentService / ToolRegistry),右侧 LLM。把今天的三轮往返按 Think/Act/Observe 标出来,你会看到 LLM 那一列被"问"了三次。

交付物:trace 里能打印出 step=1 THINK tool_calls → step=1 OBSERVE queryWeather → step=2 THINK text → DONE 这样的四行日志。这四行就是明天所有调试的基础。

🔖 明日预告

概念讲完了,明天动手写。目标:不引任何 Agent 框架,纯 JDK HttpClient + Jackson,30 行核心逻辑跑出一个能调工具的 Agent,并把你昨天写的 LoopAgentService 精简到最小可运行版本——行数越少,越能看清本质。