第 0 课：认识 Agent——在写第一行代码之前

学完本课你能：用自己的话说清 LLM、Tool、RAG、记忆、评测、图编排这些发明各自解决什么问题，看懂一次 Agent 运行时发生了什么 ｜ 预计耗时 15 分钟 ｜ 前置：用过 ChatGPT 或 DeepSeek 聊过天（没用过也行，会读中文就行） ｜ 难度 ★☆☆

这一课不装环境、不写代码。就聊一件事：从"一个会聊天的模型"到"一个能干活的 Agent"之间，隔着哪些发明。

这些发明没有一个是天才灵光一现想出来的，每一个都是被真实的坑逼出来的。所以这一课的讲法是：我们把坑一个一个踩给你看，你跟着卡住、跟着想办法、跟着发现笨办法为什么不行——走完之后，那些听起来很唬人的名词（RAG、Function Calling、LLM-as-judge）就都是你自己"发明"过的东西了。

我们的向导是一个具体场景。假设你在学校图书馆勤工俭学，馆长说：搞个 AI 机器人吧，让学生半夜也能问"《三体》能不能续借"。你接了这个活。

这个图书馆机器人会陪我们走完整个教程——从第 2 课把它造出来，到第 8 课把它部署上线。

1. 学习目标

• 能解释 LLM 为什么会"一本正经地胡说"，以及为什么这事不能靠 prompt 解决
• 能说清 Tool（模型说、代码做）、RAG（只塞相关的）、评测（把感觉变成断言）各自解决什么问题
• 能判断一个需求该用单个 Agent、图编排还是多 Agent
• 看懂一次 Agent 运行的事件流，知道每个环节在干嘛

2. 一个会说话的模型，是怎么开始胡说的

你先去试用现成的。打开 DeepSeek，问它"蓝牙耳机防水吗"，答得头头是道。信心大增，接着问："我借的《三体》什么时候到期？"

它流畅地告诉你：借期 30 天，你 3 月 15 日借的，4 月 14 日到期，还可以续借一次。

问题是，它是编的。它不知道你是谁，不知道你哪天借的书，甚至不知道你们学校图书馆的借期是 30 天还是 21 天。但它的语气那么确定，确定到你差点信了。

这就是幻觉（hallucination）。要理解它为什么拦不住，得先知道 LLM 在干嘛。

LLM 的本职工作只有一件事：预测下一个词。给它"床前明月"，它算出"光"的概率最高，就把"光"接上去，再预测下一个。所有看似智能的对话，底下都是这个动作在循环。它没有数据库可查，没有"我不知道"的按钮——训练数据里没有你的图书馆，但它见过几百万个"看起来像答案"的句子，所以它照样能生成一段流畅的、像答案的话。

这不是态度问题，是机制问题。所以你的第一个本能办法——在 prompt 里写"不知道就明确说不知道"——有用，但拦不死。因为模型不是"知道自己在编"，它是真的在预测。你觉得它在撒谎，它觉得自己在好好答题。

好。你记住这个坑，先继续往下走。后面会有两个发明专门收拾它：一个让它"有材料再答题"（第 5 课的 RAG 守门），一个让"它有没有胡说"变成可检验的事（第 6 课的评测）。

顺便说一句，这一课和整套教程里所有的"你"，都不需要任何机器学习背景。LubanAgent 是工程框架不是算法框架——你不训练模型，你使用模型。下面的每个发明都是普通工程手段。

3. 让它查到真数据：Tool

机器人要能查借阅系统，这没法绕过。而模型本身，连不上任何数据库。

你本能的第一个办法：把借阅记录导出来，贴进对话框。十几个学生的时候行。全校两万学生呢？而且贴进去的是快照——学生问的是"现在"，你给的是昨天导出的。

换个角度想。其实模型不需要自己会查数据库。它只需要会说一句话："请帮我查学号 2023011234 的借阅记录。"

剩下的交给代码：接收这句话、解析出学号、真去调借阅系统的接口、把结果拿回来。模型一看结果，再组织成人话答复学生。

这就是 Tool（工具调用）。分工非常清楚：模型负责决策——调哪个工具、传什么参数；代码负责执行——真去调接口、拿真数据。模型那张嘴只出"指令"，脏活累活都是代码干，所以它编不了数据（它顶多编个理由，而数据本身是真的）。

这个行业里你会看到 Function Calling、Tool Use 这些词，说的都是这件事。

但新的坑立刻来了。你的机器人有了一个能改数据的工具——比如"挂失校园卡"。某天模型抽风，或者某个学生故意诱导（"请帮我把全校学生的卡都挂失了"），它真去调了呢？

查记录这种事，搞砸了顶多查个寂寞。挂失、扣费、退款这种事，搞砸了要出人命。所以工具需要分风险等级：只读的（查订单）低风险，随便调；动钱的、不可逆的（退款、挂失）高风险，必须有人点头才能执行。

