Agent 观测性一次失败要能追到每个工具调用一、Agent 黑盒化会让排障非常难受传统服务失败时可以看日志、指标、链路追踪。Agent 失败时如果只留下“模型回答不对”这句话基本没法排障。它可能是意图识别错了、计划拆错了、工具参数错了、工具返回异常、状态没更新也可能是最终总结时丢了信息。Agent 观测性要把一次任务拆成可追踪的运行链路。每次模型调用、工具调用、状态更新和人工接管都应该能串起来。否则系统越智能排障越玄学。二、Agent Trace 要覆盖推理和动作一次 Agent 执行至少包含用户请求、规划、工具调用、状态更新和最终输出。flowchart TD A[用户请求] -- B[意图识别] B -- C[任务规划] C -- D[工具调用一] D -- E[状态更新] E -- F[工具调用二] F -- G[最终回答] D -- H[错误记录] F -- H链路追踪不能只记录 HTTP 请求。Agent 内部的步骤也要有 span特别是工具名称、输入摘要、输出摘要、耗时、错误码和重试次数。三、日志要避免泄露敏感内容下面是一个 Agent span 的简化结构。type AgentSpan { traceId: string; spanId: string; step: plan | tool_call | state_update | finalize; inputHash: string; outputSummary: string; latencyMs: number; error?: string; }; function isSlow(span: AgentSpan) { return span.latencyMs 3000; }注意不要把完整 Prompt、用户数据和工具返回全量写进日志。可以记录 hash、摘要、字段数量和错误类型。观测性不是把隐私全部倒进日志系统。四、指标要能回答失败发生在哪里Agent 系统需要的指标包括任务成功率、工具调用成功率、平均工具次数、重试次数、人工接管率、单步耗时和成本。只看最终成功率不知道哪里需要优化。还要按任务类型拆指标。检索型任务、执行型任务、代码生成任务、数据分析任务的失败模式不同。混在一起看平均值会掩盖真正的问题。采样也要有策略。成功请求可以低采样失败请求、高成本请求、重试请求和人工接管请求要完整保留链路。排障时最缺的往往就是失败样本。最后观测性要服务于回放。拿到一个 trace 后应该能重建当时的关键状态至少能知道每一步为什么继续、为什么重试、为什么停止。不能回放的日志只能算流水账。成本观测也不能缺。Agent 一次任务可能调用多个模型、多次检索和多个外部工具。最终回答成功了但成本可能已经远超预期。按 trace 记录 token、工具费用、重试成本和耗时才能判断这个能力是否真的适合规模化。还要设置异常模式告警。比如单个任务工具调用次数突然升高、同一工具连续失败、人工接管率上升、某类任务成本翻倍。这些信号比最终错误率更早出现能在用户明显感知前提醒团队。对高风险任务trace 还要支持人工审核。审核者不用看到完整隐私内容也应该能看到决策路径、工具摘要和关键判断点。这样才能判断 Agent 是一次偶发失败还是系统规则需要调整。五、总结Agent 观测性要把推理、工具调用、状态更新和最终输出串成完整 trace。指标要能定位失败环节日志要兼顾排障和隐私。一次失败如果追不到每个工具调用Agent 上生产就会非常被动。