我为什么写这份手记
先交代一下我自己
我是个写了多年 Java 的服务端工程师。
这个背景说出来，不是为了标榜什么。恰恰相反——在 Agent 这件事上，Java 程序员的身份更像是一种"前科"。我们习惯了确定性：代码跑对了就一直对，单元测试通过就万事大吉，异常只要 catch 住就不会出事。
Agent 把这套假设全掀了。
大概一年多前，我开始认真用智能体辅助开发。起因很朴素：我不想在 AI 时代掉队。但我很快发现一件事——市面上能找到的资料，要么讲"Agent 是什么"（科普），要么讲"怎么调 API"（教程），但几乎没有东西讲"我照着做了，为什么还是搞不定"。
这份手记，就是想补上这一块。
教程教不会你的那些事
现在不缺 Agent 教程。打开任何一个技术社区，你都能找到手把手的入门指南：怎么接 LLM、怎么定义工具、怎么跑起一个 ReAct 循环。这些教程有用，我自己也受益过。
但它们都有一个共同的盲区——默认你跑通 demo 之后就万事大吉了。
现实是，demo 跑通只是开始。真正折磨人的，是 demo 之后那一长串问题：
- Agent 偶尔会调用根本不存在的工具，为什么？
- 同样的输入，昨天工作正常，今天就抽风，怎么测？
- 你让它做 A，它做完了 A 还顺手改了 B，这种"越权"怎么防？
- LLM 接口超时一次，整个服务卡死五分钟，这正常吗？
- 你把所有功能都实现了，但用户反馈"总觉得哪里不对"，可你说不出哪里不对。
这些问题，教程里不会讲。不是因为它们不重要，而是因为教程的作者是"从知识出发"——我知道 ReAct 是什么，我教你。而上面这些问题，只有"从经验出发"才讲得出来——我得先踩过这个坑，才能告诉你坑在哪。
这份手记就是从经验出发的。
一句话定位：主厨的后厨笔记
如果说市面上的 Agent 教程是"烹饪教材"——食材、刀工、火候、菜系，从基础讲起——那这份手记更像"主厨的后厨笔记"。
后厨笔记不教你怎么拿菜刀。它讲的是：
- 哪道菜最容易翻车，翻车了怎么救
- 怎么在出餐前尝出味道对不对（而不是等客人吐出来才知道）
- 备料的时候有什么不成文的规矩
- 那些菜谱上不会写、但老师傅都知道的潜规则
教程教你"怎么做"，这本讲"怎么不翻车"。 两者不冲突，反而是互补的。如果你还没跑通过第一个 Agent demo，我建议你先去看教程（附录 B 里有我推荐的几份）；如果你已经跑通过了，但总觉得 Agent 不稳定、不好用、不可控——那这份手记是写给你的。
你会在这份手记里得到什么
我不喜欢"你将收获……"这种话术，听着像卖课的。我说点实在的。
读完这份手记，你手里应该会多几个能直接用的判断工具：
- 一个叫"颗粒度 × 验证"的双轴模型，帮你判断手上的 Agent 项目会不会失控
- 一套工具设计原则，让你的 Agent 调用准确率从"勉强能用"变成"稳定可靠"
- 一份 eval 清单，用统计方法对付 LLM 的非确定性产出
- 一张"驾驭曲线"，让你看清自己跟智能体的协作关系处在什么阶段
还有一些你可能用不上但最好知道的——比如什么时候该引入多 Agent，什么时候不该；比如为什么我劝你别一上来就搞复杂的状态机。
更重要的是，这份手记里到处都是我踩过的坑。有些坑你迟早也会踩，有些坑你可能已经在踩了。我的希望是，你踩到的时候能想起"哦，书上说过这个"，然后少疼一点。
这份手记不讲什么
诚实比完整更重要。我得先交代清楚边界，免得你期待落空。
这份手记不教你从零实现一个 Agent 框架。 市面上已经有很好的教程做这件事（附录 B 推荐了几份），我不重复造轮子。
这份手记不涉及模型训练和微调。 我是应用层的工程师，这份手记讲的是"怎么用好别人训练好的模型"，不是"怎么自己训模型"。
这份手记不覆盖多模态。 书里的经验都来自文本 Agent，图像、语音、视频这些我实践不够，不敢乱讲。
这份手记的代码示例会偏少。 因为这是一本讲"判断和方法"的书，不是讲"具体实现"的书。涉及代码的地方我会给片段，但不会给完整项目。完整的代码示例，我更倾向于用配套仓库单独维护。
关于书名里的"手记"
最后说一个细节。
这份手记叫"手记"而不是"手册"或"指南"，是故意的。
"手册"暗示权威和完整，好像什么问题都有标准答案。但我做 Agent 这段时间最大的感受恰恰相反——这个行业变化太快，没有什么标准答案，很多问题我自己也还在想。 "手记"更诚实，它只是"我记录下来的东西"，你可以参考，但别当成圣经。
我也不是什么大佬。就是个努力想跟上这波浪潮的普通工程师，一路走一路记，把踩过的坑标了个记号。你要是也在走这条路，这些记号也许能帮上忙。
走吧，从第一章开始。
下一章
第 1 章 · Agent = Model + Harness —— 这份手记的核心命题：决定 Agent 好坏的不是模型多强，而是脚手架多好。