🎯 今日核心问题

  1. 经过 6 天,一个"不用框架的 Agent"最小可运行集合,到底包含哪几块?
  2. "查天气 → 决定带伞"这个两步任务,消息链在内存里长什么样?
  3. 下周的 Function Calling,和本周手写的工具调用是什么关系?

📖 精读提纲

【一】本周最小 Agent 汇编(60 行,能跑)

六天写的东西拼起来只有四块:消息协议(D4 的 sealed interface,今天简化为 record 三件套)、循环(D2 的 for + Think/Act/Observe)、终止条件(D5 的步数上限 + 重复检测)、工具表(D3 的 Map<String, Function>)。日志(D6)用一行 log.info 代替。去掉所有工程包装,核心就这些。

【二】两步任务的完整轨迹与可复用点

用户:"杭州今天要带伞吗"。R1 Think:模型看到 queryWeather 的 schema,返回 tool_calls: queryWeather(city=杭州)。R1 Observe:工具返回 {"city":"杭州","weather":"小雨","temp":18},作为 tool 消息追加。R2 Think:模型读到"小雨",输出最终文本"杭州今天小雨,气温 18℃,建议带伞"。finish_reason=stop,循环结束。

消息链最终是 5 条:system + user + assistant(tool_calls) + tool + assistant(text)。这 5 条就是 Agent 的全部中间状态,把它存下来任何一步都能回放。理解这一点,你就理解了所有 Agent 框架的内存模型。

换成"杭州今天要带伞吗 + 明天呢"这类两步任务,链路会变成 8 条:两轮各调一次 queryWeather(第二次带 date=tomorrow),最后一轮合并结论。你会发现代码一行不用改——任务变复杂只让循环多转一圈,这正是 Agent 与 if-else 编排的根本差别。

【三】实战应用:Spring Boot 场景——这 60 行往哪放

把它落进真实项目的分层:AgentController 只做参数校验和 sessionId 透传;MiniAgent 放 service/agent 包,持有循环;ToolRegistry 单独一个 Bean,工具实现注入 WeatherClient(RestTemplate + 超时配置)和 ObjectMapper。配置项 llm.* 与 agent.max-steps 全部走 application.yml,用 profile 区分 dev/prod 的模型与预算。

测试策略同样要对齐:单元测试用假的工具表(返回固定 JSON,不调外部 API),断言消息链长度和 stopReason;集成测试才打真实模型,且只跑 1-2 个用例控制成本。这样 CI 里每次提交都能跑,不会因为 API 抖动导致红。

【四】本周回顾

天核心结论产出
D1Agent = LLM + 消息列表 + 执行循环,能力增量来自编排代码而非模型循环/工具/状态三定位
D2Think 只输出意图,Act 才有副作用,Observe 必须原样回灌LoopAgentService + 时序图
D330 行 HttpClient 就能跑通 Agent,框架只包了三件事AgentMini
D4tool 消息必须与 tool_calls 的 id 严格配对,用 record 建模消息协议 + MessageValidator
D5token 消耗是 O(n²),必须有步数+预算+重复检测三道刹车StopGuard
D670% 的 bug 是"决策 bug",只能靠完整消息链定位MessageChainPrinter + trace 表

【五】常见误区与下周预告

本周最容易走偏的两点:一是以为 Agent 的智能来自循环——循环只提供"多试几次"的机会,真正决定质量的是 system prompt 的约束和工具 description 的写法;二是跳过手写直接上框架——框架会把消息链藏起来,你调不动。

本周的工具是手写注册的,schema 也是手拼的。下周解决三件事:① 用 @Tool 注解 + 反射自动生成 JSON Schema(不用手写 parameters);② 工具返回值怎么设计——结构化 JSON 比自然语言更适合模型判断;③ 工具失败、超时、参数错的完整容错链路。周日的目标是带 5 个工具的 Agent(查库、调 HTTP、读文件、算数、查时间),并且全部接入 LangChain4j。

本周的代码不要删。agent-mini 是你后面所有对比实验的基线——当 LangChain4j 出问题时,回到这 60 行,问题立刻变得清晰。

💻 代码示例

// MiniAgent.java —— 本周全部产出的合集,60 行可运行(Spring Boot 3.x)
@Service
@RequiredArgsConstructor
@Slf4j
public class MiniAgent {
    private final HttpClient http = HttpClient.newHttpClient();
    private final ObjectMapper om = new ObjectMapper();
    private final Map<String, Function<JsonNode, String>> tools = new HashMap<>();

