🎯 今日核心问题

  1. 为什么"答案不对"这件事,靠读代码几乎永远查不出原因?
  2. 一条消息链打出来 5000 行,怎么才能一眼看出模型在第几轮走偏了?
  3. 线上出了问题,用户只贴了"它胡说八道",你需要拿到哪几样东西才能复现?

📖 精读提纲

【一】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),打开时把完整消息链打进日志,生产关闭,避免日志量和敏感数据泄露。

【四】常见误区

💻 代码示例

// 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>

✏️ 今日动手

  1. 把 MessageChainPrinter 接进循环,跑一次"杭州今天要带伞吗",目标输出恰好 4 行:THINK tool_calls → OBSERVE → THINK text → DONE。
  2. 建 agent_trace 表(或在 H2 里建),每次 run 落一条记录,字段:traceId、messages_json、stop_reason、total_tokens、elapsed_ms。用 JdbcTemplate 写入即可。
  3. 做一个故意失败的实验:把 queryWeather 改成永远返回 {},观察模型接下来做了什么,然后用 snapshot() 打印完整链,判断这是第一层/第二层/第三层哪个 bug。

交付物:能一眼看懂的分轮日志 + agent_trace 表里一条可回放的记录。

🔖 明日预告

明天是周总结。不再讲新概念,而是把这一周写的三块东西(消息协议、循环、终止条件)拼成一个完整可运行的 60 行最小 Agent,跑通"查天气 → 决定带伞"的两步任务,并附一张本周知识回顾表和下周(工具调用与函数编排)的预告。