如何设计 Agent 的执行追踪、结构化日志和问题定位机制？

核心回答

Agent 的可观测性要能回答：一次任务经过了哪些步骤，卡在哪一步，当时用了什么输入和版本，最终业务结果是什么。可以用 Trace 串起执行过程，用结构化日志解释节点细节，再用指标发现异常范围。

1. 建立关联关系。 一次实际执行建立 Trace，模型、检索、工具和子 Agent 各有 Span，保留父子关系；会话 ID 串多轮，任务 ID 串暂停、恢复和重试。跨服务、线程池和消息队列时传递追踪上下文。
2. 记录节点的开始、结束和状态变化。 包括输入输出摘要、耗时、错误类型、重试次数，以及模型、Prompt、工具和知识库版本。模型调用还记录实际返回的 Token 用量；长任务记录最后进展时间，方便区分等待和停滞。
3. 沿链路定位原因。 先从失败率、延迟或用量变化找到异常范围，再查对应 Trace：是排队、模型生成、检索还是工具慢；接着结合节点日志和版本变化验证原因。
4. 把执行状态与业务结果分开。 工具超时不代表远端没有执行，接口成功也不代表答案正确。保留降级、结果校验和业务记录的关联信息，才能判断实际完成了什么。

例如，多 Agent 汇总漏了一份结果，要同时看子 Agent 是否完成、结果是否写回，以及汇总节点实际收到哪些结果，不能仅凭“所有子任务都返回了”就认定汇总正确。

关联标识怎样设计

trace_id 标识一条调用链，span_id 标识其中一个操作，父 Span 标识调用关系。模型调用结束后执行工具，工具又调用业务服务，都应该能顺着这组关系查下去。

业务上的会话和任务另设标识：一段会话可能有多次任务，一次任务也可能暂停数小时后恢复。恢复时可以新建 Trace，用稳定的任务 ID 和必要的 Span Link 关联前后执行，无需让一个 Span 始终保持开启。每次重试单独记录尝试序号，避免第一次超时和第二次成功混成一条结果。

这些名称需要在项目中统一，但不同框架的同名术语未必相同。例如 LangSmith 的 Run 指一个操作单元，接近 OpenTelemetry 的 Span；项目自己定义的业务 run_id 则可能覆盖完整任务。

HTTP、RPC 和队列边界要验证上下文是否真正传过去，不能因为框架有自动埋点就假定全程不断链。并发分支保留父子关系，汇总阶段另外记录所采用的结果 ID，方便判断遗漏发生在执行、传输还是汇总输入构建。

结构化日志需要哪些内容

日志应围绕可定位的问题组织，而不是保存所有原始文本。

• 关联与位置： 时间、服务和实例、任务/Trace/Span 标识、节点名、Agent 角色、操作名称、尝试序号。
• 执行与错误： 开始和结束、持续时间、成功/失败/取消/等待状态、错误分类、重试或降级原因、超时预算。异常堆栈应挂到对应节点。
• 模型与上下文： 实际请求模型和返回的模型标识、Prompt/配置版本、检索文档 ID 与索引版本、工具定义版本；记录能解释本次选择的输入输出摘要和证据引用。
• 资源与结果： 模型调用次数、供应商返回的输入/输出及缓存 Token、工具结果摘要、业务结果 ID、结果校验状态。成本估算应带计算口径，缺失的用量不能填成零。

节点既要记录进入，也要在成功、异常或取消时结束；重试、等待外部输入、恢复等事件保留各自时间。对流式模型调用，可以记录首 Token 和最后进展时间，区分首包慢、持续生成慢与流式连接中断。

输入输出只保留排障所需范围，长内容可以保存受控引用或摘要，凭据和敏感字段过滤后再记录。无需依赖模型输出的原始思维链判断系统做了什么，实际工具请求、检索证据和状态变化更可靠。

怎样定位“失败、卡住、答案错”

任务失败： 先按场景、版本、模型和时间段确认影响范围，再找第一个偏离预期的节点。调用超时、限流、参数错误、无检索结果和业务拒绝分别统计，不能全部压成“Agent 出错”。如果工具失败后走了降级，保留原失败 Span 和降级原因，任务层再标明最终是成功、部分完成还是失败。

任务卡住： 找最后一个开始但未结束的节点，结合队列等待、连接池、下游请求、最后进展时间及超时设置排查。缺少结束记录也可能是进程退出或追踪数据丢失，需要与服务和下游记录交叉确认。多 Agent 并行时看端到端时间与关键路径，不能把父子 Span 或并行分支耗时全部相加。

答案错误但调用正常： 顺着问题改写、召回、重排、上下文构建、模型生成和结果校验逐步检查。记录正确文档是否召回、是否被截断、最终实际用了哪些结果，比只看最后一段回答更容易定位。Trace 显示发生过哪些调用，业务系统的查询和校验则帮助确认这些调用是否产生了预期结果。

找到原因后，可将脱敏输入、版本和预期结果整理成回归案例，在隔离环境验证修复；涉及写操作时用替身服务或测试数据，避免直接回放线上副作用。

追问：日志多了以后怎样控制成本

指标保留适合聚合的维度，任务 ID 等高基数字段用于日志和 Trace 检索，避免放进每条指标标签。追踪可按场景采样，并对失败、慢请求和异常用量提高保留比例，同时留一部分正常链路作对照。采样、导出失败和保留期限也要可见，否则“查不到 Trace”容易被误判为“任务没有执行”。

告警围绕实际场景的基线设置，例如工具失败率上升、任务长时间无进展、调用次数或 Token 用量异常。单纯记录日志条数，无法说明任务是否正常。

对应教程

参考资料