本章目标:说明这本教程要解决什么问题、适合谁读、按什么顺序读, 以及如何亲手运行配套的 mini-agent 代码,把原理变成可执行的代码。
1. 为什么写这本教程
大语言模型(LLM)解锁了一个此前没有的编程范式:用自然语言描述目标,让程序自主完成。 过去三年,「AI Agent(智能体)」从研究概念演变为生产现实------代码助手自动改 bug, 客服机器人自主查单退单,交易代理自主研究并执行策略。但 Agent 也是被误解最多的概念: 有人把它当成「套个提示词的聊天机器人」,有人把它当成「什么都能自动完成的魔法」, 也有人把 RAG、MCP、Workflow 全部混进「Agent」这一个筐里。
这本教程的目标有两个,且缺一不可:
- 读懂原理:把 Agent 的核心机制讲透------它为什么「能做事」、循环里发生了什么、 工具与记忆如何改变它的能力边界、多智能体与 MCP 解决了什么问题。
- 亲手实现 :配套一个自包含、可运行、零依赖的 mini-agent, 用 TypeScript 把「循环、工具、记忆、规划、多智能体、MCP」这六大组件 从零写一遍,并用 54 个测试用例和 6 个演示程序验证它真的能跑。
一句话概括:「原理 + 代码」双线并行。 看懂 Agent 不是靠背框架 API, 而是能自己把核心机制重新造一遍。这与《重构》《代码大全》的写作精神一致------ 写那些「五年后仍然成立」的知识。
2. 你将学到什么
读完这本教程,你应该能回答以下问题:
- 概念:AI Agent 的严格定义是什么?和 LLM 应用 / Workflow / RAG 的边界在哪里? 为什么 2023 年之后 Agent 突然成为主流?(第 01 章)
- 原理:「感知-思考-行动-观察」循环如何工作?ReAct 为什么有效? 规划与反思如何提升成功率?(第 02 章)
- 工具:大模型接口的核心概念(token / 流式 / 结构化输出 / function calling)是什么? 一个「好的工具定义」长什么样?参数校验为什么是安全底线?(第 03 章)
- 记忆:短期记忆与长期记忆的区别?向量检索 + 嵌入如何实现「记住」? 上下文窗口不够时怎么办?(第 04 章)
- 上下文工程:怎么把「该进的上下文」以最低成本、最优顺序呈现给模型? 预算分配、Prompt Caching、动态工具子集、压缩与系统提示?(第 05 章)
- 框架:LangGraph / CrewAI / AutoGen / OpenAI Agents SDK / Claude Agent SDK 各适合什么? 为什么没有「一个框架赢下所有」?(第 06 章)
- 实现:如何用几十个文件、零依赖写一个工程化的 Agent? 每行代码在解决什么问题?(第 07 章 + mini-agent/)
- 多智能体:为什么需要多个 Agent?编排者-工作者 / 辩论 / 市场等拓扑如何取舍? A2A 协议是什么?(第 08 章)
- MCP:为什么「工具的协议化」是 2024-2026 年最重要的事? 客户端与服务端如何通信?(第 09 章 + mini-agent 的 MCP 客户端)
- 评测与安全:怎么知道 Agent「变好了」?提示注入如何防?OWASP LLM Top 10 是什么?(第 10/11 章)
- 部署:Agent 上生产要考虑哪些工程问题?可观测性、可靠性、成本、人机协作?(第 12 章)
- 未来:2026 年的 Agent 生态长什么样?下一步往哪走?(第 13 章)
- 提示词工程:怎么把「人类想让它做的事」翻译成「模型能稳定执行的指令」? Few-shot / CoT / 提示模式目录 / Agent 场景的提示词设计?(第 20 章附录 G)
- 向量检索与 RAG:近似最近邻(IVF/HNSW/PQ)、混合检索、重排序、 完整 RAG 管线怎么调优?(第 21 章附录 H)
- 反模式:50 条可命名的 Agent 反模式(症状→根因→修复→预防), 怎么给一个 Agent 系统做「体检」?(第 19 章)
3. 阅读前置要求
| 知识 | 要求 | 说明 |
|---|---|---|
| 大模型 / LLM 基础 | 必须 | 知道 chat completion、token、temperature 是什么 |
| TypeScript / JavaScript | 必须 | 能读懂类、泛型、async/await、import type |
| Node.js | 建议 | 会运行 node xx.ts;教程代码要求 Node ≥ 23.6 |
| Python | 可选 | 第 06 章框架对比会涉及 Python 生态,但不影响主线 |
| 提示词工程 | 建议 | 知道 system prompt / few-shot / CoT,第 02 章会用到; 想系统补齐就顺路读第 20 章附录 G |
如果你完全没接触过大模型 API,建议先花半天跑通一个 chat completion 示例再回来。 如果你会写代码但没学过「怎么把话跟模型说清楚」,第 20 章附录 G(提示词工程) 就是为你准备的------它是全书「默认你会」的地基之一。
4. 章节地图
ruby
00 前言与导读 ────────────────────────────── 现在这里
01 认识 AI Agent ──────「是什么」:定义 / 边界 / 分类
02 核心原理与架构 ─────「怎么转」:循环 / 规划 / 反思 / 模式
03 大模型接口与工具调用 ─「手脚」:API 契约 / function calling
04 记忆管理 ───────────「大脑」:短期 / 长期 / RAG
05 上下文工程 ─────────「装配」:预算 / 排序 / 缓存 / 压缩
06 主流框架 ───────────「生态」:九大框架全景对比
07 从零实现工程化 Agent ─「造轮子」:mini-agent 代码走读 ★
08 多智能体协作 ───────「团队」:拓扑 / 协议 / 编排
09 MCP ────────────────「协议」:工具互联的标准
10 Agent 评测 ─────────「度量」:怎么算「变好了」
11 Agent 安全 ─────────「防御」:威胁模型 / 护栏
12 生产部署 ───────────「落地」:可观测 / 可靠 / 成本
13 现状与未来 ─────────「远方」:2026 生态与趋势
14 附录 A 术语表
15 附录 B mini-agent 工程参考 ★
16 附录 C 端到端实战案例 ★
17 附录 D 常见问题与误区
18 附录 E 推荐阅读与资源
19 附录 F Agent 反模式目录 ★
20 附录 G 提示词工程
21 附录 H 向量检索与 RAG 工程深入
22 附录 I Agent 工程原则与决策速查 ★标注 ★ 的五章是「动手向」:07 走读代码,15 查 API 做练习,16 把全书串成一个完整项目, 19 把「系统行为怪异」的诊断变成一份可查的目录,22 把「该按什么标准做决定」变成一份 可查的原则速查。附录 G、H 是「地基补全」:G 补上全书默认你会却没系统讲的提示词工程, H 补上记忆与 RAG 背后的检索算法细节。附录 I 与附录 F(反模式)互为镜像------F 回答 「不要做什么」,I 回答「该做什么」,配起来构成完整的判断体系。
5. 如何运行配套代码
mini-agent 在 mini-agent/ 目录,零 npm 依赖,Node ≥ 23.6 直接跑 .ts:
bash
cd ai-agent-toturial/mini-agent
# 1. 类型检查(可选)
npx tsc --noEmit
# 2. 全部测试(54 个用例,约 0.4 秒)
node --test "tests/*.test.ts"
# 3. 六个演示
node examples/chat.ts # 工具调用 + 长期记忆 + 多轮上下文
node examples/math-agent.ts # 工具错误自愈
node examples/team.ts # 多智能体协作(编排者-工作者)
node examples/mcp-demo.ts # 通过 MCP 协议调用外部程序
node examples/eval-agent.ts # 评测 harness(数据集 + 结果/轨迹断言 + 报告)
node examples/eval-support.ts # 客服 Agent 评测(第 16 章附录 C):4 类用例 + 安全断言Windows 提示:node --test "tests/*.test.ts" 的引号是必须的(glob 由 Node 展开)。 macOS / Linux 同样支持。
零依赖的意义 :你不需要
npm install,不需要 API Key,不需要 GPU。 任何有 Node 的机器都能复现全部验证。这正是「工程化实现」对教学的价值------ 代码应该像数学定理一样可被任何人检验。
6. 如何阅读(三种读法)
读法一 · 循序渐进(推荐新手):按章节顺序读。01--05 建立概念与视野, 06 横向看框架,07 动手实现,08--13 深入专题,14--16 当手册随用随查; 被「提示词怎么写」卡住时插入 20 附录 G,被「向量检索为什么快/怎么选库」卡住时 插入 21 附录 H。
读法二 · 代码驱动(推荐工程师):先跑 mini-agent 的测试和 demo, 带着「它怎么做到的」再回头读 01--05 的原理,然后用 07 的走读逐行对照。
读法三 · 主题查阅(推荐实践者):遇到具体问题直接跳到对应章节------ 「想上 MCP」读 09;「要写评测」读 10;「要上线」读 12;「要规划 Agent 团队」读 08; 「要优化成本与响应质量」读 05;「想把提示词写到评测级」读 20 附录 G; 「要选向量库 / 调 RAG」读 21 附录 H;「被概念绕晕 / 想看常见坑」读 17 附录 D FAQ; 「遇到系统行为怪异 / 想给系统做体检」读 19 附录 F 反模式目录(症状→根因→修复); 「想该按什么标准做决定 / 在决策点上犹豫」读 22 附录 I 原则速查(与反模式互为镜像); 「想系统延伸阅读」读 18 附录 E 资源。
7. 写在前面的话
Agent 技术仍处于早期,今天的框架半年后就可能过时。因此这本教程刻意做了两件事:
- 把原理放在工具之前。循环、记忆、工具契约、评测方法这些不会随框架更替而失效;
- 用实现代替名词 。当你亲手写出一个 Agent 循环,你会立刻识别出 LangGraph 的
StateGraph、CrewAI 的Crew、OpenAI SDK 的Runner不过是同一种思想的封装。
学会造轮子,不是为了不用轮子,而是为了看懂轮子、选对轮子、以及 在轮子不够用时自己造。这就是写一本「能读很多年」的教程的意义。
现在,我们从第 01 章开始,回答第一个问题:到底什么是 AI Agent?