传统软件出了问题我们会看日志。但对 Agent 系统来说传统日志经常不够。因为 Agent 的失败不一定表现为异常。它可能是选错了上下文。 调用了错误工具。 相信了过期信息。 重复执行同一步。 省略了验证。 在错误目标上努力很久。 成本一路升高但没有明显报错。这些问题不是普通 error log 能解释的你需要看见 Agent 的循环。它看到了什么 它为什么这么判断 它调用了什么工具 工具返回了什么 它如何更新状态 它怎么验证 它为什么继续或停止这就是 Agent Observability。一、为什么传统日志不够传统服务日志主要记录系统行为。比如request_id endpoint status_code latency error_message stack_trace这些对 Agent 仍然有用但它们看不到最关键的部分模型输入了哪些上下文 为什么选择这个工具 为什么相信这个工具输出 为什么没有继续验证 为什么把用户目标理解成另一个目标Agent 的核心行为发生在推理和工具循环里。如果 trace 只记录最终输出你只能看到结果。看不到过程。看不到过程就无法定位问题。你只能猜是不是 prompt 不好 是不是模型不行 是不是工具有问题 是不是上下文没给够这不是调试这是占卜。二、Agent trace 应该记录什么一个实用的 Agent trace至少要记录八类信息。第一目标。user_goal task_id success_criteria risk_level第二上下文选择。system instructions project rules retrieved documents memory entries previous state excluded context注意不只记录放进去了什么。也要记录为什么排除某些上下文。第三模型调用。model input token count output token count latency cost temperature / reasoning settings第四工具调用。tool_name tool_input tool_output_summary artifact_ref error_type retry_count第五中间决策。selected_plan reason_for_tool_choice assumptions open_questions stop_reason第六状态更新。progress update decisions update open issues verification state第七验证结果。tests run test result review result unverified items human approval第八最终结果。output files changed side effects remaining risks next action这些信息不一定都要原样暴露给最终用户但系统内部必须能追。三、三种常见盲区Agent 可观测性最容易漏三类东西。1. 上下文盲区很多系统只记录 prompt但不记录上下文来源。结果出错时你不知道模型到底看到了哪份文档、哪段记忆、哪次工具输出。比如模型引用了旧政策。你需要知道旧政策是从哪里来的 为什么新政策没有被检索到 检索排序为什么错了 压缩摘要有没有丢掉关键条件没有上下文 trace就只能猜。2. 工具盲区很多系统记录“调用了工具”但不记录工具输入、输出摘要和错误恢复。结果你不知道模型是用什么参数查的 工具返回的是空结果还是错误 Agent 有没有重试 有没有换查询条件 有没有误读状态码工具调用是 Agent 行动的核心这里不能只有一行日志。3. 验证盲区最常见的是Agent 说完成了。但系统没有记录它跑了哪些测试 哪些没跑 为什么没跑 reviewer agent 有没有发现问题 人类有没有审批没有验证 trace完成声明就没有工程含义。四、调试手册可观测性不是为了好看是为了调试。下面是几个常见故障和排查路径。4.1 Context miss表现Agent 回答漏掉关键事实。 引用了旧文档。 重复问已经给过的信息。看这些 traceretrieval query retrieved documents selected context memory entries compaction summary excluded context常见修复改检索 query 调整 rerank 补上下文选择规则 更新 memory 修改压缩模板4.2 Wrong tool表现Agent 调了不该调的工具。 用读工具代替写工具。 用通用 API 工具绕过业务工具。看这些 traceavailable tools tool descriptions tool choice reason tool inputs permission prompts常见修复改工具名 改工具描述 拆分读写工具 增加 when_not_to_use 增加权限门4.3 Invalid plan表现Agent 从一开始就走错方向。 拆任务不合理。 忽略用户约束。看这些 traceinitial plan success criteria user constraints assumptions human feedback常见修复增加计划确认 让 Agent 输出假设 加入任务模板 高风险任务先人工审 plan4.4 Repeated loop表现反复查同一个文件。 反复跑同一个失败命令。 修复同一个错误多次。看这些 traceloop iteration count same tool repeated state update failure reason retry count stop condition常见修复设置最大重试 记录已尝试方案 失败后换策略 触发人工介入4.5 Cost explosion表现一次任务 token 急剧增加。 工具输出越来越长。 多 Agent 互相传大上下文。看这些 tracetoken per turn tool output size context size cache hit rate model calls subagent count常见修复工具输出 offload 压缩历史 缓存稳定前缀 限制循环轮数 降低模型调用层级五、指标不是 trace 的替代品指标很重要。比如success rate tool error rate average turns cost per task latency per turn approval rate rollback rate human escalation rate这些能告诉你系统整体健康状况但指标只能告诉你“哪里异常”。trace才能告诉你“为什么异常”。所以Agent可观测性要同时有两层Metrics看趋势和报警 Trace看单次任务路径只有指标没有 trace定位不了具体原因。只有 trace没有指标看不到系统性退化。六、从单次调试到系统改进可观测性的最终目的不是把某一次失败查清楚而是把失败转成系统改进。每一次失败都应该归类prompt issue context issue tool issue permission issue verification issue loop issue human process issue然后进入对应改进改 prompt 模板 改检索策略 改工具描述 加权限门 加测试 加停止条件 改人工审批流程如果每次事故只靠人类手动修结果Agent 系统不会变好。真正成熟的团队会把人类从“修每个输出”迁移到“修产生输出的系统”。这也是Harness Engineering的核心精神。七、实战 Checklist上线 Agent 前先检查这十项。1. 每个任务是否有 trace_id 2. 是否记录用户目标和成功标准 3. 是否记录选入上下文和来源 4. 是否记录工具输入、输出摘要和 artifact 5. 是否记录中间决策和假设 6. 是否记录状态文件更新 7. 是否记录验证命令和结果 8. 是否记录人工审批 9. 是否记录 token、成本和延迟 10. 是否能按失败类型聚合分析如果这些都没有Agent 可以先在低风险环境试用但不建议直接进入生产闭环。八、最后第七篇到第十一篇我们把 Harness Engineering 的主要层拆完了。工具让 Agent 能行动。验证让 Agent 能自证。权限让 Agent 有边界。观测让团队能调试和改进。到这里一个生产级 Agent 已经不再只是模型 prompt而是一套可运行、可验证、可审计、可恢复的系统。下一篇我们进入最后一个阶段Loop Engineering。因为当 Agent 不只是执行一次而是围绕目标持续运行时新的问题会出现它什么时候继续 什么时候停止 状态怎么保存 失败怎么恢复 目标漂移怎么发现这就是 Agent Loop 的问题。参考资料• OpenAI Agents SDK: Tracing and Observability• OpenTelemetry Documentation• Claude Agent SDK / Claude Code Observability Documentation• Langfuse / Opik / SigNoz Agent Observability Integrations• Martin Fowler: Harness Engineering for Coding Agent Users参考文献第十一篇可观测性看不见 Agent 的循环就无法调试 Agent