看完 Agent 教程，能解释“模型调用工具”，却仍然不知道一个任务为什么失败，这种落差很常见。模型可能没拿到上一步结果，也可能选对了工具却传错参数，或者结果已经正确，只是最后一句话总结错了。学习时如果只保存最终回答，这几种原因会混在一起。
《深入理解 AI Agent》的价值，在于提供了围绕这些环节展开的章节与实验。读者可以沿着一次任务的输入、工具调用和反馈往下查，而不是只记住框架名字。本文根据 2026 年 9 月 23 日的仓库资料整理阅读路线；当前项目列出 109 个实验，原文提到的 92 个实验及部分章节顺序已经不适用于这一版本。具体运行情况还应查看仓库的实验状态记录。
先确认你读的是哪一版
项目主仓库目前分为十章：Agent 基础、上下文、记忆与 RAG、工具、编程 Agent、交互、评估、后训练、进化和多 Agent。第六章讨论交互，第七章才是评估。按旧文章里的序号直接查找，容易把学习目标和目录对错位置。
下载代码之后，先记录提交号，再保存环境信息。书籍正文、实验代码和依赖可能持续调整；当你准备复查一个月前的结果时，只有文件夹名称并不足以说明跑的是哪个版本。记录提交号也方便给作者提交可复现的问题。
依赖安装应从目标章节开始。当前学习说明要求 Python 3.11 至 3.13，部分后训练实验另有 Python 3.12 及以上的要求。主仓库提供按章节选择依赖的方式，使用 uv 时，第一章的安装示例是 uv sync --locked --extra ch1。这条命令负责同步相应依赖，不代表全部实验都已执行，也不代表机器已经具备模型服务和训练硬件。
第一次学习不必安装所有可选依赖。先读目标实验自己的说明，确认它是否需要 API Key、外部数据、额外服务或 GPU。这里没有替你运行全书实验，也没有提供模型调用成本的实测值；遇到涉及付费接口的步骤，应先用小样本确认配置和费用归属。
从上下文实验学会保存中间过程
第一章的上下文实验适合作为起点。仓库当前设计包括完整历史、无历史、去除推理、去除工具调用和去除工具结果等条件。它们让读者观察：从发送给模型的消息里拿走一部分信息，任务过程会发生什么变化。实验条件应以对应版本代码为准，不要只按文章里的名称手工删几段文本。
以“读取配置文件并回答服务端口”为例，一次完整过程至少涉及用户问题、读取文件的调用信息、读取结果和最后的回答。工具定义说明模型能调用什么；工具结果告诉模型这次调用实际得到了什么。保留定义但删掉结果，模型仍然知道读取工具存在，却未必知道文件里写了哪个端口。
做实验前可以写出预期：如果移除工具结果，回答应当承认缺少数据，或者再次读取文件。若模型仍然给出一个具体端口，要检查这个值是否来自其他历史消息，是否碰巧与常见默认值相同。仅凭一次答对，无法证明它真正保留了任务所需信息。
一次实验记录可以很短，但应当能让别人复查：任务输入是什么，发送了哪些消息，调用了哪个模型及版本标识，工具返回什么，最后根据什么判定成功。涉及文件时记录样本内容或摘要；涉及随机性时保存重复次数与每次结果，别只截取表现最好的一次。
还需要保存失败路径。工具返回文件不存在，与模型根本没有尝试读文件，是两类问题。前者通常要查工作目录、路径或权限，后者则要查上下文中的任务说明和工具可见性。把两者都写成“模型能力不够”，后续就没有明确的修正方向。
把记忆与检索放回具体任务里
读到记忆与 RAG 时，可以继续使用同一个小项目：让 Agent 回答某个服务的配置问题，但资料从一个文件增加到几十份文档。这时需要关心的变化是，它怎样找到相关内容，以及怎样判断内容仍然有效。
假设旧部署手册写端口为 8080，新配置写成 8081。检索返回旧手册，并不意味着语言模型读错了；它可能准确复述了一份过期资料。实验应当分别检查召回文档、文档时间或版本、引用片段和最终答案。只测最后一个数字，无法知道该改检索、资料管理还是回答策略。
长期记忆也有更新问题。如果上次对话把“测试环境端口是 8080”写入记忆，下次询问生产环境时，系统需要保留环境条件。把条件删掉再存成一条简短事实，会让看似方便的记忆成为错误来源。可以设计一对对照问题，分别询问测试与生产配置，观察系统是否混淆。
这里适合先学会区分两种材料：本次任务的证据，以及以后可能复用的经验。配置文件中的当前值属于前者；“先确认环境再查配置”可以作为后者的候选。具体存储方式要结合书中的实现阅读，不宜把一次临时观察直接升级为永久规则。
工具章节要检查输入、执行与回传
工具调用出现在界面上，并不说明操作已经成功。读工具章节时，可以给每次调用画出三个检查点：模型生成的参数，工具执行后的结构化结果，以及模型收到结果后的处理。
例如读取函数接受文件路径。参数为空应怎样返回，文件不存在是否与读取成功使用不同状态，读取内容过长会不会截断，这些都影响模型接下来的判断。工具若用一段普通文本同时表达错误和正常内容，调用方可能难以区分；设计明确的返回结构，通常比在提示词里不断补充错误提醒更容易检查。
学习编程 Agent 时，也可沿用这种检查方法。把“修改成功”拆成目标文件是否改变、测试是否实际执行、退出状态是否成功、变更是否符合要求。模型最后说测试通过，不应替代终端记录。测试本身如果没有覆盖修改点，即使返回零，也只能证明那一组测试没有发现问题。
最初的样本应当足够小，让你能人工判断结果。比如只改一个纯函数，先写下输入输出，再观察 Agent 如何读文件、编辑和验证。等你能解释一次失败，再增加多文件依赖。直接拿复杂仓库开练，很容易把环境故障与推理错误混在一起。
把评估提前，带着问题读后面的章节
官方学习指南提供了整体路线。对主要想把 Agent 接入工作的人，我建议先完成第一至第五章的相关实验，再阅读第七章评估。这个顺序是针对应用实践的建议，不是替代书籍目录。
评估不一定从大型排行榜开始。你可以先建立一个十来条的小任务集，覆盖正常输入、资料缺失、工具报错和条件冲突。每条写清预期行为。例如资料缺失时，正确结果可以是指出缺什么，而不是强行输出一个答案。这样系统改动后，才知道它是否为了提高完成率而开始猜测。
评分也应保留不同维度。最终答案正确、工具调用符合边界、成本合理和结果可复查，可以分别记录。一个任务用更贵的模型重试多次后成功，和一次完成，在产品选择上可能有不同意义。不能只看单个成功比例就宣布方案更好。
后训练、进化和多 Agent 章节适合带着已发现的问题去读。如果失败主要来自过期资料，引入多个 Agent 未必能解决；如果一个固定子任务持续失败，再考虑示例、训练或工作流调整，理由会更充分。新增一个组件后，要用同一组样本比较，避免同时换模型、工具和数据，最后不知道谁造成了变化。
怎样判断自己已经学会这一部分
完成一个实验后，试着不用书里的结论解释自己的记录：哪条输入触发了哪次调用，证据从哪里进入上下文，失败发生在哪一步。如果只能说“效果不错”，通常还缺少能定位问题的过程材料。
项目的实验状态文件值得和正文一起看。仓库有代码、文档写了命令、某个环境成功执行过，以及你在当前环境复现成功，是不同层次的事实。记录时区分这些状态，遇到无法运行的实验也能留下有用信息：系统版本、依赖版本、失败命令和经过脱敏的报错。
最后保留一个小而完整的学习目录：原始样本、配置说明、运行记录、判断标准和复盘笔记。以后升级模型或改动工具时，重新执行这些样本，就能观察行为是否变化。读书时积累下来的这套记录，也会成为真正接入业务前可以继续扩充的测试基础。