    @Value("${llm.base-url}") private String baseUrl;
    @Value("${llm.api-key}")  private String apiKey;
    @Value("${llm.model}")    private String model;

    @PostConstruct
    void init() {
        tools.put("queryWeather", a -> {             // 真实场景替换为 RestTemplate 调天气 API
            String city = a.path("city").asText();
            if (city.isBlank()) return "{\"error\":\"city required\"}";
            return "{\"city\":\"" + city + "\",\"weather\":\"小雨\",\"temp\":18}";
        });
    }

    public String run(List<Map<String, Object>> msgs) throws Exception {
        Set<String> seen = new HashSet<>();                       // 重复调用检测
        for (int step = 1; step <= 6; step++) {                  // 步数刹车
            Map<String, Object> body = Map.of("model", model, "messages", msgs,
                    "tools", schemas(), "temperature", 0);
            HttpResponse<String> resp = http.send(HttpRequest.newBuilder(
                            URI.create(baseUrl + "/chat/completions"))
                    .header("Authorization", "Bearer " + apiKey)
                    .header("Content-Type", "application/json")
                    .timeout(Duration.ofSeconds(60))
                    .POST(HttpRequest.BodyPublishers.ofString(om.writeValueAsString(body)))
                    .build(), HttpResponse.BodyHandlers.ofString());

            JsonNode choice = om.readTree(resp.body()).path("choices").path(0);
            JsonNode msg = choice.path("message");
            msgs.add(om.convertValue(msg, Map.class));            // assistant 原样回填
            log.info("[R{}] THINK content={} calls={}", step,
                    msg.path("content").asText(""), msg.path("tool_calls").size());

            if (msg.path("tool_calls").isEmpty()) return msg.path("content").asText();

            for (JsonNode c : msg.path("tool_calls")) {
                String name = c.path("function").path("name").asText();
                String rawArgs = c.path("function").path("arguments").asText();
                if (!seen.add(name + "#" + rawArgs)) {            // 同参数第二次 = 死循环
                    msgs.add(Map.of("role", "tool", "tool_call_id", c.path("id").asText(),
                            "content", "{\"error\":\"duplicate call, stop retrying\"}"));
                    return "查询未成功,请确认城市名称。";
                }
                String out;
                try {
                    out = tools.getOrDefault(name, x -> "{\"error\":\"unknown tool\"}")
                               .apply(om.readTree(rawArgs));
                } catch (Exception e) {
                    out = "{\"error\":\"" + e.getClass().getSimpleName() + "\"}";
                }
                log.info("[R{}] OBSERVE {} -> {}", step, name, out);
                msgs.add(Map.of("role", "tool", "tool_call_id", c.path("id").asText(),
                        "content", out.length() > 4000 ? out.substring(0, 4000) : out));
            }
        }
        return "达到最大步数,请补充信息后重试。";
    }

    private List<Map<String, Object>> schemas() {               // D4/D5 的 schema 三件套
        return List.of(Map.of("type", "function", "function", Map.of(
                "name", "queryWeather",
                "description", "查询指定城市今天的天气",
                "parameters", Map.of("type", "object",
                        "properties", Map.of("city", Map.of("type", "string",
                                "description", "城市名,如 杭州")),
                        "required", List.of("city")))));
    }
}

// 调用:两步任务跑通
var msgs = new ArrayList<Map<String, Object>>();
msgs.add(Map.of("role", "system", "content",
        "你是出行助手。需要天气数据时调用 queryWeather,禁止编造天气,回答中给出是否带伞的建议。"));
msgs.add(Map.of("role", "user", "content", "杭州今天要带伞吗"));
System.out.println(agent.run(msgs));   // → 杭州今天有小雨(18℃),建议带伞出门。

✏️ 今日动手

把 MiniAgent 完整跑通并提交:@SpringBootTest 里断言回答包含"伞",日志里应出现 [R1] THINK calls=1 → [R1] OBSERVE queryWeather → [R2] THINK calls=0。然后写 README.md 三节:这是什么、怎么跑(key 用环境变量)、消息链长什么样(贴那 5 条消息)。这就是你简历里第一个 Agent 项目的最小雏形。

🔖 明日预告

下周进入工具调用与函数编排:把今天手拼的 schemas() 换成 @Tool 注解自动生成,把 Map 工具表换成 LangChain4j 的 ToolSpecification,并给 Agent 接上查库、调 HTTP、读文件、算数、查时间五个工具。你会发现自己写的 60 行和框架做的事几乎一一对应。