《AI Agent 开发入门》前言

关于这本书

这是一本写给「想真正学会 Agent 开发」的人的书，而不是一本写给「想在面试前背几个概念」的人的书。全书共 18 章 54 节，另加序、前言、目录三篇前置内容与附录 A 到 D 四篇，合计 61 篇。它假定你愿意动手写代码、愿意在报错信息里泡一会儿、愿意花时间想清楚「为什么这样设计」，而不是只想知道「这样写能不能跑」。

在正文开始之前，这一篇把体例讲清楚：这本书写给谁、怎么组织、代码按什么约定写、不同的人应该怎么读。读完它，你就能判断该从哪一页开始，以及哪些部分可以放心跳过。

目标读者与前置知识

最低前置知识：会写 Python，能使用命令行。Agent 开发本身不要求任何框架经验，本书从零讲起。具体来说，你最好已经具备：

• 能读写 Python 的类、函数、dataclass 与类型标注；
• 知道什么是虚拟环境（venv），能在终端里切换目录、执行命令；
• 大致理解 HTTP 与 JSON，能读懂最基础的英文报错信息里的关键词。

如果你有 Python 基础但没写过 Agent，这本书就是为你写的。它不会预设你懂任何 Agent 框架，唯一的建议是按顺序读、每节动手敲，不要跳章。Agent 的知识是层层叠加的——不理解消息协议，就读不懂循环；不理解循环，就读不懂工具调用与编排。

如果你已经用过某个 Agent 框架，你可以快速扫过第 1、2 章，但请留意三处框架通常替你隐藏的地方：循环的停止条件（第 3 章）、工具结果的合并方式（第 4 章）、上下文是怎么被裁剪的（第 6 章）。这三处是框架使用者最容易「知其然不知其所以然」的地方。

如果你完全没接触过异步编程，也不必担心。本卷用到 asyncio 的地方集中在第 14 章，前面十五章都是同步代码；真到了异步那章，正文会从最基础的 async / await 讲起。

全书结构：六部分 18 章

全书按学习曲线分为六个部分，每一部分解决一类问题：

每一部分的内部也是递进的。以第二部分为例：第 4 章先让模型能调工具，第 5 章才讲几种让循环更可控的推理模式，第 6 章才处理上下文预算，第 7 章才把过程流出来——这一顺序不是随意的，没有工具调用，推理模式就无从谈起；没有循环，可观察性也无从附着。

需要强调的是，六个部分由同一个项目 minagent 串联。第 1 章用它建起仓库骨架，第 3 章让它的循环跑起来，第 4 章给它接上工具，第 9 章给它装上记忆，第 17 章把它服务化。每节开头的引用块都会说明「本节把 minagent 推进到哪一步」，读的时候留意这条主线，知识点才不会散。

每一节的组织方式

为了让 54 节保持一致的节奏，正文的每一节都按同样的五段式组织：

1. 本节目标：开头用一小段话说明这一节要解决什么问题、读完之后你能做什么。
2. 正文小节：主体内容，以 ## X.Y 为节标题，其下再用 ### X.Y.n 细分。每个小节聚焦一个具体问题，尽量给出可运行的代码与真实输出。
3. 小结：末尾用几句话收束，点明这一节最值得记住的判断标准，而不是复述正文。
4. 真实模型下会怎样：说明假模型与真实 API 的差异，让你知道哪些结论会随供应商而变。
5. 阅读导航：正文末尾一行给出「上一节 / 下一节」的链接，方便顺序阅读。

也就是说，每一节的开头都长这样：

本节把 minagent 推进到：……（这一节新增的能力）

这种结构的代价是每节都有一些重复的仪式感，好处是你随时可以抽出一节独立阅读，而不必担心缺少上下文。当作参考手册用时，这一点会尤其方便。

需要说明的是，本页（前言）以及序、目录和四篇附录并不遵循上面的五段式——它们不是「一节正文」，因此没有开头的目标引用块，也没有末尾的阅读导航行，而是以正常的段落收尾。这一点在你翻到附录时不必觉得奇怪。

技术栈与版本口径

这是全书唯一集中交代版本的地方，请留意它，因为后面每一节都会默认你已经知道这些口径。

