🎯 今日核心问题
- Agent 的一轮循环里,"模型在想"和"代码在执行"是怎么交替的?谁在什么时候交出控制权?
- Think / Act / Observe / Repeat 四个阶段,分别对应你 Spring Boot 代码里的哪一行?
- 为什么"观察"(工具返回值)必须以原始数据回灌,而不能塞一句"查到了"了事?
📖 精读提纲
【一】四个阶段的精确分工
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 推步骤。
【四】常见误区
- ❌ 把 Think 当成"执行"。模型输出 tool_calls 不代表事情发生了。它可能编造一个不存在的工具名,也可能参数缺失。Act 阶段必须做校验。
- ❌ Observe 阶段做摘要。把 2000 字的 API 响应压成"查询成功",模型就失去了判断依据。只截断超长字段(如把长列表截到前 20 条并注明"共 N 条")。
- ❌ 用 while(true)。今天先写着,明天必须换成
for (int i = 0; i < MAX_STEPS; i++)。这个改动很小,但决定了你的账单。 - ❌ 把工具异常 catch 掉不告诉模型。吞掉异常,模型会以为成功,继续基于错误前提推理。正确做法是把
{"error":"timeout"}回灌。
💻 代码示例
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) {}
✏️ 今日动手
- 把今天的
LoopAgentService落进项目,先只注册一个假工具queryWeather(city),内部返回硬编码 JSON({"city":"杭州","weather":"小雨"}),不接真实 API ——目的是先跑通循环骨架。 - 在 Controller 里加
GET /api/agent/{sessionId}?q=杭州今天要带伞吗,返回AgentResult,用 Postman 发两次请求(同 sessionId),确认第二次能带上历史。 - 画一张时序图(纸笔即可):左侧 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 精简到最小可运行版本——行数越少,越能看清本质。