《AI Agent 高级编程》目录
这一页是全书的总入口。它不只列出章节标题，还交代本卷怎么读、主线项目 ResearchCopilot 被「框架重写」成了什么样子，以及每一章的一句话导读。如果你不确定从哪开始，先读「本卷怎么读」与「学习节奏」两节；如果你已经有明确目标，可以直接跳到「分部分章节」按编号定位。
全书结构是：目录 1 篇 + 正文 11 章 33 节，共 34 篇。正文按「先看清框架全景、再逐家重写、然后读源码与补持久化、最后做生产化加固」的顺序分为五个部分，主线是把卷二那个用自研引擎搭起来的研究助理服务，改用主流框架重写一遍，并把生产化短板补上。
本卷怎么读
卷一是「把引擎从零造出来」，卷二是「把引擎装进一个能给别人用的产品」，本卷是「把同一件事交给框架，并看清让渡了什么」。这三卷不是难度的简单叠加，而是三种视角：同一件事——一个能多跳检索、带引用回答的研究助理——在三卷里被反复实现，每次换一套工具、换一组约束。
本卷的重心是「对照」而非「教程」。 每一节几乎都在回答同一个问题：这套框架替我做了什么？我又让渡了什么？ 因此读的时候不要只抄代码，要把「自研版怎么做、框架版怎么做、差在哪」这条线一直挂在脑子里。目录篇、每一节的收尾、以及第 11.3 节的全景表，都是在帮你把这条线串起来。
前置知识。 本卷默认你读过卷一与卷二，或者至少有等价经验：知道 Message / ToolCall / Model 协议长什么样，知道一个 Agent 循环是怎么跑的，知道服务化要处理认证、持久化、可观测。如果你只读过其中一卷，第 1 章的四层定位图会把三卷的关系补上，第 11.3 节会把三卷的路径并排给你看。
环境前提。 主线语言是 Python 3.14（本机实测 3.14.6），本卷的虚拟环境位于 /tmp/agentbook/venv3——与卷二不同，框架全部装在这里：pydantic-ai、langgraph、claude-agent-sdk、openai-agents、smolagents、mcp、fastmcp 等，版本号在每一节里都标注为实测值。TS 侧用 Node 26（本机实测 26.5.0），只落在第 8 章这一处独立成章的落点上。
假模型仍然为主，而且有了更好的工具。 本卷的确定性对照主要靠 PydanticAI 自带的两个夹具——TestModel（按输出类型自动合成）与 FunctionModel（自定义「消息 → 响应」函数）。凡是需要「模型行为可控」的地方，都用它们或等价的本地假模型，零凭据、零成本、结果确定。真实 API 调用只出现在第 11.2 节，且需要你明确授权后才运行。
哪些代码真跑了、哪些没跑，正文都会说清楚。 本卷涉及 claude-agent-sdk 与 openai-agents 这类「一跑就真连模型、真花钱」的框架，所以这几节只做 API 表面核对（inspect.signature / dataclasses.fields）并把代码骨架给出，正文会显式标注「需要活的会话才能运行，本节未执行」。这是刻意为之：宁可标清楚没跑，也不编一个好看的数字。
与卷一、卷二的关系
三卷共用同一套引擎契约，名字与形状都不改：
- 卷一《AI Agent 开发入门》 从零手写
minagent：消息与工具协议、循环、推理模式、记忆、编排、评测、服务化。它给你「引擎内部长什么样」。 - 卷二《AI Agent 工程实战》 把
minagent装进ResearchCopilot：REST/SSE 接口、认证与租户隔离、Postgres 持久化、队列与 worker、可观测与 SLO、安全护栏、容器与发布。它给你「服务怎么上线」。 - 卷三（本卷） 用 PydanticAI / Claude Agent SDK / OpenAI Agents SDK / smolagents 重写同一件事，再补上持久化执行、计算机使用、跨 Agent 协议与训练。它给你「框架的边界在哪、什么时候该用、什么时候该自己写」。
同一个能力在三卷里的视角固定不同：卷一「从零实现」、卷二「工程化」、卷三「框架重写 + 生产化」。第 11.3 节有一张「能力 × 卷 × 视角」总表，把这条线一次讲透。
三卷速查：同一件事的三种做法
下表把本套书里反复出现的几个能力，按三卷的视角并排摆开。它的作用是让你在读到本卷某一节时，立刻知道「卷一在对应的位置做了什么、卷二又补了什么」——这也是本卷几乎每一节都在做「对照」的原因。
| 能力 | 卷一（从零实现） | 卷二（工程化） | 卷三（框架重写 + 生产化） |
|---|---|---|---|
| Agent 循环 | 手写 run() 循环，自己定停止条件 | 把循环跑在 worker 里，落库 run 状态机 | 交给框架的 run，只关心挂哪套 trace |
| 工具调用 | 自研 ToolRegistry + schema 生成 | 工具分读写危险三档、挂审批 | 用框架的工具装饰器，权限交给运行时 |
| 记忆 | 手写短期缓冲与长期向量索引 | 记忆做成独立服务，带 TTL 与治理 | 用框架的记忆/检索接口，对照自研版 |
| 编排 | 手写最小图引擎 | 状态机 + 人类在环 | 用 LangGraph 等现成编排器 |
| 持久化 | 检查点文件快照 | Postgres 表 + 事务 | 持久化执行引擎 + 确定性重放 |
| 可观测 | 自研 span 树与成本核算 | OTel 埋点 + 看板 + 告警 | 三家框架 trace 归一成统一 OTel |
| 评测 | 假模型断言轨迹 | 评测集 + CI 质量门 | 假模型 vs 真模型的差距量化 |
读这张表时请留意一件事：卷三并不总是「更高级」。 在循环与工具这两行，卷三其实把控制权让渡给了框架，换来的是更少的自研代码和更快的落地；代价则是「框架报错时你得会读它的源码」（这正是第 5 章存在的理由）。什么时候值得让渡、什么时候该自己写，第 1.3 节的选型方法给的就是这套判断。
版本时效说明
本卷与卷一、卷二最大的不同，是它依赖第三方框架，而框架版本迭代很快。为此本卷做了三件事，请在阅读时留意：
- 版本号一律标实测值，不凭记忆写。 本卷每一节在引入某个框架时，都会写明本机实测的版本号（例如
pydantic-ai 2.55.0、langgraph 1.2.14、openai-agents 0.23.1、smolagents 1.26.0、claude-agent-sdk 0.2.165）。如果你读到本节时框架已经升了大版本，API 细节可能已经变了，但正文里讲的机制——循环怎么转、检查点存哪、trace 怎么串——通常比 API 稳定得多。 - 把「框架用法」与「框架无关的原理」绑定叙述。 凡是讲源码机制的段落（尤其第 5、6 章），正文都会同时给出「这件事的本质是什么」和「这个框架具体怎么做的」。前者不容易过期，后者给你一个可验证的坐标。
- 明确标注「没跑」的地方。 本卷涉及
claude-agent-sdk、openai-agents这类一跑就真连模型、真花钱的框架，这几节只做 API 表面核对并把代码骨架给出，正文会显式写「需要活的会话才能运行，本节未执行」。这是刻意留白，不是偷懒——宁可标清楚没跑，也不编一个好看的数字。
如果你只想记一件事：本卷的机制部分可以放心学，API 部分请以你手上的实际版本为准。
学习节奏：建议 5–6 周
按每周 6–8 小时估算，本卷正文约需 5 周；如果每一节的框架代码都亲手跑一遍、并对照卷一自研版做实验，6 周更从容。本卷比卷二略短，但信息密度更高——每一节都带着「框架 vs 自研」的对照，读得慢一点是正常的。
一份可执行的五周计划
| 周 | 章节 | 本周结束时你手上应该有什么 |
|---|---|---|
| 第 1 周 | 第 1–2 章 | 四层定位图 + 统一 AgentBackend 抽象 + PydanticAI 重写的问答路径 |
| 第 2 周 | 第 3–4 章 | Claude Agent SDK 与 OpenAI Agents SDK / smolagents 的对照笔记 + 三框架同题跑分 |
| 第 3 周 | 第 5–6 章 | 三家框架的源码调用链笔记 + 一个可崩溃恢复、可确定性重放的执行器 |
| 第 4 周 | 第 7–9 章 | 浏览器 Agent 跑通 + A2A 跨语言通信 + Agent RL 的决策清单 |
| 第 5 周 | 第 10–11 章 | 三框架 trace 归一 OTel + 成本延迟治理 + 平台化注册表 + 全景复盘 |
四条阅读路径：
- 系统通读（5–6 周）：按顺序读完 11 章，每节代码都跑一遍。这是唯一能完整建立「框架选型与生产化」心智模型的路径。
- 带问题速查（1–2 天）：直接跳到「常见问题速查」表，按你的症状找到对应小节。
- 只补框架短板（2 周）：如果你已经会从零写 Agent，重点读第 1、2、4、5、10 章；第 3、7、8 章按需选读。
- 只做前沿占位（3–4 天）：如果你只关心站内近乎空白的那几块，直接读第 6 章（持久化执行）、第 7 章（计算机使用与浏览器 Agent）、第 8 章（A2A 与跨语言）、第 9 章（Agent 强化学习）——这四章合起来是本卷与站内既有内容的差异化核心。
不管你走哪条路径，都建议先花十分钟读一遍「三卷速查」与「版本时效说明」两节：前者让你知道本卷在整套书里的位置，后者让你知道哪些内容可以放心学、哪些要以你手上的实际版本为准。
与既有 AI 专题的分工
本站已有一批 AI 与 Agent 相关专题，本卷与它们是互补而非重复的关系，边界写在这里以免误读：
- 与 LLM 专题
的分工：该专题的
llm-agent-frameworks给的是选型矩阵（谁适合什么场景）。本卷给的是源码级调用链与可运行重写——把框架拆开看循环、看重试、看检查点到底怎么写的。一句话：专题告诉你「选哪个」，本卷告诉你「它内部怎么跑」。 - 与 MCP 专题 的分工：该专题覆盖协议规范、Server 实现、传输与授权。本卷只在第 8.2 节讲 A2A（Agent↔Agent）与 MCP（Agent↔工具）的分工边界，协议规范不碰，遇到时链过去。
- 与 AI / AI-ML 专题 的分工：那两个专题覆盖通用微调、量化、推理部署。本卷第 9 章只写 Agent 强化学习这一子集——轨迹、奖励、信用分配、可验证奖励，通用训练流程不重复。
- 与 LLMOps 专题 的分工：该专题讲模型侧的运维与部署。本卷第 10 章讲的是应用侧的统一可观测、成本治理与安全纵深。
一句话概括：专题给你概念与选型，本卷给你可运行的框架代码与源码级理解。
分部分章节
下面按五个部分列出全部 11 章 33 节，每一行给出编号、标题与一句话说明。
表格里的编号规则是「章.节」，例如 7.2 表示第 7 章第 2 节。点击标题即可进入该节正文。每个部分开头都有一段导读，说明这一部分在全卷推进中的位置；如果你只想知道某节讲什么，直接看表格第三列的说明即可。
第一部分：框架全景与统一抽象（第 1 章）
这一部分先不写具体框架，而是把地图画出来：把 Agent 技术栈分成引擎层、编排层、SDK 层、协议层四层，把卷一的 minagent 与卷二的 ResearchCopilot 钉到图上，再定义一个统一的 AgentBackend 抽象，让不同框架能挂到同一个接口上互换，最后给一套可打分的选型方法。
读完这一部分，你会有两样东西：一张能定位任何 Agent 框架的四层图，和一个「换框架不改调用代码」的适配层。后面每一章引进新框架时，都回到这张图和这个抽象上。
| 编号 | 章节 | 说明 |
|---|---|---|
| 1.1 | 框架分层：引擎/编排/SDK/协议四层定位图 | 真 import 各框架佐证分层，把 minagent 与 ResearchCopilot 钉到图上 |
| 1.2 | 统一抽象：一个 Protocol 适配多家并写适配层 | 定义 AgentBackend，让假后端与 PydanticAI 后端挂同一接口互换 |
| 1.3 | 选型方法：按可观测/持久化/生态/锁定度打分 | 四维权重、评分锚点与一个可运行的打分脚本，含敏感度分析 |
第二部分：三大框架重写（第 2–4 章）
这一部分是本卷的主体：把卷二的研究助理服务，依次用 PydanticAI、Claude Agent SDK、OpenAI Agents SDK / smolagents 重写一遍。每一章都遵循同一个套路——先讲核心模型，再讲工具与输出，最后与卷一的自研运行时做对照。
读这一部分要留意一件事：不同框架对「Agent 是什么」的假设并不一样。 PydanticAI 假设「Agent 是一个带类型输出的函数」，Claude Agent SDK 假设「Agent 是一个带权限与子代理的运行时」，smolagents 假设「Agent 就是会写代码的模型」。这些假设决定了它们各自的强项与锁定点。
| 编号 | 章节 | 说明 |
|---|---|---|
| 2.1 | 核心模型：Agent/RunContext/依赖注入重写问答路径 | 用 Agent + RunContext 注入假检索器，重写问答路径 |
| 2.2 | 结构化输出与工具：输出模型 + 校验重试 | output_type 结构化输出，校验失败触发重试的真实调用链 |
| 2.3 | 与 minagent 对照：代码量与可测性对比 | 同任务的框架版 vs 自研版，行数与可测性的诚实对比 |
| 3.1 | 核心概念：subagent/hooks/权限/session 搭研究任务 | 核对 AgentDefinition / HookMatcher 等 API，搭多子代理骨架 |
| 3.2 | 工具与权限：allow/deny 与审批回调 | allowed_tools / permission_mode 与人工审批回调 |
| 3.3 | 与自研运行时对照：内置省了什么、锁定了什么 | 内置省掉调度与持久化，代价是绑定 CLI 与模型 |
| 4.1 | OpenAI Agents SDK：handoff/guardrails/tracing 实现委派 | handoff 委派、护栏与 trace，只核对 API、不发起真实调用 |
| 4.2 | smolagents：CodeAgent「代码即行动」重写子任务 | 用自定义假模型驱动 CodeAgent，真跑「代码即行动」 |
| 4.3 | 三框架同题对照：同评测集比分数与成本 | 同一道题在三个框架上的步数、工具调用与代码量对照 |
第三部分：源码剖析与持久化执行（第 5–6 章）
这一部分回答两个「往下钻」的问题：框架内部的循环到底怎么写的？长时运行的 Agent 崩溃了怎么办？第 5 章打开三个框架的源码，读图执行器、读重试调用链、读子代理与钩子的调度；第 6 章补上持久化执行——崩溃恢复、确定性重放、与自研检查点的边界。
读源码这一章是本卷最「硬」的部分。它不要求你记住每一行，而是让你建立一种能力：遇到一个框架，知道从哪里切进去看它的循环。
| 编号 | 章节 | 说明 |
|---|---|---|
| 5.1 | 读 LangGraph：图执行器与检查点机制 | 超步如何推进、检查点存在哪，贴真实源码路径与行号 |
| 5.2 | 读 PydanticAI：run 循环与重试调用链 | 结构化输出校验失败后如何重试，追到真实调用链 |
| 5.3 | 读 Claude Agent SDK：subagent 与 hook 调度（含 TS SDK 对照） | 循环跑在 CLI 进程，子代理与钩子靠跨进程 RPC |
| 6.1 | 为什么需要持久化执行：崩溃/重启/长任务改造 | 真跑「第 3 步崩溃后从检查点恢复」而不是从头重跑 |
| 6.2 | 确定性重放与副作用：模型调用变可重放步骤 | record/replay 让模型调用可重放，副作用隔离成幂等步骤 |
| 6.3 | 与自研检查点对照：轮子与现成品边界 | 真跑 LangGraph 检查点与 interrupt，对照自研日志引擎 |
第四部分：前沿能力（第 7–9 章）
这一部分把三个「卷一卷二没碰」的能力补齐：计算机使用与浏览器 Agent、跨 Agent 的 A2A 协议、Agent 强化学习。这三样在站内都是近乎空白，也是本卷差异化的核心。
三章的性质不同：第 7 章能真跑（对本地页面与合成屏幕），第 8 章能真跑（本地进程间通信，且含本卷唯一独立成章的 TS 落点），第 9 章不能真跑完整训练闭环——它只讲问题设定、奖励设计与决策清单，代码限定为可运行的最小数据结构与离线打分，不编造任何训练曲线。
| 编号 | 章节 | 说明 |
|---|---|---|
| 7.1 | Computer Use 基础：截图/坐标动作/循环最小实现 | 合成屏幕 + 脚本化假模型，真跑「截图→动作→再截图」 |
| 7.2 | 浏览器 Agent：Playwright 工具化完成网页取数 | Node 版 Playwright 对本地页面真跑，ARIA 快照替代截图 |
| 7.3 | 安全与成本：不可逆动作沙箱与人工确认 | 风险三级分级 + dry-run / 审批 / 配额三道防线 |
| 8.1 | A2A 协议：Agent Card/Task/消息，起两个本地 Agent 通信 | 本地起服务端与客户端，真跑一次 Agent Card 与任务往返 |
| 8.2 | 与 MCP 分工：工具协议 vs 协作协议 | 真跑 FastMCP 与 A2A 组合链路，讲清两者边界 |
| 8.3 | 跨语言 Agent：TS 实现 A2A 端与 Python 协作 | 本卷 TS 落点：TS 与 Python 双向真跑，零 npm 依赖 |
| 9.1 | 问题设定：轨迹、奖励与信用分配 | 轨迹形式化、奖励设计与折扣归因，配可运行示例 |
| 9.2 | 从 SFT 到 RL：工具使用与多步推理训练流程 | 偏好奖励 vs 可验证奖励，四条路径与 Agent RL 的坑 |
| 9.3 | 何时该训、何时调提示：成本收益决策清单 | 五种干预按成本收益排序，含一个可运行的决策打分脚本 |
第五部分：生产化加固与收官（第 10–11 章）
这一部分把前面所有框架重写的东西，按生产标准再加固一遍：统一可观测（三家框架的 trace 归一成 OTel）、成本与延迟治理、安全纵深，最后平台化并做全景复盘。
第 10 章与卷二第 13–15 章是「同题不同视角」：卷二讲自研服务怎么埋点，本卷讲三家框架各不相同的 trace 如何归一。第 11 章是全书收口，11.2 节讲「假模型 vs 真模型」的差距该怎么量化（真模型列需要你授权后才运行），11.3 节把三卷的路径并排给你看。
| 编号 | 章节 | 说明 |
|---|---|---|
| 10.1 | 统一可观测：三框架 trace 归一 OTel | 真埋点 + 本地 exporter，把三框架 span 归一成统一树 |
| 10.2 | 成本与延迟治理：路由/缓存/并发 + 评测兜底 | 真跑语义缓存与预算降级，降级必须过评测兜底 |
| 10.3 | 安全纵深：注入/越权/供应链审计 | 输入侧注入剥离、工具侧越权拦截、依赖审计 |
| 11.1 | 平台化：Agent 注册、版本与配额 | 真跑注册表 + 版本路由 + 配额扣减的最小平台 |
| 11.2 | 真实 API 冒烟：假模型 vs 真模型量化差距 | 对照 harness 真跑假模型列，真模型列需授权后运行 |
| 11.3 | 全景回顾：从零到框架的完整路径与展望 | 「能力 × 卷 × 视角」总表，串起三卷的完整路径 |
常见问题速查
下表把框架选型与生产化里最常撞上的症状映射到对应小节。左列是「你遇到的现象」，右列是「去哪看」。
| 现象 | 去哪看 |
|---|---|
| 不知道某个框架属于哪一层 | 1.1 框架分层 |
| 换框架就要改一堆调用代码 | 1.2 统一抽象 |
| 几个框架都看了，还是不知道选哪个 | 1.3 选型方法 |
| 想让 Agent 直接吐一个结构化对象 | 2.2 结构化输出与重试 |
| 想知道框架到底替我写掉了多少代码 | 2.3 与 minagent 对照 |
| 想让 Agent 有多个子角色 | 3.1 subagent、4.1 handoff |
| 模型想调用不该调用的工具 | 3.2 权限、10.3 安全纵深 |
| 框架一跑就真花钱，不敢试 | 4.1、4.2 用本地假模型驱动 |
| 想知道哪个框架更省步骤/更省代码 | 4.3 三框架同题对照 |
| 框架报错了，但不知道循环里哪一步出的问题 | 5.1–5.3 读源码 |
| 长任务跑到一半进程崩了 | 6.1 持久化执行 |
| 想复现一次线上跑挂的轨迹 | 6.2 确定性重放 |
| 想知道该自己写检查点还是用现成的 | 6.3 与自研检查点对照 |
| 想让 Agent 操作界面/网页 | 7.1 计算机使用、7.2 浏览器 Agent |
| 怕 Agent 点了「删除」「支付」这种不可逆动作 | 7.3 不可逆动作沙箱 |
| 想让两个 Agent 互相协作 | 8.1 A2A 协议 |
| 分不清 A2A 和 MCP 该用哪个 | 8.2 工具协议 vs 协作协议 |
| 想让 TS 服务和 Python Agent 通信 | 8.3 跨语言 Agent |
| 想把 Agent 的行为「训」得更好 | 9.1、9.2 轨迹与奖励 |
| 不知道到底该训模型还是改提示词 | 9.3 何时该训、何时调提示 |
| 三家框架的 trace 各长各的，拼不起来 | 10.1 统一可观测 |
| 模型账单又涨了，但不知道贵在哪 | 10.2 成本与延迟治理 |
| 检索回来的文档里藏着指令 | 10.3 安全纵深 |
| 公司里有一堆 Agent，想统一管起来 | 11.1 平台化 |
| 想知道假模型跑出的好成绩算不算数 | 11.2 假模型 vs 真模型量化差距 |
| 框架升了版本，正文里的 API 还对得上吗 | 版本时效说明（本节） |
| 想知道卷一自研版和卷三框架版差在哪 | 2.3 与 minagent 对照、三卷速查表（本节） |
| 不确定该用框架还是继续自己写 | 1.3 选型方法、3.3 内置省了什么锁定了什么 |
| 想让 Agent 写代码来完成任务而不是调工具 | 4.2 smolagents CodeAgent |
| 想知道 Agent 一次跑多少步、花多少 token | 4.3 三框架同题对照、10.2 成本治理 |
| 框架的 trace 能不能接到现有的观测系统 | 10.1 统一可观测 |
| 想让 Agent 在没人看着的时候也能跑长任务 | 6.1 持久化执行、7.3 不可逆动作沙箱 |
| 想回头看看三卷到底讲了什么 | 11.3 全景回顾 |
小结
这一页的核心信息可以浓缩成三句话：
- 结构上，全书是「目录 1 篇 + 五部分 11 章 33 节」，共 34 篇，主线是用框架重写卷二的研究助理服务
ResearchCopilot并做生产化加固。 - 路径上，系统通读 5–6 周；有明确症状可以查「常见问题速查」；已会从零写 Agent 的话，重点读第 1、2、4、5、10 章。
- 方法上，本卷坚持「假模型为主、真跑为据、对照为线」——正文里出现的每一个输出，都是在本机真实执行过的结果；涉及真实模型调用的部分会明确标注「未执行」，而不是编一个好看的数字。
本卷是三卷本的收官卷。读完之后，你手里应该有一套完整的东西：一个从零手写的引擎（卷一）、一个能上线的服务（卷二）、以及一份「什么框架适合什么场景、它内部怎么跑、该让渡什么」的判断力（本卷）。这三样加起来，才是「会做 Agent」而不是「会用某个框架」。
最后再重复一句：本页不需要从头读到尾。它的作用是「在你需要的时候，三秒钟内把你送到正确的那一节」。把这一页加进书签，比记住任何章节编号都有用。
给不同读者的三句话：
- 如果你是从卷一一路读过来的，本卷是你最该慢读的一卷——它不教你新概念，而是逼你回答「我原来那样写，是不是白写了」。答案常常是「没有白写，但也不必再写一遍」，这正是选型能力的来源。
- 如果你是直接跳到本卷的，请至少补读卷一的第 1、3 章（消息协议与循环）和卷二的第 1 章（架构边界）。本卷几乎每一节都在引用这两个基础，缺了它们，对照会读得很吃力。
- 如果你是带着具体问题来的（「我们的 Agent 一崩就要从头跑」「我们不知道选哪个框架」），直接翻「常见问题速查」，不必按顺序读。
一句话记住本卷的方法论： 先问「这件事框架替我做得好不好」，再问「让渡的代价我承不承受得起」。凡是这两问都答得清楚的场景，用框架；答不清楚的，回卷一自己写。第 11.3 节会把这条方法论收束成一张能带走的总表。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。