这一卷要解决什么
本合集目录
本章目录
单册说明:本文件是「AI Agent 完整教程」卷 0 的第 1 章,可独立阅读。 前置:无。这一章不装环境、不写代码,只回答"我要花时间读什么"。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 0 · 学习地图(第 1 / 6 章) |
| 前置章节 | 无 |
| 本章产出 | 一份属于你自己的阅读路线选择 |
| 对应代码 | 无 |
| 配图 | 图 0-12(三条阅读线) |
| 读完的判定 | 能说出自己走哪条线、为什么走这条线 |
1.1 一句话定位
这一卷不教你 Agent 的原理,只保证三件事:看得懂、装得上、跑得起来。
这三件事听起来不起眼,但它是绝大多数人卡住的地方。我见过太多人:收藏了二十篇"Agent 保姆级教程",装了五个客户端,却始终没有一个能真正替他干活的 Agent。卡点几乎从不在原理,而在这三件事:
- 看不懂:名词太多(Agent、MCP、RAG、Harness、上下文工程),每个都懂一点,拼不成一张图,于是不知道该先学哪个;
- 装不上:跟着教程装到一半报错,不知道错在哪一层,于是放弃;
- 跑不起来:跑通了"你好",但不知道自己下一步能拿它干什么,于是回到对话框。
所以本卷的顺序是:先给地图 → 再装环境 → 再跑一个真的 Agent → 最后选路径。
1.2 你是哪一类读者
三类人的读法完全不同。先对号入座,再看 1.5 的阅读线。
| 画像 | 典型情况 | 本卷对你最关键的部分 |
|---|---|---|
| A. 非程序员 | 科研人员、研究生、文科背景;会装软件,不会写代码;想让 Agent 帮自己处理文献、表格、文件 | 第 2 章(地图)+ 第 4 章(三条链路)+ 第 5.6 节(跑起来看效果)。第 5 章的代码不用全懂,能跑就行 |
| B. 会写代码 | 会 Python 基础,想真做出东西;厌倦了只会调 API | 全卷都读,重点在 5.5 节(把循环拆开看)+ 6.4(路径 B) |
| C. 要带人 | 要给学生/团队做培训,或者自己要写教程 | 全卷精读,特别注意 2.6 的误解、5.7 的失败模式、6.3 的"假跑通"——这些是别人一定会问到的 |
怎么判断自己是哪一类:问自己一句话——"我想让 Agent 替我做的那件事,需要它读写文件吗?"
- 需要,但我不会写代码 → A
- 需要,我也想自己写 → B
- 我主要是想搞清楚这东西值不值得推给别人 → C
1.3 本卷管什么、不管什么
| 本卷解决 | 本卷不解决(在哪一卷) |
|---|---|
| Agent 到底是什么、和聊天机器人差在哪 | 模型的训练与推理原理(卷 1) |
| 一个 Agent 系统由哪几层组成,卡住时该查哪层 | 提示词工程的具体技巧(卷 1) |
| 环境怎么装、三条链路怎么打通、报错怎么查 | 各个客户端与框架的详细用法(卷 3) |
| 一个能动手、会收手、需要你点头的最小 Agent | 多智能体、记忆系统、RAG 的完整实现(卷 2 / 卷 4) |
| 你该走哪条路径、下一卷读什么 | 评测、成本、安全、部署(卷 6) |
为什么要把边界划这么清:入口卷最怕的是"什么都想讲一点"。讲浅了没用,讲深了劝退。本卷的原则是——凡是后面会专门讲的,这里只讲到"能继续往下走"的程度,并明确告诉你它属于哪一层。
1.4 卷内结构
| 章 | 标题 | 它给你的东西 | 对应产出 |
|---|---|---|---|
| 1 | 这一卷要解决什么 | 范围、读者、读法、验收标准 | 一份自己的路径选择 |
| 2 | 全景地图:七层模型 | 一张能用来"定位故障"的图 | 知道自己卡在第几层 |
| 3 | 环境准备(一) | 系统、账户、终端、密钥、目录、代理 | 一个干净的实验目录 |
| 4 | 环境准备(二) | 网页 / 客户端 / API 三条链路 | 三条链路全通 |
| 5 | 第一个 Agent | 一个 200 行、能跑、有安全边界、有终止条件的 Agent | 一个能干活的东西 |
| 6 | 收口 | 验收清单、自测题、路径分叉、速查卡 | 下一步的方向 |
章与章之间的依赖是线性的:第 2 章不装环境也能读,但第 4 章必须做完第 3 章,第 5 章必须做完第 4 章。不要跳——跳过第 4 章直接跑第 5 章的代码,报错信息会让你以为是代码问题,其实是环境问题。
1.5 三条阅读线
同一个卷,三种读法,按你的目的选。

