单Agent出了问题，你打开对话记录从头看一遍就知道哪里错了。
多Agent出了问题，你可能连是哪个Agent干的都不知道。Lead Agent说它已经把任务分发下去了，Sub Agent A说它完成了自己的部分，Sub Agent B也说完成了。但最终结果是错的。谁的锅？
我在生产环境跑多Agent踩过这个坑。排查了两个小时，最后发现是Sub Agent A的输出格式跟Sub Agent B的预期不匹配，Lead Agent没有做格式校验就直接传递了。三个Agent都没报错，但结果就是废的。
从这件事之后，我把可观测性放到了多Agent系统的第一优先级。
01 第一层：日志
日志是最基础的。每个Agent的每次操作都要留痕。
一条合格的Agent日志至少包含这些字段：时间戳、Agent ID、动作类型（工具调用/LLM请求/消息传递）、输入参数、返回结果、耗时、token消耗。
很多人写日志只记"Agent调用了什么工具"，不记参数和返回值。这在排查问题时几乎没用。你知道Agent调了一次文件读取，但不知道它读了哪个文件、拿到了什么内容。等你要回头查的时候，文件可能已经被改过了。
一个我在用的日志格式：
{
"ts": "2026-02-10T14:32:01Z",
"agent_id": "code-reviewer",
"action": "tool_call",
"tool": "read_file",
"params": {
"path": "src/api/handler.ts"},
"result_length": 2847,
"duration_ms": 120,
"tokens_in": 0,
"tokens_out": 0
}
LLM请求的日志要单独存。因为prompt内容通常很长，跟其他日志混在一起会导致日志文件膨胀到不可读。我的做法是主日志里记一个请求ID，详细的prompt和response存到独立的文件里。需要时按ID去查。
02 第二层：轨迹
日志是一条一条的记录。轨迹是把这些记录串成一条线，还原一个任务从开始到结束的完整路径。
一个典型的多Agent任务轨迹：
- 用户发起任务："给这个API加上分页功能"
- Lead Agent分析任务，决定拆成两个子任务：修改数据库查询层、修改API响应格式
- Lead Agent把子任务1分发给Agent A（数据库专家）
- Agent A读取了当前的查询代码，调用了3次工具，生成了修改方案
- Agent A把结果返回给Lead Agent
- Lead Agent把子任务2和Agent A的结果一起发给Agent B（API专家）
- Agent B基于Agent A的修改，调用了4次工具，完成API层的修改
- Agent B返回结果
- Lead Agent汇总，返回给用户
轨迹要记录每一步之间的数据流。步骤3里Lead Agent发给Agent A的具体指令是什么？步骤5里Agent A返回的具体内容是什么？步骤6里Lead Agent有没有对Agent A的结果做二次加工？
没有这些信息，你在出问题的时候只能看到起点和终点，中间的传递过程是黑盒。
03 第三层：回放
能不能用同样的输入重现同样的执行路径？
理论上，如果你完整记录了每一步的输入输出，应该可以回放整个执行过程。实践中很难做到。
第一个障碍是LLM的非确定性。即使temperature设为0，同样的prompt在不同时间点跑出的结果也可能不同。模型供应商的服务端可能更新了权重、调整了推理参数，这些对你是透明的。
第二个障碍是外部状态。Agent在执行过程中读取了文件系统、调用了API、查询了数据库。回放时这些外部状态可能已经变了。你不能回到任务执行时的文件系统快照。
我的折中方案：不追求完美回放，追求"可解释的回放"。记录每一步的实际输入和实际输出，回放时用这些记录来还原逻辑链路，而不是真的重跑一遍。这样至少能回答"当时发生了什么"，即使不能"重现当时的情况"。
对于关键任务，可以更进一步：在执行时把外部依赖的快照也存下来。Agent读了某个文件，就把那个时刻的文件内容存一份。Agent调了某个API，就把API的响应存一份。空间换可追溯性。
04 第四层：责任归因
出错时能定位到具体的Agent和具体的步骤。
这需要两个前提。第一是清晰的任务边界。每个Agent负责什么，输入是什么，输出是什么，要在任务分发时就定义清楚。如果Lead Agent给Sub Agent的指令是模糊的"帮我处理一下这个文件"，出了问题你分不清是指令不清楚还是执行不到位。
第二是审计日志。不只是记录Agent做了什么，还要记录Agent为什么做这个决定。LLM在生成工具调用之前通常会有一段推理文本（thinking），这段文本对责任归因很有价值。它能告诉你Agent是基于什么判断选择了这个操作。
GitHub上有一个社区项目dylan-gluck/cc-dev-team，它做多Agent协作开发，里面提到了几个做法：实时可观测性、状态管理、智能hook。状态管理这一点我觉得说得好——每个Agent在执行过程中的状态变化（空闲→接收任务→执行中→等待依赖→完成）都应该被追踪。状态的异常变迁（比如从"执行中"直接跳到"空闲"，跳过了"完成"状态）往往就是问题的信号。
05 Anthropic团队自己怎么做
Anthropic在他们的博客里提到过，内部安全团队用多Agent做生产问题诊断，问题诊断速度提升了3倍。
3倍提升的前提是他们有完整的观测体系。安全团队的多Agent系统能接入内部的日志平台、监控仪表盘、告警系统。Agent不是在黑盒里工作，而是在一个充分透明的环境里。
对于我们普通开发者，没有那么完善的基础设施，但思路可以借鉴。让Agent的执行环境尽可能透明。它读了什么、调了什么、判断了什么，都应该有记录。
06 一个最小可行的观测方案
如果让我推荐一个成本最低的方案，三个东西。
结构化日志。用JSON格式写日志，每条包含时间戳、Agent ID、动作、参数、结果。不要用纯文本日志，纯文本在后续分析时解析成本很高。
执行轨迹文件。每个任务生成一个轨迹文件，把这个任务涉及的所有Agent的所有操作按时间排列。文件名用任务ID命名，方便按任务检索。
错误快照。每次任务失败时，自动把当时的完整上下文存一份：所有Agent的日志、任务的输入、每个Agent的输出、失败时的错误信息。这些失败样本积累起来就是一个案例库。下次遇到类似的失败，先去案例库里搜一下，可能有现成的解决方案。
三样东西加起来，写代码大概一到两天的量。但它能把排查时间从"两小时翻聊天记录"缩短到"五分钟查日志"。
多Agent系统的可观测性投入，回报率远高于在prompt上反复调优。prompt调得再好，出了问题看不到执行过程，还是得靠猜。
