《AI Agent 开发入门》目录
这一页是全书的总入口。它不只列出章节标题，还交代本卷怎么读、贯穿项目 minagent 的定位，以及每一章的一句话导读。如果你不确定从哪开始，先读「本卷怎么读」与「学习节奏」两节；如果你已经有明确目标，可以直接跳到「分部分章节」按编号定位。
全书结构是：前置 3 篇（序、前言、目录）+ 正文 18 章 54 节 + 附录 4 篇（A–D），共 61 篇。正文按学习曲线分为六个部分，每一部分解决一类问题，并围绕一个从零手写的 Agent 运行时 minagent 逐步长大。
本卷怎么读
这本书的目标不是让你「会调用某个框架」，而是让你亲手写出一台能跑、能测、能解释的 Agent 引擎。为此，全卷有几条贯穿始终的阅读约定，先在这里交代清楚。
环境前提。 主线语言是 Python 3.14（本机实测 3.14.6），配套虚拟环境位于 /tmp/agentbook/venv。minagent 引擎在第一到第十六章只用标准库（dataclasses / typing / json / asyncio / sqlite3 / math / re / hashlib），不需要装任何第三方包就能跑通全部示例。只有在明确标注「可选」「工程化」的地方，才会引入 pydantic、httpx、anthropic、fastapi 等依赖，并且都会注明这是可选项、可以跳过。
假模型为主。 全书默认路径是假模型（FakeModel），而不是真实 API。所谓假模型，就是一个实现了同一 Model 接口、但行为完全由脚本决定的替身：它不会联网、不需要密钥、每次运行输出完全一致。这样你才能对「Agent 到底调了几轮、每轮发了什么、最后为什么停」做确定性断言。真实 API 调用只在全卷末尾第 18.2 节出现一次，而且是可选的，需要你自备密钥、自行决定是否消耗额度。
动手优先。 每一节都以 minagent 的推进为主线，示例是可直接复制运行的最小完整片段，而不是脱离上下文的伪代码。只读不写，你收获的会是「我好像懂了」的错觉；敲过一遍、报过错、改对过，才算真的懂了。
TypeScript 对照。 本卷以 Python 为主线，但保留一条 TypeScript 对照线（Node 26），用来证明「协议与事件模型是语言无关的」这件事。TS 片段全部只用可擦除语法，node file.ts 可零构建直接运行，主要出现在第 17 章。
贯穿项目：minagent
卷一全卷以一个从零手写的 Agent 运行时库 minagent 为线索，18 章逐步把它养大：从一个二十行的循环，长成涵盖「消息 / 工具 / 记忆 / 编排 / 评测 / 服务」的完整模块。
用一句话说：minagent 是一台由你自己搭起来的最小 Agent 引擎，它先教会你「Agent 是怎么跑起来的」，再让你有能力判断任何框架替你做了什么。 每一节开头的引用块都会说明「本节把 minagent 推进到哪一步」，读的时候留意这条主线，知识点才不会散。
第 1–3 章立下它的核心类型（Message / Role / ToolCall / Model / Tool / ToolRegistry / RunResult），后面每一章都在这套契约之上叠加能力，而不改动已有字段名。这也是为什么本卷可以随时回看：契约一旦立稳，后面的模块就都是可插拔的。
学习节奏：建议 8–9 周
按每天投入一小时估算，完整通读一遍大约需要 8 到 9 周。下表给出三条典型路径，它们不互斥，可以先速成再补齐。
| 路径 | 适合谁 | 读哪些 | 预计用时 |
|---|---|---|---|
| 完整通读 | 想系统建立 Agent 工程心智模型 | 第 1 章至第 18 章顺序读，每节动手写代码 | 8–9 周 |
| 快速上手 | 有 Python 基础、急于能写一个 Agent | 1.1、1.2、1.3、2.1、3.1、3.3、4.1、4.2 共 8 节 | 2–3 周 |
| 参考手册 | 已会写、需要随时查 | 按目录定位章节，优先用附录 A–C | 按需 |
两条补充建议：无论选哪条路径，都请完整跑通第 1 章的示例，把仓库骨架与假模型配好；如果时间允许，第 16 章关于「确定性测试与评测」的部分值得反复读，它决定了你写的 Agent 是可验证的，还是只能靠「感觉好像变好了」来判断。
一份可执行的八周计划
上面三条路径偏原则。如果你希望有一份可以直接照着打勾的安排，下面这份八周计划可以作为起点（按每天投入一小时估算），它对应的是「完整通读」路径。
| 周次 | 主要任务 | 完成标志 |
|---|---|---|
| 第 1 周 | 第 1–2 章：仓库骨架、消息协议、假模型与 Model 协议 | 能跑通第一轮假模型对话并替换模型后端 |
| 第 2 周 | 第 3–4 章：Agent 循环、停止条件、工具注册与参数校验 | 能让 Agent 自己调工具、自己收敛 |
| 第 3 周 | 第 5–6 章：ReAct / Plan-and-Solve / Reflexion、上下文工程 | 能切换三种推理模式并控制上下文长度 |
| 第 4 周 | 第 7–8 章：流式事件、会话状态、检查点、短期记忆 | 能把一次运行的事件流出来并存盘续跑 |
| 第 5 周 | 第 9–10 章：本地嵌入、混合检索、检索增强与带引用回答 | 能让 Agent 查知识库并给出带引用的答案 |
| 第 6 周 | 第 11–13 章：任务分解、工作流编排、多 Agent 协作 | 能把 Agent 放进图里并让多个角色协作 |
| 第 7 周 | 第 14–16 章：错误重试、超时取消、可观测性、评测 | 能对运行做追踪、核算成本、写确定性测试 |
| 第 8 周 | 第 17–18 章：打包 API、TS 客户端、综合项目交付 | 能把引擎服务化并交付一个端到端项目 |
这份计划的关键不在于准时，而在于每周都有产出。Agent 工程的知识如果不落到代码上，遗忘速度会非常快。如果某一周的任务没有完成，宁可延长这一周，也不要为了赶进度跳过动手环节。
与既有 AI 专题的分工
站内 AI 相关专题已达约 250 篇（/posts/ai/、/posts/ai-ml/、/posts/llm/、/posts/llmops/、/posts/mcp/），其中与 Agent 直接相关的至少 25 篇。它们质量不低，但有一个共同的特点：每一篇都假设你已经理解 Agent 是什么，然后带你在某个单点上钻深——比如某个框架的用法、某种检索策略的调参、某个 MCP 工具的接入。
这本书与它们的分工，靠的是从零手写 + 假模型可断言的轨迹。卷一的每一节都以 minagent 的推进为主线，概念服务于可运行代码：你不会看到「Agent 有哪几种架构」这种脱离上下文的罗列，而会看到「这一轮循环为什么停在这里、这个工具调用为什么被拒绝」这样具体到可复现的现象。
一句话概括两者关系：本卷给的是「从零可运行的引擎 + 确定性复现」，站内专题给的是「单点主题深挖」，两者互补、不重复。
| 维度 | 本卷（入门卷） | 站内 AI 专题 |
|---|---|---|
| 组织方式 | 按学习顺序递进，围绕 minagent 一条主线 | 单点主题独立成篇，互不依赖 |
| 是否可运行 | 每节都有可复制的完整代码 | 侧重思路与结论，示例视主题而定 |
| 复现方式 | 假模型，输出确定、可断言 | 多依赖真实 API 或特定框架 |
| 深度取舍 | 广度优先，够用即止 | 单点深挖，可以很深 |
需要特别说明的是框架用法：卷一不依赖任何 Agent 框架（PydanticAI、LangGraph、Claude Agent SDK 等一律不用）。若正文提到它们，只作「后面会对照」的预告，不展开、不给可运行代码——框架用法留给卷三。并发深度与生产化加固则留给卷二：卷一第 13–14 章只写到「会用 + 能用假模型复现」为止。
如果你现在就想深挖某个单点主题，可以直接读本站对应的 AI 专题；读完本卷之后再回看它们，你会更容易看出每一篇在解决哪个具体问题。
分部分章节
下面按六个部分列出全部 18 章 54 节，每一行给出编号、标题与一句话说明。
表格里的编号规则是「章.节」，例如 13.2 表示第 13 章第 2 节。点击标题即可进入该节正文。每个部分开头都有一段导读，说明这一部分在整个学习曲线中的位置；如果你只想知道某节讲什么，直接看表格第三列的说明即可。
第一部分：引擎地基（第 1–3 章）
这一部分解决「Agent 到底是什么、怎么装环境、怎么让一台引擎转起来」三个前置问题。读完能建好仓库骨架、定义好消息协议，并用一个假模型跑通第一轮对话。
节奏上，这一部分刻意放慢了。第 1 章立下全卷的核心类型，看起来只是搭架子，但它决定了后面每一章怎么组织代码。第 2 章把「调用大模型」抽象成可替换的接口，是全书最重要的一个设计决定。第 3 章第一次让循环真正跑起来——从朴素循环到抽成 Agent 类。
| 编号 | 章节 | 说明 |
|---|---|---|
| 1.1 | 环境与仓库骨架 | 建好 minagent/ 目录结构，配好 venv，理解全卷的代码组织 |
| 1.2 | Agent 的最小定义与消息协议 | 定义 Message / Role / ToolCall，理解 Agent 的最小构成 |
| 1.3 | 可编程假模型 FakeModel | 用脚本驱动的假模型替换真实调用，跑通第一轮对话 |
| 2.1 | Model 协议设计 | 用 Protocol 定义 Model，把「调用大模型」变成可替换抽象 |
| 2.2 | 真实供应商适配与离线替身 | 写一个真实供应商适配器（可选），与假模型共用同一接口 |
| 2.3 | Token 预算与截断策略 | 估算 token、设定预算，在超限时按策略截断 |
| 3.1 | 朴素循环：跑到没有工具调用为止 | 写出第一个 run() 循环，理解「多轮」从哪来 |
| 3.2 | 停止条件与循环上限 | 区分正常结束、工具继续与死循环，加上步数上限 |
| 3.3 | 抽成 Agent 类：状态、步骤与回调 | 把循环收进 Agent 类，暴露步骤记录与回调钩子 |
第二部分：能力扩展（第 4–7 章）
这一部分让 Agent 从「会说话」变成「会做事、会思考、可观察」。它讲清四件事：怎么给模型接上工具、怎么选择推理模式、怎么控制喂进去的上下文、怎么把运行过程流出来。
这是全书信息密度最高的一段。第 4 章的工具调用是 Agent 区别于聊天机器人的分水岭；第 5 章的三种推理模式是同一个循环的三种变体；第 6 章的上下文工程决定了 Agent 在长任务里会不会「忘事」；第 7 章的可观察性则让前面所有行为都能被看见、被存盘。
| 编号 | 章节 | 说明 |
|---|---|---|
| 4.1 | 工具即函数：schema 生成、注册表与分发 | 用 Tool 与 ToolRegistry 把函数暴露给模型 |
| 4.2 | 参数校验与执行隔离 | 校验工具入参、隔离异常，让错误以结果而非崩溃呈现 |
| 4.3 | 并行工具调用与结果合并 | 一轮里同时调用多个工具，并按顺序合并结果 |
| 5.1 | ReAct：把「想—做—看」写进循环 | 把思考、行动、观察三段式嵌进循环 |
| 5.2 | Plan-and-Solve：先出计划再执行 | 让模型先给计划，再逐步执行，减少来回试探 |
| 5.3 | Reflexion：失败后的自我修正 | 失败后回看轨迹、生成反思，再重试一次 |
| 6.1 | 系统提示与指令分层 | 把系统、开发者与用户指令分层，避免互相覆盖 |
| 6.2 | 上下文裁剪与摘要 | 在超预算时裁剪历史或用摘要压缩，保留关键信息 |
| 6.3 | 结构化输出约束与解析兜底 | 约束模型输出 JSON，并在解析失败时兜底 |
| 7.1 | 流式事件模型 | 用事件流描述一次运行，让每一步都可被订阅 |
| 7.2 | 会话状态对象 | 用 Session 承载多轮状态，隔离不同会话 |
| 7.3 | 检查点与快照 | 把状态存盘，崩溃后能从检查点续跑 |
第三部分：记忆与知识（第 8–10 章）
这一部分回答「Agent 怎么记住东西、怎么查资料」。它把记忆分成短期与长期两层，再引出检索增强，让 Agent 能基于一个知识库回答问题，而不是只依赖模型自身的参数知识。
设计上，这一部分刻意保持「本地可离线」：嵌入与向量索引都用手写的最小实现，不依赖任何向量数据库或云端服务。这样你既能理解检索的原理，也能在没有网络的机器上完整复现。
| 编号 | 章节 | 说明 |
|---|---|---|
| 8.1 | 对话缓冲与摘要记忆 | 用缓冲与摘要两种策略保存近期对话 |
| 8.2 | 记忆检索注入 | 从记忆里挑出相关片段，注入到当前上下文 |
| 8.3 | 记忆写入策略 | 决定什么该记、什么时候记、记多细 |
| 9.1 | 嵌入与向量存储：本地可离线方案 | 手写一个可离线的嵌入与向量索引 |
| 9.2 | 混合检索：关键词 + 向量 + 重排 | 融合关键词与向量召回，再加一层重排 |
| 9.3 | 记忆即工具 | 把记忆读写暴露成工具，交给模型自己决定何时用 |
| 10.1 | 文档加载与切分 | 加载文档并按语义边界切成可检索的块 |
| 10.2 | 索引与检索工具 | 提供 search 与 read 两个工具，让 Agent 查知识库 |
| 10.3 | 带引用的回答 | 让答案附上来源引用，可追溯、可核对 |
第四部分：编排与协作（第 11–13 章）
这一部分把单个 Agent 放进更大的结构里：先学会把大任务拆成子任务，再把流程编排成图，最后让多个角色协作。它回答的是「一个 Agent 不够用时，怎么组织更多」。
这一部分也是全卷最容易「用力过猛」的地方。正文反复提醒：能用一个循环解决的就不要上多 Agent，能写成顺序执行的就不要上状态机。复杂度只有在真正需要时才值得引入。
| 编号 | 章节 | 说明 |
|---|---|---|
| 11.1 | 任务分解：把大问题拆成子任务 DAG | 把目标拆成有依赖关系的子任务图 |
| 11.2 | 计划执行器 | 按依赖顺序执行子任务，汇总中间结果 |
| 11.3 | 重规划 | 执行受阻时回看计划，局部重排而非全盘重来 |
| 12.1 | 状态机式编排 | 手写一个最小图引擎：节点、边与状态流转 |
| 12.2 | 分支、合并与循环 | 支持条件分支、并行合并与带出口的循环 |
| 12.3 | 人类在环 | 在关键节点暂停，等待人工确认后继续 |
| 13.1 | 角色与分工 | 用 supervisor / worker 划分职责，各司其职 |
| 13.2 | 消息总线与共享状态 | 用进程内消息总线连接多个 Agent |
| 13.3 | 协作模式对照 | 对照几种协作拓扑，判断何时值得上多 Agent |
第五部分：可靠性与度量（第 14–16 章）
这一部分处理「让 Agent 稳定、可见、可评估」。它把工程上的三个老问题搬到 Agent 场景：出错怎么办、运行怎么看见、改动到底有没有让效果变好。
很多教程会跳过这一部分，直接讲「怎么让 Agent 更聪明」。但真实项目里，决定成败的往往是这三件事：错误能不能被分类处理、成本能不能被核算、优化能不能被量化。卷一把它们认真讲一遍。
| 编号 | 章节 | 说明 |
|---|---|---|
| 14.1 | 分类错误与重试 | 把错误分类，只对可重试的做退避重试 |
| 14.2 | 超时、取消与结构化并发 | 用 asyncio.TaskGroup 统一管理超时与取消 |
| 14.3 | 幂等与副作用 | 识别有副作用的工具，让重试不产生重复影响 |
| 15.1 | 运行追踪 | 用 span 树记录一次运行的完整调用结构 |
| 15.2 | 结构化日志与关联 ID | 输出可检索的结构化日志，用关联 ID 串起全链路 |
| 15.3 | 成本与用量核算 | 累计 token 用量，换算成可比较的成本 |
| 16.1 | 确定性测试 | 用假模型与断言轨迹写出确定性测试 |
| 16.2 | 评测集与打分 | 建一个小评测集，给不同版本打分 |
| 16.3 | 对比实验 | 用对比实验判断改动到底有没有让效果变好 |
第六部分：交付（第 17–18 章）
最后一部分把引擎交付出去：先把它包成一个稳定的库接口，再服务化，最后用一个综合项目把全书串起来。它回答的是「代码写完之后，怎么变成别人能用的东西」。
第 17 章的 TS 客户端是全书唯一的 TypeScript 落点，用来证明协议可以跨语言复用。第 18 章则把前面所有模块组装成一个端到端项目，并给出可选的真实 API 冒烟步骤与后续学习路线。
| 编号 | 章节 | 说明 |
|---|---|---|
| 17.1 | 库的对外接口 | 收敛出一个稳定的公开接口，隐藏内部实现 |
| 17.2 | HTTP 服务化 | 用 FastAPI 与 SSE 把引擎暴露成可流式调用的服务 |
| 17.3 | TS 落点一：同一协议的 TS 客户端 | 用 TypeScript 写一个遵循同一协议的客户端 |
| 18.1 | 端到端 | 组装工具、记忆、检索与编排，跑通完整任务 |
| 18.2 | 真实 API 冒烟（可选） | 可选地用真实供应商做一次冒烟验证 |
| 18.3 | 回顾与路线 | 回顾 minagent 的演进，给出进阶学习路线 |
前置与附录
前置三篇负责交代背景与体例，附录四篇负责速查与排错。建议第一次通读时先跳过附录，遇到具体问题再回来翻。
| 位置 | 标题 | 说明 |
|---|---|---|
| 序 | 《AI Agent 开发入门》序 | 为什么现在要学 Agent 开发，以及本书的写法取舍 |
| 前言 | 《AI Agent 开发入门》前言 | 目标读者、前置知识、技术栈、版本口径与三卷结构 |
| 目录 | 《AI Agent 开发入门》目录 | 全书导航与学习路径（即本页） |
| 附录 A | 附录 A minagent API 与模块速查 | 核心类型、协议与模块的签名速查 |
| 附录 B | 附录 B FakeModel 脚本语法与测试夹具速查 | 假模型脚本的写法与常用测试夹具 |
| 附录 C | 附录 C 环境与离线复现速查 | venv、依赖安装源与离线复现步骤 |
| 附录 D | 附录 D 常见错误与 FAQ | 高频报错的原文、原因与修法 |
常见问题速查
下面是读者最常问的几个「该读哪一节」的问题，直接给答案：
| 你的问题 | 去哪一节 |
|---|---|
| 不想联网、不想花钱，能不能学 | 1.3 可编程假模型 FakeModel、附录 C |
| 怎么把「调模型」换成可替换的接口 | 2.1 Model 协议设计 |
| Agent 为什么停不下来 / 转圈 | 3.2 停止条件与循环上限、附录 D |
| 怎么让模型调用我自己写的函数 | 4.1 工具即函数：schema 生成、注册表与分发 |
| 工具报错把整个 Agent 搞崩了 | 4.2 参数校验与执行隔离 |
| 一轮里想同时调好几个工具 | 4.3 并行工具调用与结果合并 |
| 不知道该选哪种推理模式 | 5.1 ReAct、5.2 Plan-and-Solve、5.3 Reflexion |
| 对话一长就「忘事」 | 6.2 上下文裁剪与摘要、8.1 对话缓冲与摘要记忆 |
| 想让运行过程实时可见 | 7.1 流式事件模型、15.1 运行追踪 |
| 崩溃后不想从头再跑 | 7.3 检查点与快照 |
| 怎么让 Agent 查自己的资料库 | 10.2 索引与检索工具、10.3 带引用的回答 |
| 一个 Agent 忙不过来 | 13.3 协作模式对照 |
| 重试把订单下了两次 | 14.3 幂等与副作用 |
| 怎么知道改动有没有让效果变好 | 16.2 评测集与打分、16.3 对比实验 |
| 想把 Agent 暴露成 HTTP 接口 | 17.2 HTTP 服务化 |
如果你遇到的问题不在表里，可以先用目录里的关键词搜索定位章节，再结合每节开头的引用块判断是否命中。
小结
这一页的核心信息可以浓缩成三句话：
- 结构上，全书是「前置 3 篇 + 六部分 18 章 54 节 + 附录 4 篇」，共 61 篇，围绕从零手写的
minagent逐章推进。 - 路径上，想系统建立心智模型就顺序通读（8–9 周），有 Python 基础可读 8 节速成，已会用可当参考手册查。
- 方法上，本卷坚持「假模型为主、动手优先、每节可独立阅读」，任何一节都可以单独抽出来看。
如果你已经选好了路径，可以直接从对应的章节开始。每一节的开头都会交代它把 minagent 推进到哪里，跟着主线走不会迷路。
最后再重复一句：本页不需要从头读到尾。它的作用是「在你需要的时候，三秒钟内把你送到正确的那一节」。把这一页加进书签，比记住任何章节编号都有用。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。