智能体为何需要追踪
智能体每次请求都会进行多次 LLM 调用和工具调用——没有追踪，您就无法了解内部情况。
智能体为何需要追踪 是 CoddyKit 上的免费 AI Agents 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。
本课时的部分内容尚未翻译，以英文显示。
智能体难以调试
一条用户消息可能触发 10 次 LLM 调用、5 次工具调用，并产生 30 秒延迟。出现问题时，“智能体给出了奇怪的答案”什么也说明不了。
追踪可以让您看到实际发生了什么。
一次追踪记录了什么
对于一个用户请求：
- 每次 LLM 调用：模型、输入消息、输出响应、令牌数、延迟
- 每次工具调用：名称、参数、结果、错误
- 所有步骤的顺序和时间
- 最终向用户展示的答案
日志还不够
普通日志（打印语句）会丢失追踪的结构——您无法判断哪个 LLM 调用属于哪个用户请求，也无法看出各步骤如何组成树。
结构化追踪工具可以解决这些问题。
span 与追踪
该概念借鉴自 OpenTelemetry：
- 追踪 —— 整个智能体运行过程（一个用户请求）
- span —— 追踪中的一个步骤（LLM 调用、工具调用、检索）
- span 具有父级，从而形成一棵树
A Concrete Trace Tree
Trace: user asks 'What is our return policy?'
|-- Span: retrieve_docs (12 ms)
|-- Span: llm_call_planner (820 ms)
| |-- tool_call: search_kb
|-- Span: tool_call: search_kb (340 ms)
|-- Span: llm_call_synthesise (1100 ms)
Total: 2.3 s, 8400 tokens, $0.012为什么追踪胜过日志
- 树结构展示父子关系
- 时间瀑布图揭示缓慢步骤
- 每次追踪都会汇总令牌数和成本
- 回放：使用新提示词重新运行一次追踪，以测试更改
何时添加追踪
从第一天开始。在开发期间进行追踪，可以发现仅通过聊天调试时不会注意到的错误。等到生产事故发生后再添加，就太晚了。
隐私与追踪
追踪包含用户数据。请像对待日志一样处理它们：
- 导出前遮盖 PII
- 静态加密
- 遵守数据保留政策
追踪与评测
追踪 = “这一次运行发生了什么”。评测 = “智能体在测试集上的表现如何”。两者都需要，但追踪应当先进行——无法检查的内容就无法评估。
追踪的成本
追踪会增加 1%–2% 的延迟开销，并增加存储需求。对于交互频繁的智能体，请进行采样（例如完整记录 10% 的追踪，记录 100% 的失败追踪），而不是捕获所有内容。
手动插桩与自动插桩
一些框架（LangChain、LlamaIndex）会自动插桩——您可以免费获得追踪。对于自定义代码，请使用 span 辅助函数封装 LLM 调用和工具调用。
面向用户的错误中的追踪 ID
智能体失败时，请向用户返回追踪 ID：
“发生错误。参考 ID：trace-9c4a... 请将此信息提供给技术支持。”
技术支持人员可以打开追踪，准确查看发生了什么。
为什么需要追踪？
为什么结构化追踪比面向智能体的普通打印日志更好？
回顾
追踪不可或缺。请从第一天起就将其构建进去。接下来的课程将介绍应该记录什么，以及应该使用哪些工具。
常见问题解答
「智能体为何需要追踪」课时是免费的吗？
是的 — 「智能体为何需要追踪」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。
「智能体为何需要追踪」这节课中我会学到什么？
智能体每次请求都会进行多次 LLM 调用和工具调用——没有追踪，您就无法了解内部情况。 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 AI Agents 需要有经验吗？
无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。
「智能体为何需要追踪」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 AI Agents 课中编写并运行代码吗？
能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。