🎯 今日核心问题

  1. 你已经在项目里调过 /v1/chat/completions,一次问答一次返回——那"Agent"到底比它多了什么?
  2. 为什么同一个模型,包一层循环 + 一组工具之后,就能完成"查天气再决定带伞"这种需要两步的任务?
  3. 循环、工具、状态这三个词,分别对应代码里的哪三块结构?

📖 精读提纲

【一】一次 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。

【四】常见误区

💻 代码示例

// 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 模块),做三件事:

  1. 在 resources/prompts/ 下建 agent-system.md,写一句 system prompt:"你是一个订单助手,需要数据时调用工具,不要编造订单状态。" —— 今天只写这一句,明天细调。
  2. 新建 SessionStore 接口和 InMemorySessionStore 实现(ConcurrentHashMap<String, List<Message>>),方法就两个:load(sessionId)、save(sessionId, msgs)。先不接 Redis。
  3. 把上面 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 调用栈,看清楚"模型的思考"和"代码的执行"是怎么交替的。