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 上生产就会非常被动。