🎯 今日核心问题
- 为什么"答案不对"这件事,靠读代码几乎永远查不出原因?
- 一条消息链打出来 5000 行,怎么才能一眼看出模型在第几轮走偏了?
- 线上出了问题,用户只贴了"它胡说八道",你需要拿到哪几样东西才能复现?
📖 精读提纲
【一】Agent 的 bug 分三层,日志也必须分三层
第一层是"代码 bug":NPE、JSON 解析失败、400 协议错误。这层靠异常栈就能定位,不用专门设计。
第二层是"决策 bug":代码完全正确,但模型选择了错误的工具、传了错误参数、或该停不停。这层只能靠消息链看出来——你必须看到模型当时看到了什么,才能理解它为什么这么选。
第三层是"工具 bug":模型选对了,但工具返回到的数据有问题(空列表、字段名不一致、时间格式错)。这层靠工具入参/出参日志。
实践中 70% 的问题是第二层。所以日志设计的核心不是"打更多",而是把每一轮的输入快照和输出完整留档。
【二】可读的消息链格式
直接 log.info(om.writeValueAsString(msgs)) 打出来是一行几万字符的 JSON,根本没法看。要做一个 MessageChainPrinter,按轮次分组、每条消息一行、content 截断到 200 字、工具调用单独展开。理想输出长这样:
[R1] THINK → tool_calls: queryWeather(city=杭州) tokens=612
[R1] OBSERVE← {"weather":"小雨","temp":18} 12ms
[R2] THINK → text: "杭州今天有小雨,建议带伞…" tokens=734
这种格式能让你在第 3 秒就看出问题:是模型没选工具?工具返回空的?还是模型看到了正确数据但结论错了?这三种情况的修法完全不同——分别改 system prompt、改工具实现、改 prompt 里的推理引导。
【三】实战应用:Spring Boot 场景——可回放的结构化日志
落地三件套:1)MDC 打 traceId,每个请求生成唯一 traceId 放 MDC,所有日志自动带上,方便串起多线程里的工具执行。2)结构化日志输出到文件,用 logback 单独配一个 agent appender,JSON 格式,字段固定为 traceId/sessionId/step/phase/tool/tokensMs/duration,方便后续 ELK 查询。3)落库一份完整消息链,存 agent_trace 表(traceId、sessionId、messages_json、stop_reason、total_tokens、created_at),这就是你的"黑匣子"。
有了这张表,复现 bug 的标准流程就变成:拿 traceId → 把 messages_json 取出来 → 把最后一条 assistant 消息删掉,重新发一次请求 → 对比两次输出是否一致。因为 temperature=0 时模型基本确定性,能复现就说明是 prompt 或工具的问题;不能复现说明是随机性,要考虑降低 temperature 或加校验。
另外强烈建议在测试阶段开一个 debug 开关(agent.debug=true),打开时把完整消息链打进日志,生产关闭,避免日志量和敏感数据泄露。
【四】常见误区
- ❌ 只打模型的最终回答。那等于只知道结果不对,不知道哪一步错的。
- ❌ 只打工具入参,不打返回。模型看到空数据自然乱答,你却以为工具正常。
- ❌ 用 System.out 或 log.info 混在业务日志里。Agent 的日志必须独立 appender,否则被业务日志淹没。
- ❌ debug 全量日志一直开着上生产。token 花费和用户隐私都会进日志,必须 default 关闭、按 traceId 临时打开。
💻 代码示例
// MessageChainPrinter.java —— 把消息链打成人类可读的分轮日志
@Component
@Slf4j
public class MessageChainPrinter {
public void print(String traceId, int round, String phase, String detail, int tokens, long ms) {
MDC.put("traceId", traceId);
try {
log.info("[R{}] {:<8} {} tokens={} {}ms", round, phase, detail, tokens, ms);
} finally {
MDC.remove("traceId");
}
}
/** 完整快照,仅 debug 模式,落盘用于回放 */
public String snapshot(List<AgentMessage> msgs) {
StringBuilder sb = new StringBuilder();
for (AgentMessage m : msgs) {
switch (m) {
case SystemMsg s -> sb.append("SYS : ").append(abbr(s.content()));
case UserMsg u -> sb.append("USER : ").append(abbr(u.content()));
case AssistantMsg a -> {
sb.append("AI : ").append(abbr(a.content()));
if (a.toolCalls() != null) {
a.toolCalls().forEach(c -> sb.append("\n ↳ ")
.append(c.function().name()).append(c.function().arguments()));
}
}
case ToolMsg t -> sb.append("TOOL : [").append(t.toolCallId()).append("] ")
.append(abbr(t.content()));
}
sb.append('\n');
}
return sb.toString();
}
private static String abbr(String s) {
if (s == null) return "<null>";
String one = s.replaceAll("\\s+", " ");
return one.length() <= 200 ? one : one.substring(0, 200) + "…(" + one.length() + ")";
}
}
// 循环里挂上:每轮两个 phase 各一条日志
printer.print(traceId, round, "THINK", describe(reply), usage, thinkMs);
printer.print(traceId, round, "OBSERVE", req.name() + " → " + abbr(result), 0, actMs);
// logback-spring.xml:Agent 日志单独一份,滚动 7 天
// <appender name="AGENT" class="ch.qos.logback.core.rolling.RollingFileAppender">
// <file>logs/agent.log</file>
// <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
// <fileNamePattern>logs/agent.%d{yyyy-MM-dd}.log</fileNamePattern>
// <maxHistory>7</maxHistory>
// </rollingPolicy>
// </appender>
// <logger name="com.yourco.agent" level="DEBUG" additivity="false">
// <appender-ref ref="AGENT"/>
// </logger>
✏️ 今日动手
- 把
MessageChainPrinter接进循环,跑一次"杭州今天要带伞吗",目标输出恰好 4 行:THINK tool_calls → OBSERVE → THINK text → DONE。 - 建
agent_trace表(或在 H2 里建),每次 run 落一条记录,字段:traceId、messages_json、stop_reason、total_tokens、elapsed_ms。用 JdbcTemplate 写入即可。 - 做一个故意失败的实验:把
queryWeather改成永远返回{},观察模型接下来做了什么,然后用snapshot()打印完整链,判断这是第一层/第二层/第三层哪个 bug。
交付物:能一眼看懂的分轮日志 + agent_trace 表里一条可回放的记录。
🔖 明日预告
明天是周总结。不再讲新概念,而是把这一周写的三块东西(消息协议、循环、终止条件)拼成一个完整可运行的 60 行最小 Agent,跑通"查天气 → 决定带伞"的两步任务,并附一张本周知识回顾表和下周(工具调用与函数编排)的预告。