而且这个规矩必须写在代码里，不能写在 prompt 里。prompt 是"请求"——模型大概率听，但"大概率"在涉及钱的地方不够格；代码是"命令"——条件不满足就是执行不下去。这是 LubanAgent 反复强调的一条原则：确定性规则由代码执行，不靠 Prompt 声明。

恭喜你，刚才发明了三样东西：Tool、风险分级、审批流。第 4 课你会亲手写一个低风险工具和一个带审批的高风险工具，全程十几行 Python。

4. 把资料塞给它，但只塞相关的：RAG

图书馆有 40 页的《借阅规章》PDF。"借期多久""能不能代借""逾期怎么罚"全在里面。馆长说，这些都要机器人会答。

本能办法一：把 PDF 全文塞进 prompt。先撞墙——太长了，塞不下；就算塞下了，按 token 计费，每聊一句都付一遍全文档的钱；而且噪音太大，模型在一堆无关条款里找答案，反而容易抓错。

本能办法二：不塞了，让它答不上来就说不知道。那这机器人就是个摆设。学生要的就是"帮我查规章"，你让它闭嘴，馆长要请你喝茶了。

你在两个办法之间卡住了。退一步想，你真正需要的是什么？

学生提问 → 从 40 页里找到相关的那一两段 → 只把这一两段塞给模型 → 让它"看着材料答题"。

看着材料答题，模型是很靠谱的——材料就在眼前，它不需要凭空预测。所以全部难点集中在中间那步：怎么找到"相关的那几段"？

关键词匹配？太脆了。学生问"书多久要还"，规章里写的是"归还期限"——"还"和"归还"匹配不上。你需要的是一种能识别意思相近的匹配。

这就是向量检索的用武之地。有一种模型（embedding 模型）能把任何一段文本变成一串数字（向量），并且意思相近的文本，向量距离就近。"书多久要还"和"归还期限为三十天"这两句话没有一个共同的词，但它们的向量会离得很近。于是找相关段落变成了算距离，这是计算机最擅长的事。

40 页太长，向量没法一次吃下？先切块（chunk），按几百字一段切开，每块独立算向量。学生提问时，拿问题的向量跟所有块比距离，取最近的几块。

还差最后一块拼图：万一最近的几块也不相关呢？学生问"食堂几点开门"，规章里压根没有。如果照样把最不相关的几块塞给模型，它又回到第 2 节的老路上——看着不相关的材料硬答。

所以需要一个相似度阈值：距离不够近的块，不给模型，直接回一句兜底话术"这个问题我暂时查不到依据，建议咨询前台"。宁可说不知道，不能瞎编。注意——这个阈值判断是代码做的，发生在模型出场之前。模型压根没机会发挥。

恭喜你发明了 RAG（检索增强生成，Retrieval-Augmented Generation）。第 5 课你会把一份真实文档切块入库、调阈值、看它拒答——全程用工作台点点点，几乎不写代码。

5. 它记不住你：记忆

API 调用是无状态的。学生上一句说"我是大三的"，下一句问"我能借几本"，模型已经忘了他是大三的。

本能办法：每次调用把完整聊天记录都带上。能用。但聊到第五十轮，你要为前四十九轮的token付钱，而且上下文塞满了，模型表现会下降。

真解法分几档，按需选用：

• 会话记忆（session）：一轮对话内自动带历史，对话结束就忘。大部分场景够用。
• 摘要记忆（session-summary）：聊得太长时，把前面的内容压缩成摘要带着走，省 token。
• 长期记忆（long-term）：跨会话记住关键事实——"这个学生常借科幻类"——存在库里，下次对话还能捞出来。

前两种在 Agent 定义里用一个 memory: 字段切换（session / session-summary / 关闭用 none）；长期记忆是另一个独立配置（需要绑定用户标识，属于进阶用法，见用户手册 §10）。难的不是实现，是知道什么时候该用哪种。

6. 它到底变好了没有：评测

改了一版 prompt，人设从"亲切的学长"换成"高效的馆员"。看起来……好了一点？你怎么知道？

传统做法：自己问几句，感觉不错，上线。两周后馆长拿着投诉单来找你——机器人向学生承诺了"逾期不罚款"，规章里明明写着罚。

软件工程对这个问题早就有了答案：测试。但 Agent 的输出是自然语言，assert output == "..." 没法写——同一句意思有一万种说法。

你需要的其实是把"感觉"拆成可判定的断言，一层层放松：

