《AI Agent 工程实战》目录

《AI Agent 工程实战》目录

这一页是全书的总入口。它不只列出章节标题，还交代本卷怎么读、贯穿项目 ResearchCopilot 的定位，以及每一章的一句话导读。如果你不确定从哪开始，先读「本卷怎么读」与「学习节奏」两节；如果你已经有明确目标，可以直接跳到「分部分章节」按编号定位。

全书结构是：目录 1 篇 + 正文 18 章 54 节，共 55 篇。正文按工程推进的顺序分为六个部分，每一部分解决一类问题，并围绕一个从卷一引擎长出来的研究助理服务 ResearchCopilot 逐步长大。

本卷怎么读

卷一是「把引擎造出来」，本卷是「把引擎装进一个能给别人用的产品」。这个转向意味着阅读方式要换：卷一每一节都能独立跑通，本卷则有前后依赖——第 5 章建的表，第 7 章的 worker 要用；第 3 章定的错误契约，第 4 章的认证要遵守。跳过中间章节直接读后面，会遇到「这个类型哪来的」。

环境前提。 主线语言仍是 Python 3.14（本机实测 3.14.6），配套虚拟环境位于 /tmp/agentbook/venv；TS 侧用 Node 26（本机实测 26.5.0），依赖装在 /tmp/agentbook/ts。与卷一不同，本卷放心使用工程库：pydantic-settings、FastAPI、psycopg、redis、mcp 等都会真正装、真正用，版本号在每一节里都标注为实测值。

两个本地服务。 本卷大量章节需要 Postgres 与 Redis。全卷统一用这两个连接串：

docker run -d --name ab-pg -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=research -p 15435:5432 postgres:17-alpine
docker run -d --name ab-redis -p 16380:6379 redis:7-alpine

注意端口是 15435 与 16380，不是默认的 5432 / 6379——本机这两个默认端口已被占用，用非默认端口是为了不和别的服务打架。每一节需要连库时都会重复给出这两条命令。

假模型仍然为主。 本卷不依赖真实模型 API 就能读完全部内容：所有演示默认走假模型路径，零凭据、零成本、结果确定。真实调用只出现在第 2 章的适配器写法与第 18.3 节的可选冒烟里，且需要你自备密钥、自行决定是否消耗额度。

需要卷一的底子。 本卷复用卷一立下的核心契约：Message / ToolCall / ModelResponse / Model 协议、Tool / ToolRegistry、run() 循环、FakeModel 脚本、AgentLoopError。这些名字在本卷出现时不再重新解释，只说明「服务层怎么用它」。如果这些名字对你陌生，先读卷一第 1、3、4 章。

贯穿项目：ResearchCopilot

ResearchCopilot 是一个研究助理服务：用户提问 → Agent 多跳检索本地语料 → 调用工具（含本地 Postgres 查询）→ 生成带引用的报告；后台 worker 周期跑语料更新与日报。

它被选作贯穿项目，是因为四个工程问题在它身上都自然出现：

• 工具调用天然分层——search / read / calc 只读，save_note / delete_run 写入，读写分离不是硬凑的。
• 记忆天然有长短期之分——语料索引是长期，会话是短期，recall 正好可以做成「记忆即工具」。
• 编排天然是 DAG——规划 → 并行检索 → 综合 → 引用校验。
• 评测有客观信号——引用能不能在语料里找到、答案有没有被语料支持，是可以用代码判定的。

本卷每推进一章，ResearchCopilot 就多一块能力：第 3 章有了 API，第 5 章有了持久化，第 7 章有了异步执行，第 10 章有了外部工具生态，第 16 章能被打包部署。

学习节奏：建议 6–8 周

按每周 6–8 小时估算，本卷正文约需 6 周；如果每一节的代码都亲手跑一遍并做课后改动，8 周更从容。

一份可执行的六周计划

三条阅读路径：

• 系统通读（6–8 周）：按顺序读完 18 章，每节代码都跑一遍。这是唯一能完整建立「Agent 服务怎么上线」心智模型的路径。
• 带问题速查（1–2 天）：直接跳到「常见问题速查」表，按你的症状找到对应小节。
• 只补工程短板（2 周）：如果你已经会写 Agent，但没做过服务化，重点读第 3、5、7、8、13、16 章；第 1、2、4 章可以略读。

与既有 AI 专题的分工

本站已有一批 AI 与 Agent 相关专题，本卷与它们是互补而非重复的关系，边界写在这里以免误读：