| 阅读线 | 适合 | 做法 | 读完能做什么 |
|---|---|---|---|
| 快线(只求能用) | 画像 A,只想尽快让 Agent 帮自己干活 | 读 2.1–2.2 → 做第 3 章 → 做第 4 章的链路①② → 跑 5.4 的完整版 | 有一个能用的客户端 + 知道它为什么能用 |
| 标准线(推荐) | 所有画像 | 1 → 2 → 3 → 4 → 5 → 6 顺序读完,代码全部跑一遍 | 环境、认知、动手三样都有 |
| 深线(要带人) | 画像 C | 标准线 + 每章的"为什么这么设计"部分 + 自己做一遍 5.7 的失败实验 | 能给别人讲清楚,也能预判别人会卡在哪 |
快线不是"偷懒版":它的设计逻辑是——如果你只需要一个能用的客户端,第 3 章装完、第 4 章链路② 验完就够了,第 5 章的手写 Agent 对你属于"知道有这回事"即可。但只要你有"让它每天自动跑"的念头,就必须补上第 4 章链路③ 和第 5 章,因为自动化只能靠 API。
1.6 前置条件与设备
必要:
- 一台能上网的电脑,Windows 10/11 或 macOS 12 以上(Linux 也可以,命令略有差异);
- 8GB 内存以上(走云端 API 路线,这个配置足够);
- 一个可用的模型服务账号(第 3.3 节列了怎么选)。
可选但建议:
- 16GB 内存 + 独立显卡 8GB 以上 → 可以走"本地跑模型"路线,数据不出机器;
- Git(保存你的代码版本);
- Node.js 20+(部分客户端和工具需要)。
不需要:不需要服务器、不需要域名、不需要会 Docker、不需要先学机器学习。
1.7 本卷的四个产出物
- 一个干净的环境:
ai-agent-lab目录、可用的 Python、配好的密钥、能连上的网络; - 三条打通的链路:网页能用、客户端能动手、API 能编程;
- 一个 Agent:
first_agent.py,能列目录、读文件、写报告,会自己收手,写文件前会问你; - 一份路径判断:看完第 6 章,你知道自己下一卷该读哪个,不该读哪个。
每一样都能拿出证据判定(见导读里的"四个产出物"图),不是"我感觉我会了"。
1.8 本章验收(也是全卷的验收口径)
全部按"应当会使用"来判定,不看花了多久、看了几遍:
- 应当会说清 Agent 与聊天机器人的区别,并能举一个自己的例子;
- 应当会定位一个故障发生在七层中的哪一层;
- 应当会独立完成环境安装,并解释每个环境变量是干什么的;
- 应当会用三条链路各完成一次任务,并在出错时说出该查哪里;
- 应当会运行并修改第一个 Agent 的任务描述,让它完成一件你自己的小事。
五条里能做到第 4、5 条,本卷就算通过。第 1–3 条是支撑,做不到的话,后面会反复回来补。
判断标准为什么用"会不会用"而不是"学没学完":这套教程是给要带人的人准备的(画像 C)。带人的时候你不能问"你读完了吗",只能问"你能做出来吗"。所以从第一章起,验收口径就统一成可观察的行为。
1.9 下一步
- 想先建立框架 → 第 2 章 全景地图:七层模型
- 想直接动手装环境 → 第 3 章 环境准备(一)
- 想先看看整卷有什么 → 返回导读