《AI Agent 开发入门》全 61 篇，是一套以一个从零手写的 Agent 运行时为主线的入门书：从第 1 章定义
Message与Role起，到第 18 章把引擎组装成端到端项目，minagent会一路长大——二十行的朴素循环、可替换的模型接口、工具注册表与并行调用、三种推理模式、上下文裁剪、短期与长期记忆、本地可离线向量检索、任务分解与图编排、多 Agent 消息总线、错误分类与重试、span 追踪与成本核算、确定性测试与评测集、最后收敛成一个稳定的库接口与 HTTP 服务。所有示例基于 Python 3.14（本机实测 3.14.6）实跑，默认走假模型路径，零凭据、零成本、逐字节可复现。
本页是《AI Agent 开发入门》的全书目录：按章节顺序列出全部 61 篇，点击标题直达正文。也可以从各节末尾的「阅读导航」按顺序通读，或先看目录篇 里的三条学习路径与八到九周计划。
全书概览
| 项目 | 内容 |
|---|---|
| 书稿 | 《AI Agent 开发入门》 |
| 篇数 | 61 篇（正文 18 章 54 节 + 目录篇 + 序 + 前言 + 附录 A–D） |
| 领域 | AI Agent 引擎从零实现到可交付服务 |
| 贯穿项目 | minagent —— 一台从零手写的 Agent 运行时，18 章逐步长大 |
| 阅读方式 | 从目录篇 进入按顺序通读，或按查漏场景跳读 |
| 实测版本 | Python 3.14.6（本机 Homebrew）、Node 26.5.0（第 17 章 TS 对照） |
| 依赖 | 正文第 1–16 章只用标准库；pydantic / httpx / anthropic / fastapi 仅在明确标注「可选」处引入 |
| 上级专题 | 书稿专题 |
全书目录
前置
| 节 | 文章 | 核心内容 |
|---|---|---|
| — | 目录与学习路径 | 全书导航页：本卷怎么读、三条阅读路径与八到九周计划、六部分依赖关系与 54 节逐节索引 |
| — | 序 | 更高视角：为什么现在要学 Agent 开发、本书的写法取舍与常见误解 |
| — | 前言 | 本书怎么来的、写给谁、技术栈与版本口径、三卷结构、本书不写什么 |
| 附 A | 附录 A.minagent API 与模块速查 | Message / ToolCall / ModelResponse / Tool / ToolRegistry / run / Agent 的签名与语义速查，含 model.calls 断言法 |
| 附 B | 附录 B.FakeModel 脚本语法与测试夹具速查 | 三种脚本元素（str / ToolCall 列表 / ModelResponse）的语义对照、四种脚本模式、调用序列断言、真实响应录制回放夹具 |
| 附 C | 附录 C.环境与离线复现速查 | Python 3.14 venv、依赖安装源、Node 26 可擦除语法约束、Docker 起 postgres/redis、零网络复现步骤 |
| 附 D | 附录 D.常见错误与 FAQ | 高频报错原文与最小复现：假模型脚本耗尽、工具参数不匹配、JSON 解析失败、SSE 断流、max_steps 撞线……每条给原因与修法 |
第一部分：引擎地基（第 1–3 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 1.1 | 1.1 环境与仓库骨架 | 建好 minagent/ 目录结构、配好 venv、理解全卷的代码组织与运行方式 |
| 1.2 | 1.2 Agent 的最小定义与消息协议 | 定义 Message / Role / ToolCall，理解 Agent 的最小构成与消息的序列化回放 |
| 1.3 | 1.3 可编程假模型 FakeModel | 用脚本驱动的假模型替换真实调用，零凭据跑通第一轮对话 |
| 2.1 | 2.1 Model 协议设计 | 用 Protocol 定义 Model，把「调用大模型」变成可替换抽象；EchoModel 与 ScriptedModel |
| 2.2 | 2.2 真实供应商适配与离线替身 | 写一个真实供应商适配器（可选），把真实响应录成夹具离线重放 |
| 2.3 | 2.3 Token 预算与截断策略 | 估算 token、设定预算，在超限时按策略裁剪；BudgetedModel 装饰器 |
| 3.1 | 3.1 朴素循环：跑到没有工具调用为止 | 写出第一个 run() 循环，理解「多轮」从哪来、RunResult 有哪三件东西 |
| 3.2 | 3.2 停止条件与循环上限 | 五条止损线：自然收敛、max_steps、max_tokens、工具连续失败、重复动作；用 AgentLoopError 把异常终止变成数据 |
| 3.3 | 3.3 抽成 Agent 类：状态、步骤与回调 | 把循环收进 Agent 类，暴露 on_step / on_tool_call 回调与 history 状态 |
第二部分：能力扩展（第 4–7 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 4.1 | 4.1 工具即函数：schema 生成、注册表与分发 | 用 Tool 与 ToolRegistry 把普通函数暴露给模型，自动生成 schema |
| 4.2 | 4.2 参数校验与执行隔离 | 校验工具入参、隔离异常，让错误以 {"error": ...} 结果而非崩溃呈现 |
| 4.3 | 4.3 并行工具调用与结果合并 | 一轮里同时调用多个工具，按顺序合并结果；量化并发收益 |
| 5.1 | 5.1 ReAct：把「想—做—看」写进循环 | 把思考、行动、观察三段式嵌进循环，并解释它为何只是同一个循环的变体 |
| 5.2 | 5.2 Plan-and-Solve：先出计划再执行 | 让模型先给计划再逐步执行，减少来回试探与无效调用 |
| 5.3 | 5.3 Reflexion：失败后的自我修正 | 失败后回看轨迹、生成反思，再重试一次；对照三种模式的代价 |
| 6.1 | 6.1 系统提示与指令分层 | 把系统、开发者与用户指令分层，用 model.calls 验证分层是否真的落到消息里 |
| 6.2 | 6.2 上下文裁剪与摘要 | 超预算时裁剪历史或用摘要压缩，保留 system 与最近上下文 |
| 6.3 | 6.3 结构化输出约束与解析兜底 | 约束模型输出 JSON，解析失败时带错误重试一次 |
| 7.1 | 7.1 流式事件模型 | 用 token / tool_call / step / error 事件流描述一次运行，让每一步都可被订阅 |
| 7.2 | 7.2 会话状态对象 | 用 Session 承载多轮状态，隔离不同会话的历史 |
| 7.3 | 7.3 检查点与快照 | 把状态存盘，崩溃后能从检查点续跑而不重头再来 |
第三部分：记忆与知识（第 8–10 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 8.1 | 8.1 对话缓冲与摘要记忆 | 用缓冲与摘要两种策略保存近期对话，权衡保真度与体积 |
| 8.2 | 8.2 记忆检索注入 | 从记忆里挑出相关片段，注入到当前上下文而非全量塞入 |
| 8.3 | 8.3 记忆写入策略 | 决定什么该记、什么时候记、记多细，以及如何按相似度去重 |
| 9.1 | 9.1 嵌入与向量存储：本地可离线方案 | 手写一个可离线的嵌入与向量索引（仅第 9 章用到 numpy） |
| 9.2 | 9.2 混合检索：关键词 + 向量 + 重排 | 融合关键词与向量召回，再加一层重排，量化各自贡献 |
| 9.3 | 9.3 记忆即工具 | 把记忆读写暴露成 recall / save_note 工具，交给模型自己决定何时用 |
| 10.1 | 10.1 文档加载与切分 | 加载文档并按语义边界切成可检索的块，对本站文章目录跑切块统计 |
| 10.2 | 10.2 索引与检索工具 | 提供 search 与 read 两个工具，让 Agent 自己查知识库 |
| 10.3 | 10.3 带引用的回答 | 让答案附上来源引用，可追溯、可核对，并校验引用是否真的支持结论 |
第四部分：编排与协作（第 11–13 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 11.1 | 11.1 任务分解：把大问题拆成子任务 DAG | 把目标拆成有依赖关系的子任务图，识别可并行的部分 |
| 11.2 | 11.2 计划执行器 | 按依赖顺序执行子任务，汇总中间结果，支持串行与并行 |
| 11.3 | 11.3 重规划 | 执行受阻时回看计划，局部重排而非全盘重来 |
| 12.1 | 12.1 状态机式编排 | 手写一个最小图引擎：节点、边与状态流转 |
| 12.2 | 12.2 分支、合并与循环 | 支持条件分支、并行合并与带出口的循环 |
| 12.3 | 12.3 人类在环 | 在关键节点暂停，等待人工确认后继续，并保留可恢复的中间状态 |
| 13.1 | 13.1 角色与分工 | 用 supervisor / worker 划分职责，各司其职 |
| 13.2 | 13.2 消息总线与共享状态 | 用进程内消息总线连接多个 Agent，隔离与共享各自的边界 |
| 13.3 | 13.3 协作模式对照 | 顺序、辩论、投票三种拓扑的步数 / 延迟 / 成本量化对照，判断何时值得上多 Agent |
第五部分：可靠性与度量（第 14–16 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 14.1 | 14.1 分类错误与重试 | 把错误分类，只对可重试的做退避重试，不可重试的快速失败 |
| 14.2 | 14.2 超时、取消与结构化并发 | 用 asyncio.TaskGroup 统一管理超时与取消，避免任务泄漏 |
| 14.3 | 14.3 幂等与副作用 | 识别有副作用的工具，用幂等键让重试不产生重复影响 |
| 15.1 | 15.1 运行追踪 | 把一次运行变成 span 树，记录完整的调用结构 |
| 15.2 | 15.2 结构化日志与关联 ID | 输出可检索的结构化日志，用关联 ID 串起全链路 |
| 15.3 | 15.3 成本与用量核算 | 累计 token 用量，换算成可比较的成本，按模型与步骤归集 |
| 16.1 | 16.1 确定性测试 | 用假模型与断言轨迹写出确定性测试，把「模型看到了什么」变成可断言事实 |
| 16.2 | 16.2 评测集与打分 | 建一个小评测集，用引用可回溯与答案可支持两类信号打分 |
| 16.3 | 16.3 对比实验 | 一次只改一个变量，用对比实验判断改动到底有没有让效果变好 |
第六部分：交付（第 17–18 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 17.1 | 17.1 库的对外接口 | 收敛出一个稳定的公开接口，隐藏内部实现，讲清版本策略与破坏性变更 |
| 17.2 | 17.2 HTTP 服务化 | 用 FastAPI 与 SSE 把引擎暴露成可流式调用的服务 |
| 17.3 | 17.3 TS 落点一：同一协议的 TS 客户端 | 用 TypeScript（Node 26 可擦除语法）写一个遵循同一协议的客户端 |
| 18.1 | 18.1 端到端 | 组装工具、记忆、检索与编排，跑通从提问到带引用回答的完整任务 |
| 18.2 | 18.2 真实 API 冒烟（可选） | 可选地用真实供应商做一次冒烟验证，对照假模型与真模型的差异 |
| 18.3 | 18.3 回顾与路线 | 回顾 minagent 的演进路径，给出进阶学习路线与进入实战卷的衔接 |
怎么用这份索引
- 顺序通读：从第 1 章 1.1 开始，每一节末尾都有上一节 / 下一节的导航。若不确定从哪开始，先看目录篇的三条学习路径 。
- 按问题跳读：假模型脚本耗尽看 1.3、循环停不下来看 3.2、工具报错被吞看 4.2、上下文被裁得丢信息看 6.2、模型输出不是合法 JSON 看 6.3、长任务忘事看 8.2、检索不准看 9.2、多跳问答串不起来看 11.2、想上多 Agent 前先看 13.3、超时没生效看 14.2、测试不稳定看 16.1。附录 D 另有一张按报错原文索引的速查表。
- 只查 API：直接翻附录 A 与附录 B ，前者是引擎核心类型的签名速查，后者是假模型脚本与测试夹具的写法对照。
- 想动手：18 章全程只有
minagent一个项目，每一节都在它的真实代码上推进，可以边读边改。环境与离线复现步骤见附录 C 。
相关阅读
- LLM / AI 开发专题 — 从 API 调用到生产级智能应用的专题级深度文章，与本卷互补
- MCP 专题 — Model Context Protocol 的协议、Server 与传输细节；本卷只讲「作为 client 接工具源」
- AI / 机器学习专题 与 AI-ML 专题 — 模型原理、微调与部署的专题文章
- LLMOps 专题 — Agent 与 LLM 应用的上线与运维
- 测试专题 — 测试策略与质量体系的系统方法，与本卷第 16 章衔接
- 可观测性专题 — 日志、指标、链路追踪，与本卷第 15 章衔接
- 书稿专题 — 全部在线电子书与创作手记