Agent 上生产后出了问题怎么看：企业需要记录哪些执行轨迹

一手素材：

1. Microsoft Learn - *Configure tracing for AI agent frameworks*（https://learn.microsoft.com/en-us/azure/foundry/observability/how-to/trace-agent-framework ）

2. AWS Documentation - *Observe your agent applications on Amazon Bedrock AgentCore Observability*（https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html ）

本文把 Microsoft Azure 和 AWS 两份一手资料里"Agent 可观测性与追踪"这条主线拉出来讲透——目标读者是企业 AI 平台架构师、运维负责人、SRE、以及正在为生产 Agent 搭建监控体系的工程师。

一句话结论

Agent 上生产后出问题不可怕，可怕的是"看不到问题在哪"。 Microsoft Azure 和 AWS 在两份文档里给出的建议完全一致：没有可观测性，Agent 不准上线。可观测性的核心是"执行轨迹（Trace）"——记录 Agent 每次运行的每一步决策、每次工具调用、每次状态变化、每次延迟和 Token 消耗。

如果你正在为生产 Agent 搭建监控，先记住三个判断标准：

• Agent 出问题时能不能在 10 分钟内定位到具体哪一步？——不能说明追踪不够细。
• Agent 决策的理由能否被回放？——不能说明缺"决策理由"字段。
• Token 消耗、延迟、错误率能否按 Agent、按工具、按时间拆分？——不能说明监控粒度不够。

三个中只要命中一个，就该补可观测性。

一、传统日志为什么不够

过去企业系统出了问题，看日志是最常见的做法。但 Agent 系统的故障模式和传统系统有本质区别——

传统系统故障：明确的错误码、明确的异常堆栈、明确的失败位置。日志里搜关键字就能定位。

Agent 系统故障：没有明确的错误码、没有异常堆栈，Agent "看起来正常完成"但结果错误。"沉默失败"是 Agent 最常见的故障模式。

举例：

• 传统 API 调用失败：返回 HTTP 500，日志里有 stack trace，立刻知道是数据库连接池满；
• Agent 任务失败：返回"已成功处理"，但实际把退款金额算错了（多减了 100 元）。日志里没任何错误。3 天后财务对账才发现。

后者的问题不是日志"没记"，而是日志里根本没记录 Agent 的判断过程——只知道它做了，但不知道为什么做、依据什么数据做、中间有没有犹豫、有没有换过方案。

这就是为什么传统日志对 Agent 来说远远不够。可观测性（Observability）应运而生——它比"日志"多了一层：不只记录发生了什么，还记录为什么发生、过程中经历了哪些状态。

Microsoft Azure 和 AWS 在两份文档里都把这种记录称为 "Trace（轨迹）"——一次 Agent 运行从开始到结束的所有步骤、决策、调用、状态的完整时序记录。

二、Trace 必须包含的 6 类信息

一个合格的 Agent Trace 必须包含 6 类信息。每类信息对应一种"出问题想查"的需求。

1. 基本信息

• Trace ID：一次完整任务的全局唯一 ID
• 开始时间 / 结束时间 / 总耗时
• 用户/调用方标识：谁触发的这次任务
• Agent 名称 / 版本：跑的是哪个 Agent 的哪个版本
• 任务输入：用户原始请求或上游调用传入的数据

典型用途：用户反馈"我的任务怎么还没完成"，按 Trace ID 查详情。

2. LLM 调用详情

• 每次模型调用的时间戳
• Prompt 完整内容（包括 system prompt 和 user prompt）
• 模型返回完整内容
• 输入 token 数 / 输出 token 数
• 模型名称 / 温度 / 最大 token 等参数
• 调用延迟

典型用途：Agent 给出错误答案时，回看 prompt 是否传递了正确信息、模型返回是否被截断、token 是否超限。

3. 工具调用详情

• 每次工具调用的时间戳
• 工具名称 / 版本
• 调用参数完整内容
• 工具返回完整内容
• 调用延迟
• 调用结果状态（成功 / 失败 / 超时）

典型用途：Agent 任务结果错误时，回看工具是否返回了正确数据；Agent 卡住时，回看是不是某个工具超时。

4. Agent 决策理由

• 每一步决策的输入（看到了什么信息）
• 每一步决策的输出（做了什么选择）
• 决策理由（为什么选 A 不选 B）
• 决策耗时

典型用途：Agent 行为不符合预期时，回看决策理由判断是模型判断错误还是上游数据错误。

注意：决策理由通常需要让 Agent 自己输出（让模型在每次决策时说明原因），并在 Trace 里记录。

5. 状态变化

• 每次状态变化的时间戳
• 状态变化前后的快照
• 触发状态变化的事件

典型用途：长任务里 Agent "回到某个状态"，看是从哪个分支回来的、有没有循环。

6. 异常与重试

• 每次异常的时间戳
• 异常类型 / 异常信息
• 是否触发重试
• 重试次数 / 重试参数
• 最终结果（成功 / 失败 / 部分成功）

典型用途：Agent 任务"看起来成功"但实际失败时，回看有没有被吞掉的异常。

三、可观测性平台的 4 个核心能力

有了 6 类 Trace 信息，还需要一个可观测性平台把它们聚合起来。Microsoft Azure 和 AWS 在文档里都明确给出 4 个核心能力要求。

能力 1：Trace 存储与查询

• 存储容量：支持百万级 Trace，保留至少 90 天
• 查询速度：按 Trace ID 查询 < 1 秒，按多条件聚合查询 < 10 秒
• 查询能力：支持按 Agent、工具、时间、用户、错误类型等多维度过滤