• 与 MCP 专题 的分工：该专题覆盖协议规范、Server 实现、传输与授权等完整内容。本卷只写一件事——minagent 作为 MCP client，把外部 Server 暴露的工具接进自己的工具注册表（第 10.1 节）。协议本身怎么写，本卷不碰。
• 与 LLM 专题 的分工：该专题讲 Agent 架构、工具调用、记忆、多 Agent 协作等概念与方法。本卷把这些概念落成可运行的服务代码，重点在工程约束：并发、事务、限流、灰度、故障演练。
• 与 LLMOps 专题 的分工：该专题讲模型侧的运维与部署。本卷讲的是应用侧的运维——评测门、追踪、SLO、成本治理。
• 与 可观测性专题 、Kubernetes 专题 的分工：那两个专题是通用基础设施知识。本卷只讲 Agent 服务在这两套体系里的特有之处：span 树怎么建、GenAI 语义约定填什么字段、队列积压怎么告警。

一句话概括：专题给你概念，本卷给你一台能跑起来的服务。

分部分章节

下面按六个部分列出全部 18 章 54 节，每一行给出编号、标题与一句话说明。

表格里的编号规则是「章.节」，例如 13.2 表示第 13 章第 2 节。点击标题即可进入该节正文。每个部分开头都有一段导读，说明这一部分在工程推进中的位置；如果你只想知道某节讲什么，直接看表格第三列的说明即可。

第一部分：项目地基（第 1–4 章）

这一部分解决「我们要造什么、怎么配、接口长什么样、谁能用」四个问题。读完能有一个跑得起来的 API 服务骨架，带认证与租户隔离。

节奏上这一部分刻意放慢。第 1 章定下的架构边界（引擎 / 服务 / worker / 存储）会约束后面每一章的代码往哪放；第 3 章定下的错误契约会被第 4、15 章反复引用。

第二部分：数据与性能底座（第 5–6 章）

这一部分解决「状态存在哪、怎么保证不出错、怎么不被打爆」。它把服务从「内存里跑跑」推进到「重启不丢数据、并发不出错、滥用有上限」。

这是全卷最偏基础设施的一段，也是最容易被跳过的一段。但第 5.2 节的原子状态跃迁与第 6.3 节的配额，恰恰是后面第 7 章队列与第 14 章成本治理的地基。

第三部分：异步与前端（第 7–9 章）

这一部分解决「长任务怎么跑、并发怎么控、结果怎么实时给人看」。读完服务能异步执行、能在压力下不崩、能给前端逐步显示过程。

第 7 章把「一次 run」从同步请求改造成异步任务，这是服务架构上的一次分水岭；第 9 章是本卷的 TS 落点，用 TypeScript 把事件消费掉、渲染出来、断线后接上。

第四部分：生态、记忆与质量（第 10–12 章）

这一部分解决「能力从哪来、记住什么、怎么知道变没变差」。读完能接入外部工具生态、把记忆做成服务、用评测门拦住退化。

第 10 章的边界必须说清楚：MCP 在本卷里只作为工具来源被消费，协议与 Server 实现不在本卷范围。第 12 章的质量门是后面第 14、17 章反复引用的兜底机制。

第五部分：可观测、性能与安全（第 13–15 章）

这一部分解决「线上出问题怎么查、又贵又慢怎么办、被人钻空子怎么办」。读完能回答三个问题：慢在哪、贵在哪、错在哪。

第 13 章的 span 树是第 14 章成本剖析与第 18 章故障演练的数据来源；第 15 章的护栏与第 4 章的权限是一对——一个管「谁能做」，一个管「模型能不能被诱导去做」。

第六部分：交付（第 16–18 章）

这一部分把前面所有东西装进镜像、发上线、并在出故障时知道怎么办。读完能独立完成一次从构建到上线的完整交付。

第 16 章是本卷第二个 TS 落点（双栈镜像）；第 17 章把第 12 章的评测接进流水线；第 18 章的故障演练是对全卷的一次反向检验——前面每一章的防护，都要在这里被主动打破一次。

常见问题速查

下表把工程里最常撞上的症状映射到对应小节。左列是「你遇到的现象」，右列是「去哪看」。

小结

这一页的核心信息可以浓缩成三句话：

• 结构上，全书是「目录 1 篇 + 六部分 18 章 54 节」，共 55 篇，围绕研究助理服务 ResearchCopilot 逐章推进。
• 路径上，系统通读 6–8 周；有明确症状可以查「常见问题速查」；已会写 Agent 但缺工程经验的话，重点读第 3、5、7、8、13、16 章。
• 方法上，本卷坚持「假模型为主、真跑为据、每节可复现」——正文里出现的每一个输出，都是在本机真实执行过的结果；跑不了的部分会明确标注原因，而不是编一个好看的数字。

本卷之后是《AI Agent 高级编程》：同一个项目，改用 PydanticAI、Claude Agent SDK、OpenAI Agents SDK、smolagents 等框架重写，并补齐持久化执行、计算机使用、跨 Agent 协议与训练相关的内容。如果你已经能独立完成本卷的交付流程，可以直接进入卷三。

最后再重复一句：本页不需要从头读到尾。它的作用是「在你需要的时候，三秒钟内把你送到正确的那一节」。把这一页加进书签，比记住任何章节编号都有用。