2026/07/23
2026 年读《深入理解 AI Agent》：先学什么，后学什么，怎么把 92 个实验真正跑起来
把《深入理解 AI Agent：设计原理与工程实践》当成一张可执行的学习路线图：按章节、按实验、按依赖、按评估顺序推进，而不是停留在概念速览。
别从目录开始，先把实验台搭起来
很多人读 Agent 资料时会遇到同一个停顿：前几章的概念都看懂了，真正打开配套代码，却卡在 API key、Python 依赖、外部仓库或硬件设备上。等环境终于装好，已经忘了前面的问题定义。读《深入理解 AI Agent：设计原理与工程实践》更适合反过来做：先选一个能在本机完成的小实验，再用章节解释它为什么这样工作。
这本书的核心公式是 Agent = LLM + 上下文 + 工具。它的价值不在于把热词集中到一处，而在于把模型如何获得信息、如何采取动作、如何接受检验拆成了工程问题。中文原版有 10 章和 92 个配套项目，其中一部分可以独立运行，另一部分是复现说明、设计练习、训练任务或硬件实验。它们不是 92 个平行的 Demo，硬件、显存、外部服务和数据集都会改变实际门槛。
仓库主页是 bojieli/ai-agent-book，在线阅读版在 bojieli.github.io/ai-agent-book。先从仓库 README 和各章 README 确认依赖，再决定今天要跑哪一个项目，比直接复制一条安装命令可靠得多。
第一轮：先建立能失败、能重跑的环境
不要一开始就为第七章训练实验准备一台昂贵机器。第一轮只需要 Python、Git、一个隔离环境和能够访问的模型接口。API 平台的可用地区、认证方式、价格和当前模型名会变化，书中的示例不能替代服务商自己的说明；没有 key 时，也可以先完成不依赖外部模型的代码阅读、数据处理和工具契约实验。
git clone https://github.com/bojieli/ai-agent-book.git
cd ai-agent-book
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip把仓库提交、Python 版本、系统平台和使用的 provider 写入记录。依赖安装失败时，保留完整错误，而不是连续换版本直到“碰巧成功”。这份失败记录以后会解释为什么同一个项目在两台机器上结果不同。
| 实验状态 | 常见条件 | 第一轮处理 |
|---|---|---|
| 可运行 | 本地 Python、少量依赖、无需外部硬件 | 优先跑通并保存输入输出 |
| 需复现 | 需要数据集、外部仓库或特定 commit | 先读 README，记录版本后再跑 |
| 设计/读者练习 | 没有完整实现或要求自行改造 | 当作思考题，不计入“跑通” |
| 硬件实验 | 机械臂、摄像头、GPU 或仿真环境 | 先看替代路径，最后再投入设备 |
第二轮：按依赖读十章，而不是按兴趣跳跃
第一章解决任务和 Agent 循环，第二章解决上下文，第三章处理记忆和知识库，第四章才把工具引入动作空间。这个顺序很实际：如果连模型看到了什么都说不清，记忆检索失败时就没有定位入口；如果工具没有输入、权限和错误契约，后面的 Coding Agent 只会把不确定性扩大。
| 阶段 | 章节 | 交付物 |
|---|---|---|
| 基础闭环 | 1–2 | 一个能解释上下文组成的最小 Agent |
| 信息与动作 | 3–5 | 记忆、工具和代码修改的可回滚样例 |
| 证据与改进 | 6–8 | 评估集、失败分类和经验更新记录 |
| 复杂环境 | 9–10 | 多模态或多 Agent 的责任边界图 |
第二章值得慢读。上下文不是把更多文本塞给模型，而是决定哪些信息在当前时刻可见、以什么顺序出现、哪些内容应被压缩或丢弃。可以先拿一个简单问答任务，分别记录完整历史、摘要历史和检索片段的结果，再观察错误来自信息缺失、信息冲突还是提示组织不当。
mkdir -p experiments/records
printf 'commit,python,provider,task,result,notes\n' > experiments/records/index.csv
python -V
git rev-parse HEAD第三章和第四章：把记忆与工具当成权限问题
记忆实验不要只看“能否记住”。更重要的是记忆何时写入、何时召回、召回内容是否过期，以及用户能否删除。RAG、结构化索引、用户记忆和知识图谱解决的不是同一个问题；先用小数据集验证召回依据，再讨论规模和向量数据库。
工具也一样。一个工具至少要有名称、参数 schema、权限范围、失败返回和超时策略。读文件和写文件、查询和执行命令，风险不是一个等级。第四章的 MCP、感知工具、执行工具和协作工具可以分别做最小样例，不必一开始搭建完整工具市场。
python -m pytest chapter4 -q
python -m pytest chapter3 -q
python -m pytest --collect-only chapter4 2>experiments/records/collect-errors.txt如果仓库某章没有统一的 pytest 入口，以该章 README 为准；上面的命令用于说明记录方式，不代表每个目录都存在同一套测试结构。运行前确认实际路径，避免把命令本身误当成项目保证。
第五章：先做可回滚的 Coding Agent
Coding Agent 是从“调用工具”走向“改变外部世界”的分水岭。第一次实验最好放在临时 Git 分支，限制文件范围，让 Agent 先输出计划，再允许修改。每次运行只改变一个变量：模型、上下文、工具权限或提示，不要同时换四样东西。
git switch -c experiment/coding-agent
mkdir -p /tmp/agent-book-sandbox
cp -R chapter5/coding-agent /tmp/agent-book-sandbox/
git diff --stat评估代码生成时，不能只看补丁像不像。至少检查测试是否通过、修改是否越界、错误处理是否保留、Agent 是否解释了未完成部分。代码可以执行，不等于方案正确；能生成补丁，也不等于拥有生产权限。
第六章是分水岭：没有评估就没有改进
第六章的意义，是把“感觉更好”变成可比较的信号。先准备一组固定任务，记录输入、上下文、工具列表、模型、版本和输出，再改变一个因素。对于开放式答案，可以保留人工评分标准；对于工具调用和代码任务，加入结构化断言、测试结果和失败类型。
| 记录项 | 为什么要保存 |
|---|---|
| 任务输入与系统提示 | 防止把提示变化误判成模型变化 |
| 模型、provider、commit | 定位版本和服务差异 |
| 工具清单与参数 | 解释动作选择和越权风险 |
| 原始输出与错误 | 支持复盘，而不是只保存成功样本 |
| 评分规则与测试结果 | 让改进可以重复比较 |
python - <<'PY'
import json, datetime
record = {'time': datetime.datetime.now().isoformat(), 'task': 'baseline', 'status': 'manual-review'}
with open('experiments/records/baseline.jsonl', 'a') as f:
f.write(json.dumps(record, ensure_ascii=False) + '\n')
PY第七、八章：后训练和自我进化都应晚一点
如果上下文、工具和评估都没有稳定，直接做 SFT、RL 或经验学习，往往是在训练一个尚未定义清楚的任务。第七章可以先理解预训练、SFT 和 RL 的分工，再判断手里的问题是否真的需要改权重；很多 Agent 项目先改提示、检索、工具契约和评估集，就能解决一部分失败。
第八章的自我进化也要保留刹车。经验写入前要有来源、适用范围和失效条件，自动生成的规则应进入候选区，经过回归集后再升级为正式配置。所谓“会自我改进”不能成为绕过人工审批的理由。
第九、十章：复杂环境需要责任图
多模态、实时交互、Computer Use、机器人和多 Agent 协作都比文本 Agent 多出一层环境风险。第九章涉及语音、GUI 和物理世界，第十章涉及协作框架、上下文共享与隔离。学习时可以先在仿真或只读环境中验证感知和决策，再考虑真实设备；真实硬件、GPU 和外部平台的条件应以对应项目 README 为准。
多 Agent 实验不要只数“有几个 Agent”。要画出谁拥有工具、谁能写入状态、谁负责最终确认、谁处理失败。协作层越多，责任越容易被平均掉；一张权限和交付物地图通常比再加一个角色更有帮助。
API key、外部仓库与许可证要单独核对
README 列出的 API 平台只是学习入口，不构成当前可用性、价格或性能承诺。key 应放在本地安全存储，不要写入 Git；调用失败时，区分认证失败、地区限制、额度限制、模型不存在和代码错误。第六、七、九、十章还涉及外部基准、训练框架和硬件项目，仓库说明它们未全部内置，需要按对应 README 获取。
中文正文位于仓库的 book/，英文、正体中文等版本由社区维护，可能落后于中文原版。许可证是 Apache License 2.0，但部分子项目可能有自己的许可文件；下载代码、模型或数据集时仍要逐项查看。
首批实验只选四类，不要追求覆盖率
第一批实验的目标不是证明自己读得快，而是建立一条完整链路。可以从四类任务各选一个：一个上下文组织实验、一个记忆或检索实验、一个只读工具实验、一个带固定断言的评估任务。四个任务都能留下输入、工具记录和结果，已经足以观察公式中的三个部分如何互相影响。
选实验时看三个条件。第一，是否能在现有设备上完成；第二，失败后能否判断原因；第三，是否能在第二次运行时只改变一个变量。需要大规模训练、真实机器人或复杂外部平台的项目不适合做起点，因为环境变量太多，失败时难以知道是代码、模型、数据还是设备。
| 首批任务 | 控制变量 | 成功标准 |
|---|---|---|
| 上下文组织 | 历史长度或摘要方式 | 能说明信息缺失与冲突来自哪里 |
| 记忆/检索 | 索引与召回条件 | 引用可追踪，过期内容可删除 |
| 只读工具 | 参数 schema 与超时 | 失败可见，不发生隐式写入 |
| 固定评估 | 模型或提示二选一 | 同一任务可重复比较 |
如果一个项目 README 标记为读者练习或设计方案，不要把“没有一条命令直接运行”当成仓库缺陷。它要求读者补实现或做决策。相反，标注可运行的项目也不意味着在任何操作系统和任何时间都能零配置启动；依赖版本和外部 API 会变化，运行前仍要看项目目录里的说明。
外部仓库要锁 commit，不要只保存 clone 命令
第六、七、九、十章的一些实验依赖外部基准、训练框架、机器人项目或数据集。主仓库没有把这些资源全部内置，既有体积原因，也有许可证和维护边界。复现时应把外部项目的 URL、commit、安装日期和本地改动写进台账。否则三个月后重新 clone 默认分支，拿到的可能已经是另一套依赖。
git -C external-project rev-parse HEAD
git -C external-project status --short
python -m pip freeze > experiments/records/requirements.lock.txt
uname -a > experiments/records/system.txt数据集也要记录版本和获取方式。不能提交到 Git 的大文件或受许可限制的数据，至少保存校验值、目录结构和下载页面。真实凭据只记录变量名，不记录值。这样同事拿到台账时，知道缺什么，也不会从日志里捡到 token。
find data -type f -maxdepth 2 -print0 | sort -z | xargs -0 shasum -a 256 > experiments/records/data.sha256
printf 'Required secrets: MODEL_API_KEY (value not recorded)\n' > experiments/records/secrets.example不同子项目可能有自己的 LICENSE。主仓库采用 Apache-2.0，不会自动改变外部仓库、模型权重或数据集的许可。准备把实验代码放进商业项目之前，逐个检查依赖的许可证和服务条款，而不是只引用主仓库的开源协议。
最小回归集从失败样本开始
回归集不必等到第六章才建立。第一次运行失败时就保存样本：原始输入、预期动作、实际动作、错误类型和人工判断。最初十到二十条失败记录，往往比一百条随机成功样本更能说明系统的短板。
分类要贴近工程原因，而不是只写“回答不好”。可以分成上下文缺失、检索错误、工具参数错误、权限拒绝、超时、输出格式错误和任务理解偏差。每修一个问题，先跑对应类别，再跑其他类别，避免为了修工具参数而破坏上下文处理。
{"id":"ctx-001","category":"context-missing","expected":"cite source","actual":"unsupported claim"}
{"id":"tool-001","category":"tool-args","expected":"read-only query","actual":"invalid schema"}
{"id":"auth-001","category":"permission","expected":"stop and ask","actual":"retry loop"}同一个样本应尽量固定非目标变量。如果要比较上下文压缩方式，就保持模型和工具不变；如果要比较模型，就保持输入、提示和评分规则不变。否则结果有变化，也无法归因。开放式任务可以由人工评分，但评分标准要在看输出前写好，防止事后为喜欢的结果改规则。
出现这些信号时，先暂停训练和硬件实验
后训练的成本不只来自 GPU。数据清洗、标注、验证器、训练日志和回滚都要投入。如果基础提示和工具 schema 仍频繁变化，训练数据会迅速过期；如果评估集不能稳定复现问题，也无法判断训练是否带来收益。此时继续训练，只会把未定义好的行为固化进权重。
可以用四个暂停信号判断：同一失败无法稳定重现；工具权限仍在频繁调整；训练样本缺少来源和验收规则；上线场景与训练环境差异过大。先解决这些问题，再决定 SFT 或 RL。第七章的意义不是鼓励每个项目都训练模型，而是帮助读者判断什么时候训练比改上下文和工具更合适。
硬件实验也有类似门槛。语音、GUI 和机器人任务加入了传感器、网络、控制频率和安全空间。没有真实设备时，可以先做数据回放、仿真或只读感知；准备接入机械动作时，再增加急停、限速、人工确认和隔离区域。不能把文本环境里的容错假设直接搬到物理世界。
多 Agent 项目如果还没有清晰的单 Agent 评估，也应暂停扩展角色。把一个不稳定循环拆成五个角色，不会自动得到协作能力，只会增加消息传递和责任定位成本。先证明单体的输入、工具和输出可控，再引入共享上下文、任务分派与最终审批。
把十章压缩成一个六周节奏
如果只能利用工作日晚间学习，可以把路线压成六周，而不是给每章机械分配相同时间。第一周读第一、二章，交付一个能打印完整上下文组成的最小循环；第二周处理第三、四章，交付一个带来源的检索结果和一个只读工具；第三周进入第五、六章，要求代码修改可回滚、固定任务能重复评分。
第四周再看第七、八章，但先做决策记录，不急着训练：当前失败能否靠上下文、检索或工具修复，训练数据从哪里来，验证集怎样与训练集隔离。第五周从第九章挑一个仿真或软件侧多模态任务，不具备硬件条件就不强行复现。第六周读第十章，把已有单 Agent 拆成明确的发起者、执行者和审批者，并测量通信增加了什么成本。
| 周次 | 重点 | 必须留下的证据 |
|---|---|---|
| 1 | Agent 循环与上下文 | 输入组成、截断规则、一次失败复盘 |
| 2 | 记忆与工具 | 引用来源、工具 schema、权限说明 |
| 3 | Coding Agent 与评估 | Git diff、测试结果、基线分数 |
| 4 | 后训练与经验学习 | 是否训练的决策记录、数据边界 |
| 5 | 多模态 | 仿真/设备条件和安全限制 |
| 6 | 多 Agent | 角色责任图、共享状态和审批点 |
时间不够时，优先保留第一至第六章。它们已经覆盖任务、上下文、记忆、工具、代码和评估，是大多数 Agent 工程问题的主干。第七至第十章可以按项目需求选读。跳过并不等于忽略，而是等前置条件成立后再回来。
验收一次实验，不只看终端返回零
命令成功退出只说明程序没有在那个位置报错。一个 Agent 实验至少还要看四件事：输出是否回答了原任务，工具是否只做了允许的动作，引用能否追到来源，重复运行时关键行为是否稳定。涉及写入的实验还要检查回滚，涉及外部 API 的实验还要检查超时和费用保护。
每次验收可以写一段很短的结论：通过了什么、没有验证什么、下次要改变哪个变量。不要把“跑通”写成一个没有条件的勾。比如“在当前 commit、Python 版本和只读数据上通过；未验证并发、长上下文和网络中断”，比截图一张绿色终端更有复现价值。
## Run 2026-07-23
- Commit: <git sha>
- Verified: read-only tool path, fixed evaluation set
- Not verified: concurrency, long context, network failure
- Next change: retrieval top-k only当实验涉及随机性时，至少重复几次，并保留全部结果而非最好的一次。样本很少时不要急着宣称性能提升；先判断错误类型是否改变、失败是否从不可解释变成可定位。工程学习的目标是增加可解释性，而不是制造一张看起来漂亮的榜单。
最后留下三份东西：实验台账、失败集和 Agent 地图
每个实验至少留下三份记录。台账写环境、版本、命令和结果；失败集保存原始输入、错误、工具调用和人工判断；Agent 地图画出模型、上下文、工具、记忆、评估和权限之间的关系。下一次修改时，先跑失败集，再看是否引入新的错误。
git status --short
find experiments/records -maxdepth 1 -type f -print | sort
sha256sum experiments/records/* 2>/dev/null仓库提供的学习建议见 学习建议文档。完成这条路线不要求把 92 个项目全部跑完，而要求能解释：模型看到了什么，工具允许什么，结果如何验证，失败如何回滚。读到这里，如果你已经能用这四个问题审视自己的 Agent，学习就从收藏目录变成了工程能力。