能力 2：实时仪表盘

• 核心指标仪表盘：成功率、Token 消耗、延迟、错误率
• 按 Agent 拆分：每个 Agent 单独的运行情况
• 按工具拆分：每个工具的调用次数、成功率、平均延迟
• 按时间趋势：今日 vs 昨日、本周 vs 上周

能力 3：告警机制

• 错误率告警：超过阈值立即通知
• 延迟告警：P95 延迟超过阈值立即通知
• Token 消耗告警：单任务或累计消耗超预期时通知
• 异常模式告警：检测到循环调用、连续失败等异常模式时通知

能力 4：调试与回放

• Trace 回放：选中一个 Trace，完整回放每一步
• Prompt 修改重跑：基于历史 Trace，修改 prompt 后重跑验证
• 决策路径可视化：把 Agent 的决策树画出来
• 关联查询：从一次失败 Trace 关联所有类似的 Trace

四、企业落地的 5 步路径

可观测性平台搭建不是一步到位的事，企业落地通常分 5 步。

Step 1：明确 Trace 规范

团队先达成一致：Trace 必须包含哪些字段、命名规范是什么、ID 如何生成。这一步比选平台更重要——没有规范，Trace 数据会变成无法使用的"数据沼泽"。

Step 2：选型

可选方案：

• 云厂商方案：Azure Application Insights（深度集成 Foundry）、AWS Bedrock AgentCore Observability、Cloud Trace（深度集成 Vertex AI）
• 第三方方案：Langfuse、Helicone、Arize Phoenix、LangSmith
• 自建方案：OpenTelemetry + Jaeger / Tempo + Prometheus

选型考虑：

• 已有云生态 → 优先云厂商方案
• 多云/混合云 → 第三方方案
• 强定制需求 + 大规模 → 自建

Step 3：埋点

在 Agent 代码里加 Trace 埋点。常见做法：

• 用 OpenTelemetry SDK 手动埋点
• 用框架提供的装饰器（LangGraph、OpenAI Agents SDK 都内置 Trace）
• 用云厂商 SDK 自动采集

埋点要"早做"——Agent 业务逻辑没写之前，先把 Trace 框架搭好。

Step 4：搭建仪表盘和告警

基于 Trace 数据搭建仪表盘和告警：

• 核心指标仪表盘（必做）
• 错误率告警（必做）
• 延迟告警（必做）
• Token 消耗告警（必做）
• 异常模式告警（选做）

Step 5：建立运营流程

可观测性不是"搭完就完"，必须有运营流程：

• 每日审查：每天看一次核心仪表盘，发现异常立即调查
• 每周复盘：每周聚合一次问题 Trace，找出系统性问题
• 每月优化：基于 Trace 数据优化 Agent（prompt、工具、决策路径）

五、5 个常见误区

企业搭可观测性常踩 5 个坑：

误区 1：把"日志记录"当"可观测性"

只记录 Agent 输入输出，不记录决策、工具调用、状态变化。这只是日志，不是可观测性。

正解：必须包含决策理由、工具调用详情、状态变化。日志只是可观测性的一部分。

误区 2：把 Trace 全部存到本地

Trace 数据量很大（一次复杂任务可能 10-50MB），全部存本地很快撑爆磁盘。

正解：分级别存储。详细 Trace 存云端对象存储（S3/Azure Blob），聚合数据存分析数据库，核心指标存时序数据库。

误区 3：不做数据脱敏

Trace 里可能包含用户隐私数据、商业机密、API 密钥。直接存盘违反合规。

正解：在埋点时做脱敏——手机号、身份证号、邮箱、银行卡号、API key 全部脱敏后再存盘。

误区 4：只看平均值不看长尾

Agent 任务延迟平均值是 3 秒，但 P95 是 30 秒——长尾任务卡死用户。

正解：必须看 P50、P95、P99 分位数。平均值会掩盖问题。

误区 5：告警阈值设太松或太紧

告警太松（成功率低于 50% 才告警）→ 出问题没人知道。告警太紧（成功率低于 95% 就告警）→ 告警疲劳。

正解：告警阈值基于历史数据动态调整。前两周是"训练期"，记录正常范围，然后基于历史范围设阈值。

六、给企业的 5 条具体建议

1. 第一步：先定 Trace 规范，再选平台。 规范比工具重要。

2. 第二步：用框架内置 Trace，不要自建。 LangGraph、OpenAI Agents SDK 都内置 Trace，省事。

3. 第三步：核心指标（成功率、延迟、Token、错误率）必须可视化。 一项都不能少。

4. 第四步：告警必须基于 P95/P99，不是平均值。 长尾问题才是真问题。

5. 第五步：数据脱敏必须做。 合规是企业底线。

写在最后

Agent 上生产，可观测性不是可选项，是必选项。

Microsoft Azure 的建议："No observability, no production."——没有可观测性，就不要上生产。

AWS 的建议："Trace is the foundation of all debugging."——Trace 是所有调试的基础。

把这两条原则记在心里，你的 Agent 系统会比 80% 的同类项目更可靠。

*本文基于 Microsoft Learn *Configure tracing for AI agent frameworks* 与 AWS *Observe your agent applications on Amazon Bedrock AgentCore Observability* 两份一手资料整理，并结合企业 AI 平台团队在生产监控搭建中的真实经验。所有事实性表述都可追溯到原始素材；具体案例为通用化描述，不指向特定企业。*