🎯 今日核心问题
- 你已经在项目里调过 /v1/chat/completions,一次问答一次返回——那"Agent"到底比它多了什么?
- 为什么同一个模型,包一层循环 + 一组工具之后,就能完成"查天气再决定带伞"这种需要两步的任务?
- 循环、工具、状态这三个词,分别对应代码里的哪三块结构?
📖 精读提纲
【一】一次 LLM 调用:无状态的一问一答
你写过的所有"AI 功能",本质都是同一个函数签名:String answer = llm.chat(prompt)。输入一段文本,输出一段文本,函数返回后调用链就结束了。模型不记得上一次说了什么,也不会主动做第二件事。如果你要它查天气再判断带不带伞,你得自己在 Service 里写:先调天气 API,拼进 prompt,再调模型。人肉编排。
这种调用有三个硬性边界:单轮(一次请求一次响应)、无动作(只能输出文本,不能真的去调接口)、无记忆(除了你手动拼进 messages 的历史,服务端什么都不留)。项目里 80% 的场景这样够用,但只要任务需要"边做边看结果",人肉编排就会迅速失控。
【二】Agent 的三个增量:循环 / 工具 / 状态
1)循环。普通调用是 if,Agent 是 while。模型说完一句话后,程序不急着返回给用户,而是问一句"还需要继续吗";需要就再请求一次模型,把新信息塞回去。控制流从代码里搬到了模型输出里——这是最本质的差别。你的 for 循环次数由模型的决策决定,而不是由你的 if-else 决定。
2)工具。模型本身只能吐 token。但它可以吐出一个约定格式的"我要调用 weatherService.query(city=杭州)",你的 Java 代码解析这段 JSON,真去调 RestTemplate,把 HTTP 响应再包装成文本塞回对话。模型的"手"是你的 Spring Bean,不是模型自己。
3)状态。多轮循环必须有人持有 List<Message> messages。它是 Agent 的运行时内存:用户输入、模型每次的思考、工具返回的原始数据,全部按顺序追加,每轮整条链重发。凡是聊过三轮后开始"失忆"或前后矛盾的 Agent,问题几乎都在这里。
【三】实战应用:Spring Boot 场景——从 ChatService 到 AgentService
假设你的项目里有个客服问答接口 POST /api/chat,Controller 收 ChatRequest,Service 拼 system prompt 调模型,返回字符串。现在产品要求:"用户问'我这单什么时候到',系统要自己去查订单表再回答"。
不改 Agent 写法的话,你的代码会长成这样:if (text.contains("订单")) { orderId = 正则提取; order = orderRepo.findById(orderId); prompt = "订单状态是" + order.getStatus() + ",请回答用户:" + text; }。每加一种意图就加一个 if,正则越写越脆,多步任务(查订单 + 查物流 + 算预计到达)根本拼不出来。
换成 Agent 写法,Controller 和 Service 的职责完全变了:Controller 只透传 sessionId + userText;AgentService 持有一个按 sessionId 隔离的消息列表(生产上放 Redis,key 用 agent:session:{id},value 是 JSON 序列化的 messages,设 TTL 30 分钟);循环里调模型,模型返回"要调 queryOrder"就把订单号从 JSON 参数里取出来,调 OrderService,把结果追加成一条 role=tool 的消息,继续下一轮。**判断意图的逻辑从 Java if-else 搬进了 prompt 和工具描述里**,加工具不动 Controller。
【四】常见误区
- ❌ 以为 Agent 是更强的模型。同一个 gpt-4o,裸调就是聊天机器人,套上循环和工具才叫 Agent。能力增量来自你的编排代码,不是模型版本。
- ❌ 一上来就引框架。LangChain4j 的
AiServices三行就能写个 Agent,但出问题时你完全不知道它是怎么循环的、消息链长什么样。本周的核心任务就是先手写,把黑盒拆开。 - ❌ 把 messages 存在方法局部变量里。那叫单轮工具调用,不能多轮;用户第二句话进来 history 就没了。状态必须有明确的归属(session)和生命周期。
- ❌ 工具给太多了。20 个工具的 schema 塞进 system prompt,token 几千、选错率飙升。先从 2-3 个开始。
💻 代码示例
// AgentService.java —— 同一个业务,两种写法对照
@Service
@RequiredArgsConstructor
public class ChatService { // 普通调用:人肉编排
private final OpenAiChatModel model;
private final OrderRepository orderRepo;
public String chat(String userText) {
String prompt = userText;
if (userText.contains("订单")) { // 意图判断写死在代码里
String orderId = userText.replaceAll("\\D", "");
Order o = orderRepo.findById(orderId).orElseThrow();
prompt = "订单" + o.getId() + "状态为" + o.getStatus() + ",请回答用户:" + userText;
}
return model.chat(prompt); // 一次返回,结束
}
}
// Agent 版:控制流交给模型,Java 只负责执行动作和持有状态
@Service
@RequiredArgsConstructor
public class AgentService {
private final OpenAiChatModel model;
private final OrderService orderService;
private final SessionStore sessionStore; // 按 sessionId 隔离的消息列表
public String run(String sessionId, String userText) {
List<Message> msgs = sessionStore.load(sessionId); // 1. 状态
msgs.add(Message.user(userText));
for (int step = 0; step < 5; step++) { // 2. 循环(有上限)
AiMessage reply = model.chat(msgs); // 没有 if-else 判意图
msgs.add(reply);
if (!reply.hasToolExecutionRequests()) { // 模型说完了,收工
sessionStore.save(sessionId, msgs);
return reply.text();
}
for (ToolExecutionRequest req : reply.toolExecutionRequests()) { // 3. 工具
String result = switch (req.name()) {
case "queryOrder" -> orderService.describe(
new ObjectMapper().readTree(req.arguments()).get("orderId").asText());
default -> "{\"error\":\"unknown tool\"}";
};
msgs.add(ToolExecutionResultMessage.from(req, result));
}
}
return "超过最大步数,请换个问法。";
}
}
✏️ 今日动手
打开你现在的项目(或者新建一个 agent-lab 模块),做三件事:
- 在
resources/prompts/下建agent-system.md,写一句 system prompt:"你是一个订单助手,需要数据时调用工具,不要编造订单状态。" —— 今天只写这一句,明天细调。 - 新建
SessionStore接口和InMemorySessionStore实现(ConcurrentHashMap<String, List<Message>>),方法就两个:load(sessionId)、save(sessionId, msgs)。先不接 Redis。 - 把上面
AgentService.run()抄进去,用MockOpenAiChatModel或真实 API 跑一次,在msgs.add后面打一行log.info("step={} size={} last={}", step, msgs.size(), reply.text()),观察一轮交互后消息列表从 2 条涨到几条。
交付物:一个能跑通的空壳 Agent,和一张纸上的三条注释——「循环在哪、工具在哪、状态在哪」。这三条注释是本周所有代码的地基。
🔖 明日预告
今天知道了 Agent 有循环,但循环里每一步到底在干什么?明天把 while 拆成四个显式阶段:Think(模型想)→ Act(调工具)→ Observe(拿结果)→ Repeat,并用一张时序图对齐到你的 Java 调用栈,看清楚"模型的思考"和"代码的执行"是怎么交替的。