🎯 今日核心问题
- 经过 6 天,一个"不用框架的 Agent"最小可运行集合,到底包含哪几块?
- "查天气 → 决定带伞"这个两步任务,消息链在内存里长什么样?
- 下周的 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 抖动导致红。
【四】本周回顾
| 天 | 核心结论 | 产出 |
|---|---|---|
| D1 | Agent = LLM + 消息列表 + 执行循环,能力增量来自编排代码而非模型 | 循环/工具/状态三定位 |
| D2 | Think 只输出意图,Act 才有副作用,Observe 必须原样回灌 | LoopAgentService + 时序图 |
| D3 | 30 行 HttpClient 就能跑通 Agent,框架只包了三件事 | AgentMini |
| D4 | tool 消息必须与 tool_calls 的 id 严格配对,用 record 建模 | 消息协议 + MessageValidator |
| D5 | token 消耗是 O(n²),必须有步数+预算+重复检测三道刹车 | StopGuard |
| D6 | 70% 的 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 行和框架做的事几乎一一对应。