• 主线语言是 Python 3.14，本机实测为 3.14.6。书中代码与输出均以此为准，官方同期最新补丁版本可能略有不同，同一版本线（3.14.x）内的补丁差异不影响本书结论。
• 对照线是 TypeScript（Node 26）。TS 片段全部只用「可擦除语法」（type stripping），node file.ts 可零构建直接运行；类型检查用 npx tsc --noEmit。TS 主要出现在第 17 章，用来证明协议与事件模型是语言无关的。
• 卷一核心零第三方依赖。minagent 引擎在前十六章只用 Python 标准库（dataclasses / typing / json / asyncio / sqlite3 / math / re / hashlib）。只有在明确标注「可选」的地方才引入第三方依赖。
• 假模型是默认路径。真实 API 调用只在全卷末尾第 18.2 节出现一次，且是可选步骤，需要你自备密钥并自行决定是否消耗额度。

各组件已实测的版本如下表，供你在自己环境里对照。凡本卷引入第三方依赖，都会标明「可选」，并给出确切的版本基线。

判断 Python 版本，用 sys.version_info 而不是字符串比较：

import sys

print("running:", sys.version.split()[0])
if sys.version_info[:2] >= (3, 14):
    print("主版本线为 3.14")

running: 3.14.6
主版本线为 3.14

代码怎么跑：venv 与假模型

为了让示例能开箱即用，本书在运行方式上有几条统一约定。

• 虚拟环境：配套 venv 位于 /tmp/agentbook/venv，Python 为 3.14.6。运行任何示例，都用它的解释器：/tmp/agentbook/venv/bin/python。
• 默认零凭据：全书默认走假模型，不需要任何 API 密钥、不联网、不产生费用。你可以在断网的机器上完整跑通前十七章。
• 代码块都标语言：python 表示 Python 代码，typescript 表示 TS 代码，bash 表示命令行，text 表示真实输出或报错原文，yaml / json / sql 表示配置与脚本。
• 输出与代码分离：代码块之后紧跟的 text 代码块，是这段代码在本机跑出的真实输出，不是示意。
• 可选依赖的安装源：本机实测 PyPI 官方源与部分镜像不可靠，安装第三方包时统一用中科大源：

python -m pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple pydantic

Looking in indexes: https://mirrors.ustc.edu.cn/pypi/simple
Successfully installed pydantic-2.14.0

下面是符合上述约定的最小示例，你可以用它验证环境是否配置正确。它定义了一个最简单的假模型，并跑通一轮对话：

from dataclasses import dataclass, field

@dataclass
class Message:
    role: str
    content: str = ""

@dataclass
class ModelResponse:
    message: Message
    stop_reason: str = "end_turn"
    usage: dict = field(default_factory=dict)

class FakeModel:
    def __init__(self, script):
        self.script = list(script)
        self.calls = []

    def complete(self, messages, tools=None):
        self.calls.append((list(messages), list(tools or [])))
        return self.script.pop(0)

m = FakeModel([ModelResponse(Message("assistant", "你好，我是假模型。"))])
out = m.complete([Message("user", "在吗")])
print(out.message.content)
print("模型被调用了", len(m.calls), "次")

你好，我是假模型。
模型被调用了 1 次

三卷结构预告

这套书稿按难度分为三卷，卷一是起点，另外两卷在它之上叠加能力。

卷一刻意在某几处停住，把更深入的内容留给后两卷：并发深度（第 13–14 章只写到「会用 + 能用假模型复现」）、生产化加固（限流、熔断、灰度、部署，留给卷二）、框架用法（卷一不依赖任何 Agent 框架，留给卷三）。如果你读完卷一觉得「还不够深」，那正是设计如此——先走通一条完整的路，再回头补深度，比一上来就啃框架要有效得多。

学习时间估算

为了让「按需跳读」这条路径可执行，这里给出一份粗略的时间参考（按每天投入一小时计）：

总计约 8 到 9 周可以完成一遍系统学习。如果你的目标是「两周内写出第一个能用的 Agent」，那么集中读第 1、2、3、4 章，跳过记忆与编排部分，也能获得一个可用的起点——只是后面遇到上下文与工具问题时仍需要回来补课。

与既有 AI 专题的分工

本站的 AI 专题已经积累了约 250 篇文章，覆盖提示工程、检索增强、模型评测、MCP、LLMOps 等方向，其中与 Agent 直接相关的至少 25 篇。它们质量不低，但有一个共同的特点：每一篇都假设你已经理解 Agent 是什么，然后带你在某个单点上钻深。

