运行与观测
日志与追踪
平台上的每一次运行——实验场对话、集群节点、笔记本调用——都会被记录成一条追踪。读追踪是智能体系统里最核心的调试技能，也恰恰是课程环境几乎从不让你练到的那一项。
追踪列表
/traces 列出每一次运行，含智能体名称、提供商与模型、延迟、输入输出令牌数、美元成本、状态和时间戳。排序或扫一眼，找出看起来不对的那些行——红色状态、延迟离群值，以及成本比邻居高十倍的运行。
一条追踪里有什么
选中一次运行会打开完整记录：
- 运行指标
- 延迟、输入令牌、输出令牌，以及按模型单价算出的成本——都归属到触发它的用户、智能体和凭据。
- 解析后的系统提示词
- 在检索、记忆和路由引导都折进去之后，模型实际收到的是什么——而不是你配置的那个模板。这通常是整份记录里最出人意料的部分，也是第一个该读的。
- 工具调用
- 模型调用过的每个工具，附它选择的参数和拿回的结果。如果你预期的某个工具从没被调用，先查请求载荷，确认它到底有没有被提供出去。
- 请求 / 响应载荷
- 原始的提供商请求与响应。这是唯一的事实来源：模型实际收到的确切消息数组、参数和工具定义，以及它确切返回了什么。
- 错误
- 对于失败的运行，是运行时捕获到的错误信息。
实验场检查器
在 实验场里对话时，检查器面板会实时展示同样的信息，分三个页签：最近一次请求 / 响应往返、工具事件的实时流（带一个累计调用计数），以及当前会话的追踪。对于集群运行， 可观测性视图 还会加上逐节点的时间线。
为什么这样设计
智能体对自己推理过程的解释是生成出来的文本——那是一个关于「发生了什么」的合理故事，不是它的记录。追踪才是记录。两者不一致时，追踪是对的。按这个顺序去调试，你就不会再追那些并不存在的问题。
三个习惯
- 先复现，再阅读。 重跑那个出错的输入，打开追踪，先读请求载荷，再形成判断。大多数「模型坏了」最后都是「发给模型的东西和我以为的不一样」。
- 一次只改一处。 只调一行提示词、一个参数，或者换模型——然后用同一个输入跑一遍，对比两条追踪。在另一个标签页里留着旧追踪，是提示词工程里最接近科学方法的做法。
- 把成本当信号看。 某次运行的成本跳了一个数量级，通常意味着有循环、上下文膨胀，或者某个工具塞给模型的文本远超预期——追踪会告诉你是哪一种。
该 「失效模式实验室」笔记本 就是针对这项技能的引导练习：它会造出一条坏掉的追踪，然后让你找出原因。
从症状到成因
绝大多数故障就那么几种，而每一种在追踪里都有一个几秒钟就能辨认出来的特征。找到与你所见相符的那一行：
| 你看到的现象 | 追踪里显示什么 | 原因 |
|---|---|---|
| 一个说得很有把握、但根本不对的答案 | 解析后的系统提示词里没有检索到的上下文，或者检索块里是零个段落 | 检索什么都没匹配到，模型是凭训练知识作答的。要改的是集合或提示词里的拒答规则——不是模型。 |
| 它无视了一个你明知它有的工具 | 请求载荷里的工具列表并不包含它 | 该智能体上没启用它，或者没加入允许清单。如果它确实在列表里，那就是描述太含糊，与问题对不上。 |
| 一个错但看起来合理的数字 | 否 sql_query 调用——答案来自某份文档 | 它是从文字里读出一个数，而不是算出来的。把表挂上去，并启用相应工具。 |
| 答案在句子中间就停了 | 输出令牌数恰好等于配置的最大值 | max_tokens 截断。这是 JSON 解析不了的常见原因。 |
| 某次运行的成本是邻居的 20 倍 | 输入令牌数巨大，而问题很短 | 检索内容或对话历史占满了提示词——而且每一轮都在为它付钱。 |
| 它说自己做了某件其实没做的事 | 它描述的那个动作没有对应的工具调用 | 模型只是叙述了一个意图。只有追踪里的工具调用才是「确实发生过什么」的证据。 |
| 昨天还好，今天就不行了 | 某次工具调用返回了错误，而答案完全没提 | 上游变了。模型很少会声明某个工具失败了；它会绕开这件事作答。 |
空结果和调用失败，在答案里长得一模一样
两者都会产出一段流畅的回复，看不出任何出错的迹象——正因如此，该读的是工具调用的结果，而不是答案。这是本页收益最高的一个习惯。
一个行得通的调试顺序
- 1
先读解析后的系统提示词
一半的意外都在这里——检索块回来是空的、记忆召回了过期内容，或者路由引导把模型推向了错误的工具。 - 2
然后按顺序看工具调用
找那个返回了错误或空结果的调用。模型很少声明某个工具失败了；它照样会答。 - 3
接着看令牌数
输入很大而问题很小，说明检索内容或对话历史占了主导——而且每一轮都在为它付钱。 - 4
最后才动提示词
在读追踪之前做的提示词修改，大多修错了地方。
集群追踪
一次集群运行会逐节点记录步骤，于是你能看到路由选了哪条分支、哪些节点被跳过、审批在哪里等待，以及每个节点往流程状态里写了什么。通过 API 触发的运行追踪方式完全相同，并归属到触发它的那个密钥。
保留期，以及受监管租户可以关掉什么
本页的一切都建立在「保存人们输入了什么、模型回复了什么」之上。这既是调试好用的原因，也是追踪存储敏感的原因。有两个控制项，各管不同的事：
| 控件 | 在哪里操作 | 作用 |
|---|---|---|
PERSIST_PROMPT_BODIES | 环境变量（默认开启） | 把它设为 false ，自由文本就不会被写入：提示词、模型响应、节点输入输出、思维链，一概不写。 |
追踪保留期（trace_retention_days) | 管理 → IAM → 设置 | 删除早于该窗口的追踪。设为 0 则无限期保留。 |
关掉正文，骨架仍然保留
你不会失去可观测性——模型、提供商、令牌数、成本、延迟、状态、节点图，以及每次工具调用的 形状 都仍会记录。你失去的是它们内部的文本。这通常足以发现循环、成本膨胀或某个失败的工具，但不足以看出用户实际问了什么。
它不追溯生效
该设置是在 写入 时丢弃正文的。今天关掉它，对昨天已经采集的内容毫无作用——那才是保留期窗口的用途。如果你是为了合规原因关掉它，请在同一次改动里也设好保留期，否则已有的记录会一直躺在那里。