AI Agent 可观测性怎么做：如何追踪模型调用、工具执行、审批、Token 与故障？

结论：AI Agent 可观测性不是把对话全文存下来，也不是只看模型 API 是否返回 200。企业需要从一次真实业务任务出发，把模型调用、知识检索、工具执行、人工审批、业务写入和最终结果串成一条可追踪链路；既能回答“为什么失败”，也能回答“成功一次花了多少、是否越权、能否安全恢复”。

适用对象与问题背景

本文适合正在建设客服助手、销售辅助、文档审核、报价助手、设备售后或跨系统自动化 Agent 的企业负责人、产品负责人和业务负责人。只做演示时，开发日志也许够用；一旦 Agent 会读取内部数据、调用业务工具或推动订单、工单、通知等状态变化，就需要正式的运行追踪和业务指标。

传统应用通常能从一个接口错误定位到服务、数据库或网络。Agent 的结果还可能受到模型版本、提示词、知识版本、检索结果、工具参数、审批决定和重试路径影响。最终答案看似正常，也可能引用了错误资料、跳过了必要审批或重复执行了工具。因此，验收重点不能停留在“有没有回复”。

Cloudflare 的 Agent tracing 文档把一次运行拆成 Agent、模型、工具和审批等嵌套 span，并明确说明追踪可用于调查异常行为、慢操作和 Token 使用；同时也提醒，trace 不是完整、无损的会话记录，长内容可能被截断。这个边界很重要：追踪是诊断与治理证据，不应被误当作业务主记录。

先分清四类证据

证据层	要回答的问题	典型内容	保存原则
业务结果	任务是否真的完成	工单是否创建、报价是否进入复核、客户是否收到正确通知	由业务系统保存最终状态
Agent 运行链	Agent 如何得到并执行结果	模型调用、检索、工具、审批、重试、子任务与耗时	用 trace 关联，不替代业务记录
质量与风险	结果是否可接受	事实、引用、权限、敏感信息、人工接管、用户反馈	用固定口径评测并定期复核
系统运行	基础服务是否健康	API、数据库、队列、网络、资源与供应商错误	接入现有日志、指标和告警体系

这四层必须能通过稳定标识关联。例如一次售后申请应有业务任务 ID；Agent 运行有 trace ID；每个模型或工具步骤有 span ID；最终工单仍使用业务系统自己的记录 ID。排错时可以从客户看到的结果追到一次运行，也可以从异常工具调用回到受影响的业务记录。

一次运行至少记录什么

1. 任务与版本

记录任务类型、业务任务 ID、开始和结束时间、环境、Agent 或工作流版本、提示词版本、知识库版本、模型与关键配置。版本必须是可发布、可回溯的标识，不能只写“用了最新提示词”。

2. 模型调用

记录供应商、模型、调用顺序、耗时、结束原因、输入与输出 Token、缓存用量、重试和错误。对质量判断有必要时，保留经过脱敏或抽样的输入输出；不能默认把完整客户资料、合同、病历或账号信息写入追踪平台。

OpenTelemetry 的生成式 AI 语义约定提供了模型、会话、工作流、Token、检索和工具等通用字段，并专门提示工具参数、工具结果、检索查询和系统指令可能含敏感信息。采用通用语义可以降低对单一观测平台的绑定，但不代表所有内容都应该采集。

3. 知识与检索

记录使用了哪个数据源和版本、检索查询、返回文档标识、排名或得分、过滤条件，以及最终哪些来源进入回答。原文内容很长时，可保存文档 ID、版本和内容哈希，由有权限的人员回到原系统查看；不要为了排错无限复制敏感正文。

4. 工具与外部动作

每次工具调用应记录工具名称、受控参数摘要、调用身份、目标系统、超时、重试、结果状态和幂等键。查询、创建草稿、正式提交、退款和删除应分别标识，不能都归成模糊的“工具成功”。网络超时而结果未知时，应先查询外部系统，再决定是否重试。

5. 审批与人工接管

记录在哪一步触发审批、展示给审批人的事实和拟执行动作、审批人角色、决定时间、修改内容及最终提交是否与批准内容一致。人工接管不应只记成“失败”；它可能是设计正确的风险控制，也可能说明自动化范围过大，需要结合原因分类判断。

6. 结果与故障

运行结束要区分成功、业务拒绝、待人工、部分成功、技术失败、已补偿和结果未知。错误要落到具体阶段，并保留可行动的分类，例如“知识版本缺失”“工具权限不足”“供应商限流”“审批超时”“写入结果未知”，而不是全部写成“Agent 出错”。

指标要围绕合格任务，不只围绕模型

建议先建立六组指标：

1. 业务完成：任务完成率、一次完成率、业务拒绝率、部分成功率和恢复完成率。
2. 质量：事实或字段正确率、引用可追溯率、规则命中准确性、代表性样本通过率和用户纠错率。
3. 工具：工具成功率、参数校验失败、重复写入、结果未知、超时、重试和补偿次数。
4. 人工协同：审批触发率、接管率、修改率、等待时间，以及哪些原因最常把任务交回人工。
5. 体验与成本：端到端 P50/P95 时长、首个可用结果时间、模型 Token、外部工具费用，以及每个合格任务成本。
6. 风险：越权尝试、敏感内容命中、恶意输入、未批准动作、过期知识使用和高风险任务安全停止率。

“模型调用成功率 99%”不能说明业务可靠。一个任务可能连续调用三个模型和两个工具，最后却因审批未完成而没有进入业务系统。成本也应以“合格完成的任务”为分母；失败重试消耗的 Token 和工具费同样要计入。