这本书与它们的分工，靠的是从零手写 + 假模型可断言的轨迹。卷一的每一节都以 minagent 的推进为主线，概念服务于可运行代码；站内专题则负责就一个问题钻到底。两者是互补关系：本书负责按顺序搭起一台引擎，专题负责在某个方向上深挖。

需要特别说明的是框架用法：卷一不依赖任何 Agent 框架。若正文提到它们，只作「后面会对照」的预告，不展开、不给可运行代码——框架对照留给卷三。

本书不写什么

说清楚不做什么，往往比说清楚做什么更有助于建立正确的预期。这本书不会：

• 深入多 Agent 与并发的生产级细节。 第 13、14 章只讲到「会用 + 能用假模型复现」，生产化加固留给卷二。
• 教你用某个具体框架。 卷一坚持从零手写，框架用法与对照留给卷三。
• 覆盖模型训练、微调与底层推理优化。 这些属于另一个方向，不在本书范围。
• 承诺读完就能上线生产。 18 章 54 节能让你扎实地入门并交付一台可运行的引擎，但「生产级」是项目里磨出来的。

关于配套资源

本书不附带独立的代码仓库，原因很简单：minagent 的每一节代码都保持为自包含、可复制的最小片段。与其维护一份可能随时间腐坏的仓库，不如让每一段代码都能就地跑起来。

真正值得你准备的配套环境只有两样：一个装好 Python 3.14 的本机环境（或直接使用 /tmp/agentbook/venv），以及一个能运行 Python 的编辑器。附录承担了「速查」的角色——附录 A 汇总 minagent 的核心 API，附录 B 汇总假模型脚本语法，附录 C 汇总环境与离线复现步骤，附录 D 汇总常见错误。它们不按教学顺序组织，而是按查阅顺序组织，适合在你写代码卡住时随手翻。

关于怎么判断自己真的学会了

学完一章之后，怎么知道自己是真懂了还是「读懂了」？这个问题比它看起来更重要，因为 Agent 开发特别容易制造「我明白了」的错觉——看着别人写好的循环，每一步都合理，合上书却写不出来。

下面这份清单可以用来自查。每一项都对应一种可以被观察的行为，而不是一种感觉：

• 能预判一段循环会跑几轮。 给定脚本，你心里已经知道假模型会被调用几次、最后停在哪。
• 能解释循环为什么停。 面对「它怎么不继续了」，你答得出是停止条件命中，还是撞上了步数上限。
• 知道什么时候不该用多 Agent。 能判断某个需求用一个循环就够，还是真的需要分工。
• 能读懂报错并决定怎么改。 看到一个工具调用失败，你知道是参数问题、校验问题，还是该重试。
• 能为一次运行算清成本。 面对「这轮花了多少」，你能从用量记录里算出来，而不是靠猜。
• 能写确定性测试。 你能用假模型断言一条轨迹，而不是靠肉眼观察输出。

反过来，下面这些信号说明你可能还停在「读过」的阶段：一遇到报错就换一个提示词试试；能看懂书里的例子但自己写不出来；分不清「能跑通」和「结果可靠」的区别；写完循环之后才回头补错误处理和测试。

如果你发现自己中了几条，不必沮丧。Agent 工程的能力本来就是靠「写—错—改」的循环长出来的，回到对应章节，把示例亲手敲一遍，往往比再读一遍有效。

勘误与反馈

技术书难免有疏漏，尤其是涉及模型与库版本演进的细节。如果你在阅读中发现示例无法运行、表述有歧义，或者某个知识点讲得不够清楚，欢迎在站点相应页面留言指出。对于确认的问题，我会在后续修订中更新正文，并在页面的更新说明里标注。

需要说明的是，本书面向的是「长期有效的判断力」，而不是「某个月份的 API 清单」。模型在迭代，库版本在变，具体的模型 ID、参数名、默认行为都可能过时；但消息协议、工具调用闭环、循环停止条件、上下文预算这些内容，保质期要长得多。如果某一天你发现书里的某个供应商适配器已经变了，但其中的设计仍然有用，那这本书就达到了它想要的效果。

现在，让我们从第 1 章开始。先回答那个最朴素的问题：一个 Agent，最小能小到什么程度。