AI Agent 教程有一种很常见的读后感：每个词好像都懂，示例代码也跑通了，轮到自己做一个真正能用的东西，还是不知道该从哪里下手。
你知道 ReAct 是让模型一边思考、一边调用工具，也知道 RAG、MCP、Skills 这些名词。可 Agent 一到真实环境就开始出怪事：工具反复调用，前面拿到的信息转头就忘，模型说任务完成了，数据库里却什么也没发生。换个更贵的模型，情况可能好一点，也可能只是换了一种出错方式。
我最近从头翻了一遍李博杰的开源书《深入理解 AI Agent：设计原理与工程实践》。读下来最明显的感受，不是它收录的名词多，而是作者很愿意把那些“大家默认你已经知道”的东西写出来。
比如，在系统提示词里随手加一个动态时间戳，可能让缓存一直失效；工具偷偷把中文弯引号换成英文直引号，会让模型明明看见了原文，却怎么也替换不成功；几个 Agent 围着同一份材料讨论，也未必比一个 Agent 更聪明。
这些细节很少出现在十分钟入门教程里。它们通常藏在账单、失败日志和线上事故里，等你踩过坑才会知道。所谓隐性知识，说白了，就是熟手觉得不用讲，新手却会被卡上很久的那一层。
一、这本书补上了教程经常跳过去的那一层
《深入理解 AI Agent》源自作者在图灵《AI Agent 实战营》上的课程，后来结合实验和学员反馈不断扩写。全书正文、配图和配套代码都已经开源。按当前仓库统计，引言、十章正文和后记合计 6842 行，书中有 93 个带编号的实验。
数字只能说明分量，不能说明质量。真正让我觉得它写得细的，是作者会顺着一个概念继续往下问：它在 API 里到底长什么样，工程上由谁负责，什么情况下会失效，出了问题怎么验证，结论又有哪些边界。
全书用一句很简单的公式串起来：
Agent = LLM + 上下文 + 工具
LLM 负责判断和决策，上下文决定它眼前能看到什么，工具决定它能对外做什么。第二、三章讲上下文和记忆，第四、五章讲工具与 Coding Agent，第六、七章把评估和后训练接进来，后面再谈自我进化、多模态和多 Agent。
这个目录看着很大，主线其实没有散。碰到任何 Agent 问题，都可以先问三句：模型看到了什么？它手里有什么工具？我怎么确认它真的把事情做对了？具体框架会换，这三句话很难过时。
二、模型之外，才是 Agent 真正开始麻烦的地方
很多教程写到模型正确输出一次工具调用，任务就算完成了。书里的第一章从这里才开始谈生产问题。
作者用 Harness 来概括模型外面的这套系统。这个词不太好直译，可以先把它理解成围在模型周围的运行和保障机制。上下文、工具、权限约束、结果验证、失败后的纠正，都在这里。
书里用了一个退款 Agent 的例子。用户要退掉三天前的订单，模型能理解需求，也能提出调用 query_order 和 process_refund。这离“退款成功”还差好几步：系统得把七天退款政策告诉模型，校验金额不能超过订单金额，调用结束后检查数据库状态，遇到超时还要决定是否重试。
这几个动作由不同部分负责。模型生成的是工具调用请求，真正访问数据库、执行命令、读写文件的是 Agent 运行时。接口返回成功也只能说明调用过程没有立刻报错，退款是否真正发起、数据库里的订单状态是否正确更新，还得继续检查运行结果。
这个责任边界一旦分清，很多问题就没那么玄了。模型幻觉当然需要处理，权限、重试、回滚和结果核验也不能全甩给模型。MCP 可以统一 Agent 连接工具的方式，却不会自动替你补上安全策略，更不会保证工具本身设计得合理。
所以一个 Demo 到生产系统之间的差距，往往不在于再套一层提示词。麻烦都在模型外面，而且每一项都很具体。
模型会调用工具只是起点；生产系统还要把执行、约束、验证和失败收场接成闭环。
三、作者连那些不起眼的小坑也没放过
我印象最深的是第二章。很多文章把上下文工程讲成“写好 Prompt，再接一个知识库”，这本书直接把底层的消息列表摊开：大模型 API 本身没有记忆，每次调用都要把 system、user、assistant、tool 等消息按正确顺序重新送进去。Agent 框架做的核心工作，就是维护这条不断增长的轨迹。
消息角色也不能随便填。工具返回值如果被当成普通 user 消息，一些模型会误以为用户开启了新话题，原本需要保留的思考状态就可能被清掉。你看到的只是一段文字，模型实际接收到的却是一套带角色和边界的 token 协议。
KV Cache 那一节最能看出这本书细到什么程度。书里举了一个客服 Agent 的典型场景：工程师为了让模型知道当前时间，在系统提示词中加入实时变化的时间戳。功能看起来完全正确，结果稳定前缀每次都变，缓存无法复用，首 token 延迟和账单一起上涨。
解法并不花哨。系统提示词和工具定义尽量保持稳定，动态状态追加到消息末尾，或者需要时再通过工具查询。书里还专门区分了单次推理内部的 KV Cache 和跨 API 请求复用前缀的 Prompt Cache。普通开发者未必需要推导注意力公式，但最好知道自己改一个空格，为什么会影响速度和钱。
第四章有个更小、也更折磨人的例子。某个工具读取文件时原样返回中文弯引号，替换文件前却会偷偷把弯引号转成直引号。模型复制眼前的原文去替换，工具总说找不到。模型再读一遍，看到的还是弯引号，于是继续用同样的参数重试。
站在模型的视角，它没有做错任何事。问题出在工具让模型“看到的世界”和它真正操作的世界不一致。这类故障特别难查，因为所有局部日志看上去都合理。书里把它总结成参数传递的保真性：工具可以拒绝输入，也可以明确做规范化，唯独别悄悄改。
讲到用户记忆时，作者也保持了这种细致。他没有停在“把历史对话放进向量数据库”，而是把简单事实、完整段落、普通 JSON 卡片和带人物关系、来源背景的高级卡片放在一起比较。信息存得越完整，更新和检索越贵；拆得越碎，人物关系和上下文越容易丢。
最后给出的做法很务实：少量关键事实结构化后常驻上下文，大量原始对话按需检索。一个负责概览，一个负责细节。你真正做过记忆系统就会发现，选哪家向量数据库常常不是最难的问题，先想清楚“什么值得长期记、旧信息怎么更新、同名人物怎么区分”更要命。
四、好不好不能靠感觉，得拿评估说话
Agent 开发很容易陷进一种循环：改一下提示词，手测两个例子，感觉效果不错，然后上线。过几天遇到另一批任务，又觉得它退化了。
这本书把评估单独写成一整章。作者先把评估对象说清楚：要评估的是“模型加 Harness”这套组合，而不只是模型。模型替换实验是固定系统，只换强弱不同的模型；消融实验则固定模型，关掉提示词、工具或校验机制中的一项。前者帮助判断瓶颈在模型还是系统，后者用来找系统里真正起作用的部件。
指标部分也没有用一个“成功率”糊弄过去。假设 Agent 单次成功率是 60%，跑五次以后，至少成功一次的概率接近 99%，五次全成功的概率却只有 7.8%。前一个指标回答“它有没有能力做到”，后一个才更接近“它能不能稳定交付”。把两者混在一起，一个五次只成一次的 Agent 也能看起来很厉害。
结果和过程还要分开看。Agent 在回复里说“机票已经订好”，属于执行轨迹；数据库里真的多出订单，才是最终状态。只检查回复，很容易把“说了”当成“做了”。只检查最终状态，又可能漏掉中间的越权操作和侥幸成功。
书里甚至花篇幅讲了统计噪声。100 个测试用例上，旧模型 70%，新模型 73%，这三个点的差距很可能还在随机波动里。更靠谱的办法是用同一批任务做配对分析，看看究竟哪些题发生了一对一的胜负变化。差异仍然说不清，就继续补评估集，别急着宣布升级成功。
这部分读起来不如“做一个全自动 Agent”刺激，却可能是全书最该先用起来的内容。没有评估，所有优化都容易退回到感觉。
五、书里还把几个热门概念拉回了工程现实
第七章讲后训练时，作者没有默认读者已经懂 SFT 和 RL。SFT 说到底仍在预测下一个 token，只是训练数据换成了“问题—理想回答”，而且通常只在回答部分计算损失。它很适合把输出格式、工具协议和固定流程教稳定。
RL 也不等于写一个奖励函数。模型要在环境里生成完整轨迹，环境给出反馈，训练算法再根据奖励调整策略。做工具调用训练时，还有个很容易漏掉的细节：搜索结果、代码执行输出这些 token 来自环境，不是模型生成的，计算损失时应该屏蔽。否则模型会被带去学习“猜沙盒接下来输出什么”，训练目标从根上就歪了。书里对这个过程写得很具体。
讲“Agent 自我进化”时，作者也没有停在“让模型总结经验”这一步。一次成功轨迹想进入技能库，先要判断能否迁移到别的任务。录制下来的工作流还得在重置后的环境里从头回放，用真实评判器确认它确实完成了目标。要不然，错误流程会被当成经验反复复用，系统用得越久，毛病攒得越多。
第八章还谈到供应链攻击、能力漂移、坏工具扩散和记忆投毒。让 Agent 学会新东西不难，难的是决定什么能留下、谁来验证、出问题以后怎么清掉。这才是“持续学习”落到工程上真正麻烦的部分。
多 Agent 也被作者泼了一点冷水。第十章给出的判断标准很好用：协作有没有带来单个 Agent 生成时拿不到的新信息？
单元测试结果、编译错误、页面截图和外部事实核验都算新信息。几个 Agent 看着同一段文字轮流发表意见，信息并没有增加，很多时候只是把计算量放大。更麻烦的是，一个 Agent 的错误结论会被下游继续引用，最后因为大家说法一致，反而显得更可信。多人协作里常见的文件覆盖、跨文件语义冲突和错误级联，这一章也都写到了。
能介绍一个热门方案，也肯花时间解释它什么时候没用，这种写法挺难得。
真正拉开 Demo 和工程系统差距的，往往就是这些看起来不起眼的隐性知识。
六、它写得很细，但并不是一本零基础科普
这本书最适合已经调用过大模型 API、做过简单 Agent，又开始碰到上下文、工具、记忆、权限和评估问题的人。你不需要先学完一整套机器学习课程，不过最好能读懂 Python，熟悉命令行、Git、JSON 和 REST API。作者在引言的前置知识里也把这点说得很明白。
如果时间有限，我会先读第一、二章。第一章把 Agent 和 Harness 的坐标定下来，第二章能解释很多日常开发里的怪现象。准备做真实产品，第六章的评估最好别跳。关心模型训练，再把第六、七章连起来看。第八到十章适合带着具体问题查，不必为了“通读”硬啃。
配套实验很丰富，但也别把“有代码仓库”理解成所有项目都能一条命令跑起来。仓库的 README明确分成三类：可独立运行的项目、需要外部仓库的复现指南、还在完善的设计文档。这个标注反而让我更放心，至少读者知道自己拿到的是什么。
它也不是一本某个框架的 API 手册。只想马上抄一份 LangGraph 或 Agents SDK 示例，可能会觉得前面的路有点长。书里出现的模型、产品和排行榜也一定会变，部分前沿工作还需要时间验证。
这些局限不影响它最有价值的部分。工具名字会换，模型版本会升，Agent 仍然要面对同样几件事：给模型看什么，允许它做什么，怎样确认它没有只说不做，失败以后又该怎样收场。
七、我为什么愿意推荐它
现在的 Agent 资料不少，缺的往往不是新名词，而是有人肯把中间那几层说清楚。
我更愿意把它当成一本放在手边的工程参考书，不要求从第一页一路读到最后一页。上下文越来越乱，就回去看第二章；工具总是选错，翻第四章；换模型拿不准，先看第六章；想做会学习的 Agent，再读第八章。
技术书很难追上模型的版本号，但能把版本之外的那些问题讲清楚，就值得一直放在手边。