NIST AI RMF 要求在接近真实部署条件的环境中持续测试，并在生产中监测系统及其组件的功能和行为。对企业而言，这意味着离线评测集、上线抽样复核和生产追踪必须使用能够对应的任务类型和结果口径，而不是各自维护一套无法比较的分数。

用一个假设场景检查追踪是否完整

以下是方法示例，不是客户案例或实测效果。假设一家设备服务企业让 Agent 协助处理售后申请：

1. 客户提交设备序列号、故障描述和照片，系统创建业务任务 ID；
2. Agent 检索对应型号手册和有效保修规则，记录知识版本与文档 ID；
3. Agent 只读查询订单与设备归属，工具调用带独立身份和最小字段；
4. Agent 生成故障分类和工单草稿，低置信、资料冲突或涉及赔付时进入人工审批；
5. 人工确认后，单一写入服务用幂等键创建正式工单；
6. 追踪记录每一步耗时、模型与工具状态、审批证据和最终工单 ID；
7. 如果提交超时，状态标记为“结果未知”，先查工单是否已存在，避免重复创建。

这个场景的验收不只是“回答是否通顺”，还包括能否从工单回到来源、审批和工具动作；能否识别资料不足；能否在未知结果下停止重复写入；以及出现投诉时能否按权限复盘。

隐私、权限与保存期限要先设计

追踪数据往往比普通日志更敏感，因为它可能同时包含用户输入、内部指令、检索资料、工具参数和审批信息。OpenAI Agents SDK 提供是否在 trace 中包含模型与工具输入输出的配置，说明“保留运行结构”和“保存原始内容”可以分开决定。

企业应按任务和字段分级：

• 默认保存 ID、版本、状态、耗时、费用和错误分类；
• 原始提示词、附件、检索正文和工具结果按必要性选择采集、截断、脱敏或只存哈希；
• 调试、质量抽样、审计和业务主记录使用不同权限和保存期限；
• 生产追踪的查看、导出和删除操作也要审计；
• 涉及个人信息、商业秘密或受监管数据时，由数据与合规负责人确认范围和地域。

不要用“日志越完整越安全”替代取舍。过度采集既增加泄露面，也会抬高存储和查询成本；采集不足则无法说明一次高风险动作为什么发生。合理目标是保留足够诊断和问责的证据，同时让高敏感原文留在原业务系统。

上线前的验收清单

• 能从一个业务任务 ID 找到完整 Agent 运行链，并回到最终业务记录；
• 模型、知识、提示词、Agent 与工具版本可以追溯；
• 模型调用、检索、工具、审批和业务写入分别计时并有清楚结果状态；
• 工具写操作有权限身份、参数校验、幂等键和结果未知处理；
• 成功、业务拒绝、待人工、部分成功、失败和补偿不会混为同一状态；
• 指标以业务任务和合格结果为口径，可以按版本、场景和风险级别比较；
• 生产样本可以进入评测与复盘，但敏感字段受控、脱敏并有保存期限；
• 告警能指向负责人和处置步骤，而不是只报告 Token 或模型错误；
• 代表性测试覆盖错误知识、工具超时、权限不足、审批拒绝、重复请求和供应商切换；
• 能在模型、提示词、知识或工具升级后比较质量、时长、成本与风险变化。

常见误区与长期维护

只买一个追踪面板就算完成。 平台能展示 span，不会自动定义业务成功、风险等级、审批责任或恢复动作。

把完整对话当作唯一证据。 对话无法可靠代表数据库写入、外部工具结果和审批状态，也可能因长度限制不完整。

只监控平均耗时与平均成本。 少量极慢、极贵或反复重试的任务会被平均值掩盖，应同时看分位数、异常和每个合格任务成本。

故障后只改提示词。 问题也可能来自错误知识版本、权限、工具接口、重试策略或审批流程；修复必须落到真正的故障阶段。

永久保存所有输入输出。 这会扩大敏感数据暴露范围。追踪内容、业务主记录和审计证据应分别治理。

上线后，每次更换模型、知识源、工具权限或审批范围，都应更新版本、代表性评测和告警阈值。可观测性的成熟度不在于日志数量，而在于企业能否在一次异常发生后快速回答：影响了哪些业务任务、哪一步改变了结果、是否越权或重复执行、如何恢复，以及同类问题怎样被后续评测提前发现。

如果尚未确定 Agent 的生产模块边界，可先阅读企业 AI Agent 系统落地需要哪些模块？；如果已经进入上线验收阶段，可结合非技术负责人如何验收 AI 客服或业务助手？建立任务样本和失败分类。

参考来源

• Cloudflare Agents：Tracing：用于核对 Agent、模型、工具与审批 span 的追踪结构，以及 trace 并非完整无损会话记录的限制。（更新：2026-08-04；访问：2026-09-18）
• OpenTelemetry：Generative AI semantic conventions：用于核对模型、工作流、会话、检索、工具和 Token 的通用字段，以及敏感内容提示。（访问：2026-09-18；该规范仍在演进）
• OpenAI Agents SDK：Running agents：用于核对运行级 trace 标识、分组、元数据以及敏感模型和工具内容的采集控制。（访问：2026-09-18）
• NIST AI RMF Core：用于核对部署前后持续测试、生产监测、指标文档化与风险响应要求。（访问：2026-09-18）

不同平台的字段、计费和保存能力会变化。正式方案应以目标 Agent 架构、数据等级、业务系统主记录、实际供应商文档和企业风险容忍度共同确定。