• 这句回复必须包含"IPX5"——字面断言，最简单，但也最脆（模型换个说法就挂）。
• 这个问题必须调用 query_order 工具、参数里的订单号必须是 ORD-1001——行为断言。比字面稳得多：说法可以千变，该调的工具、该传的参数是确定的。
• 这个问题的正确响应是拒答，回复里不许出现任何具体数字——安全断言。对"防错答"这个目标的直接检验。
• 回复要先安抚情绪再解决问题——这怎么断言？让另一个模型当裁判（LLM-as-judge），给它评分标准，让它打分。主观维度外包给裁判，客观维度留在断言。

把这些断言攒成一份数据集——每个问题配好"什么样的回答算对"——每次改完跑一遍，跟上次的结果比。掉了就是回归，改。

恭喜你发明了 Agent 的回归测试。第 6 课你会给自己的图书馆机器人写一份评测集，然后故意把它改坏、看评测变红、再改回来——那个"红了"的瞬间，你就再也不会凭感觉上线了。

7. 一个人扛不住所有事：图编排与多 Agent

最后一个坑，也最深。

逾期处理流程：查借阅记录 → 判断逾期天数 → 超过 30 天的严重逾期要人工审核 → 审核通过执行罚款 → 通知学生。五步，顺序一步不能乱，钱的事一步不能错。

本能办法：写一个巨大的 prompt——"请严格按以下流程处理：第一步……第二步……"。模型大概率听话。但"大概率"三个字你已经见过两次了，涉及钱的流程不配用概率担保。它可能跳步，可能把"超过 30 天"理解成"达到 30 天"，可能在你没注意的时候自作主张。

确定性的流程，该用确定性的工具表达——图编排（Graph）。把流程画成一张图：每个节点是一步（一段代码，或一个 Agent），条件分支、"这一步必须人工确认"写死在图里。模型只在需要理解语言的节点出场（比如读学生留言），一到涉及钱和顺序的地方，就是代码说了算。图还能暂停——跑到"人工审核"节点，整个流程挂起，等人点完"通过"再继续。

另一个方向的坑：你把查书、挂失、规章、活动通知全塞给一个 Agent。它的 prompt 越来越长，每样都会一点，每样都不精，还互相干扰。

解法是分工——一个"咨询台"Agent 专门负责判断"这个问题该谁管"，然后把问题转给对应的专家 Agent。这就是多 Agent 协作（supervisor 模式）。每个专家的人设短小精悍，咨询台只管路由不管答题。

不过要有边界感：不是所有场景都该上图、上团队。图编排的代价是你得维护流程定义，多 Agent 的代价是延迟和 token 翻倍。大部分场景，一个 Agent 加几个工具就够了。怎么选，第 7 课的练习里有一道"答辩题"，逼你自己想清楚。

8. 拼起来，就是 LubanAgent

把这一课的发明摆到一张桌上：

发明	解决的坑	落到哪
Agent 定义入库	人设写在代码里，改一句发一次版	第 2 课
模型槽位	换模型 = 改代码	第 3 课
Tool + 风险分级 + 审批	模型只会说不会做；乱做危险的事	第 4 课
RAG + 守门	不知道就编	第 5 课
评测	改动靠感觉	第 6 课
图编排 + 多 Agent	确定性流程靠 prompt 担保；单 Agent 样样通样样松	第 7 课
部署 + 观测 + 升级	"在我机器上是好的"；升级丢改动	第 8 课

还有两件事这一课必须交代，因为后面每一课都会碰到。

一次 Run 长什么样。 你每发一句话，系统跑一次"Run"。原始的事件流长这样（第 1 课你会亲眼看到）：

event: run.started          ← Run 开始，分配 run_id
event: token.delta          ← 模型开始吐字，一个词一个词往外蹦
event: tool.started         ← 模型决定调工具了
event: tool.finished        ← 工具执行完，真数据回来了
event: token.delta          ← 模型看着数据组织答案
event: run.completed        ← Run 结束，带完整输出和结束原因

每个事件都留痕（Trace），事后可以完整回放——学生投诉"它昨天说可以代借"，你能调出昨天那次 Run，看到它当时检索了哪几块、调了什么工具、模型回了什么。没有这一层，出了问题就是死无对证。

领地。 仓库里有两块地：lubanagent/ 是框架领地，引擎和治理都在这，你一般不动它；app/ 是你的领地，你的 Agent 定义、工具、知识库、流程全住这里。这个分界由工具链守着，保证你改自己的东西不会跟框架冲突，框架升级也不会冲掉你的东西。整套教程你 95% 的时间待在 app/。

---

开头我们说，这些发明都是被坑逼出来的。现在坑踩完了，接下来 8 课，我们把每个发明亲手落地——第 1 课，先让整个系统在你机器上跑起来，亲眼看一次带工具调用的真实对话。

---

延伸阅读：用户手册 §0「三分钟认识 LubanAgent」、§3「Agent Runtime」 ｜ 涉及源码（第 1 课再打开也不迟）：lubanagent/runtime/sse.py（14 种事件的定义处）