3.1 追踪与可观测性

3.1 追踪（Tracing）与可观测性

本节摘要：智能体是"黑盒"还是"玻璃盒"？追踪（Tracing）让它变成玻璃盒——一次运行的每一步（模型调用、工具执行、各 Agent 行为）都有记录。本节讲清 Trace 与 Span 的概念、追踪的用途（排错、分析、优化）与接入方式。

读前必看

阅读完本节，你应当能够：

1. 解释 Trace 与 Span
2. 理解追踪的三大用途
3. 查看一次运行的追踪
4. 用追踪排查问题
5. 用追踪数据优化智能体

一、问题与直觉

"智能体答错了，问题出在哪？"——没有追踪，只能猜：是模型理解错了，还是工具返回错了，还是流程走了岔路？追踪把这一切记录下来：每次模型调用、每个工具执行、每轮循环，都有时间戳与内容。看到过程，问题自然现形。

传统软件调试靠报错堆栈，智能体调试靠什么？靠"行为轨迹"。模型不会抛"语义错误"，它只会给出一个不合预期的回答——你无法问它"你哪一步想错了"，只能看它实际走了哪条路。追踪就是把这条路完整录下来的机制，这也是智能体时代可观测性的核心。

二、核心原理

2.1 Trace 与 Span

• Trace：一次完整运行的记录（整棵树）
• Span：树上的一个节点（一次调用/一个步骤）

每一次 Runner.run_sync 都会产生一个 Trace；Trace 内部按层次挂 Span：最外层是"运行"本身，内层是每次模型调用、每个工具执行、每次 Agent 交接。这个树状结构，就是你排查问题的"地图"。

2.2 追踪的三大用途

2.3 查看一次运行的追踪

from agents import Agent, Runner

agent = Agent(name="demo", instructions="用中文回答。")
result = Runner.run_sync(agent, "你好")

print(result.trace_id)  # 追踪 ID，可去控制台查看完整记录
​

SDK 默认开启追踪。拿到 trace_id 后，可以在官方追踪控制台（或接入的第三方平台）里看到这次运行的完整树：模型输入输出、工具参数与返回、耗时与 token 用量。

三、工程实践要点

3.1 启用与接入

from agents import Agent, Runner, set_trace_processors

# 概念：自定义追踪处理器，把追踪数据导出到自己的系统
class MyProcessor(TraceProcessor):
    def on_trace_start(self, trace):
        ...
    def on_trace_end(self, trace):
        # 落库、告警、统计
        ...

set_trace_processors([MyProcessor()])

result = Runner.run_sync(Agent(name="demo"), "你好")
​

官方还提供与主流可观测平台的集成，接入后 Trace 会自动上报，团队可以直接在统一面板查看。数据口径以各平台文档为准，核心思路是：默认采集 + 自定义导出。

3.2 用追踪排查的流程

第一步 打开 Trace
第二步 看模型调用：模型怎么想的（输入了哪些历史、输出什么）
第三步 看工具执行：工具返回什么（参数对不对、结果是否符合预期）
第四步 定位差异：哪一步和预期不符
​

最常见的三个问题在 Trace 里一眼可见：工具没被调用（看模型输出里没有工具意图）、工具参数传错（看工具调用的参数）、工具结果导致答错（看工具返回内容）。

⚠️ 常见坑：出了问题才想起开追踪。追踪默认应始终开启（生产必开）——它只记录不干预，成本可控，价值却极高。等到出问题时才开，往往已经错过现场。

💡 关键直觉：追踪是智能体的"行车记录仪"——不出事时没人看，一出事就是唯一证据。生产环境必须开。

3.3 追踪数据驱动优化

工具耗时高 → 优化工具性能（缓存、并行、换更快的服务）
模型重试多 → 优化指令或模型（指令更明确，或换更强的模型）
循环次数多 → 简化流程（减少不必要的中转 Agent）
token 用量大 → 精简上下文（滚动窗口、摘要）
​

优化不是拍脑袋，而是从 Trace 数据里找证据：哪个 Span 耗时最长、哪类请求 token 消耗最大、哪个工具失败率最高。数据说话，优化才有方向。

3.4 生产环境的追踪规范

核心回顾

• 要点一：Trace 是整棵树，Span 是树上节点
• 要点二：三大用途——排错、分析、优化
• 要点三：追踪是行车记录仪，生产必开
• 要点四：排错流程——看模型、看工具、定位差异
• 要点五：追踪数据是优化的依据
• 要点六：默认全开，按需采样

看得见了，下一节让它"分工干"——多智能体协作与工作流。