Start learning →Glossary Learning record

可观测性与调试：看清 Agent 的每一步

这门课讲怎么看清 Agent 到底干了什么。上一门课（本系列第 10 门）解决的是「挂没挂」——终态判分、验证器、评测集；但评测只给你一个 pass/fail，用户报「它找不到明显就在那儿的信息」时，你还是说不清：是搜索词起得差？来源挑得烂？还是工具压根报错了？这几种原因从外面看长得一模一样。更麻烦的是，Agent 在两次运行之间是非确定性的——同样的提示词跑两次走两条路，「复现一下再打断点」这套传统调试直觉直接失灵。本课教你把「说不清」变成「有据可查」：先确立原始记录（工具调用与响应的完整往返）是第一手证据、Agent 的自述不算数；再给 harness 装上结构化日志和指标（时长、调用次数、token、报错——这次不是拿来评分，是拿来盯生产）；然后把散落的记录用关联 ID 串成一棵 trace 树，一条提示词触发的所有模型请求与工具执行读成一个整体；接着学会用 hooks 在循环的关口安探头，并走一遍非确定性下的定位流程；最后动手给你第 7 门课的 harness 装上一整层观测，亲手从一个「说不清」的症状追到具体哪一步出的岔子。适合已完成本系列前 10 门课的读者。本课不教任何具体观测平台的使用（Datadog、Grafana 等只在引文出现处点名），不涉及告警阈值与 SLO 设计（一手材料没有给数字），也不重复第 10 门课的评测方法——那边的指标用来判分，这边的同一组指标用来诊断。

课程大纲

学习目标

完成本课程后，你将能够：

说清非确定性怎么让「复现再调试」失灵：同样的提示词两次跑出不同但都合法的路径，一个症状底下压着几个从外面看不可区分的原因
把原始记录当第一手证据用：读工具调用与工具响应的完整往返，抓出 Agent 的思维链和自述里没提的行为，并说清为什么自述不可信
给自己的 harness 设计结构化日志与指标：每次模型请求与工具调用各记一条，覆盖时长、调用次数、token、报错，并能按官方给的诊断读法把指标模式对应到具体修法
用关联 ID 把散落的记录串成 trace 树：一条提示词触发的所有请求与执行读成一个整体，子代理嵌进父 trace，并知道遥测管道自身会怎么骗你（静默失败、批量丢失）
在循环的生命周期关口安探头：分清每会话/每轮/每次工具调用三种节奏的观测点，用 PostToolUse 拿到完整调用记录，并沿「按 prompt id 过滤 → 找到第一处分岔 → 用一模一样的输入逐步重放」的流程定位问题
给本系列第 7 门课的 harness 装上完整观测层（JSONL 结构化日志 + trace 树打印 + 指标汇总），并亲手走完一次「症状 → 过滤 → 定位 → 修复 → 复跑对比（真跑时从出错处恢复）」的调试演练

前置要求

完成本系列前 10 门课，或具备等同基础
能手写以 stop_reason 驱动的 harness 循环，理解 tool_use/tool_result 配对（本系列第 7 门课）
了解评测跑道与通过率之外的指标（本系列第 10 门课；本课把同一组指标从评分挪到诊断）
能读写基础的 JavaScript / Node.js 代码（第 6 课需要跟着写）

预计学习时间

约 3-4 小时，包括每课的动手练习