手动调试 Agent 的”思维”
我的理解
这一课的核心理念是”让不可见的变得可见”：Agent 以黑箱方式运行是负担而非资产，AI 架构师必须培养”透视眼”来诊断失败。实践方法出奇地简单——用 print 语句在返回最终回复前打印完整的消息历史（用户消息、tool_calls、tool_results、最终回复），通过审视这条思维链来理解 AI 决策前的”眼中世界”。这种亲手扮演日志侦探的训练能建立起对 Context Engineering 的深刻直觉，是后续一切系统构建的基石。
相关链接
- Ch02-L05 用Agentic工具扩展能力 — 本课调试的对象正是这一课构建的 Agent
- Ch02-L07 用全栈体验闭合产品闭环 — 调试完成后闭合产品闭环
原文
Lesson 15 of 46 手动调试 Agent 的”思维” / Manually Debugging the Agent’s Mind
你刚刚见证了一个魔法般的瞬间。你的应用不再只是一个简单的聊天机器人，而是一个能够在世界中采取行动的 Agent。但 AI 架构师从不相信魔法。他们会把魔法拆解开来，理解其运作机制，并将其重建得可靠稳健。一个以黑箱方式运行的 Agent 是负担，而不是资产。
这就引出了用 AI 进行构建的一项基础技能：让不可见的变得可见。当你的 Agent 给出令人意外或错误的回答时，你该如何诊断这次失败？是搜索工具返回的结果太差，还是 AI 误解了原本正确的结果？要回答这个问题，你需要培养出架构师的”透视眼”。
核心实践：成为一名日志侦探
在现阶段，你最强大的调试工具其实出奇地简单：朴实无华的 print 语句。我们要把终端变成一个原始版本的 AI 取证实验室。
让你的 AI 修改 /chat 端点。在你将最终回复返回给用户之前，添加一段代码，把导致这次回复的完整消息历史打印出来。这份历史应当包含：
最初的用户消息。
助手的 tool_calls 对象，准确展示它决定去搜索什么。
来自你的搜索函数的 tool_results，展示 Agent 拿到的原始信息。
看到这些结果后，助手生成的最终消息。
通过审视这条思维链（Chain of Thought），你不再是在猜测，而是在真正地阅读这个 Agent 的”思维”。你能看到 AI 在做出最终决策之前，眼中的世界究竟是什么样子。
学习成果：你掌握了调试 Agent 系统最根本的原则：观察上下文轨迹。这种亲手扮演日志侦探的过程是一种训练，它会建立起对上下文工程（Context Engineering）的深刻而坚定的直觉，这是任何书本或教程都无法教给你的。从今以后，这种直觉将成为你所构建的一切系统的基石。