Week 4 — Agents:当 LLM 学会用工具
Sign in
Week 4 — Agents:当 LLM 学会用工具
一个被锁住的大脑,一旦你给它装上「手」,就变成了真正能干活的工人。

Adventure 8

Adventure II — 故事进展到这里
我们讲到哪儿了
  • Week 1:LLM 是一个「下一个词预测器」
  • Week 2:它的内部 — tokens、attention、transformers
  • Week 3:用 sampling + 5 个 prompt 套路来控制它
  • Week 4(今天):给它装上 tools 之后会发生什么

Adventure 8

3 小时之后你会掌握
今天结束时,你能够:
1
解释局限
为什么一个「裸」LLM 什么都「做」不了 — 只能描述
2
看懂 tool 定义
看一份 JSON tool 定义,就能预测模型会怎么用它
3
追踪 agent loop
一步一步走完一个 agent loop
4
诊断失败
出问题时,判断 agent 落入了 4 种 failure mode 中的哪一种
5
看穿任何 AI 产品
问一句「它有哪些 tools?」 — 而且通常能猜对

Adventure 8

约定 — 3 条底线
1
先预测,再批准
在对任何 tool call 点「Allow」之前,先预测它会做什么
2
Tools 会失败,提前想好对策。
这节课有一半在讲「会出什么问题」
3
先在纸上设计,再写代码
在脑子里设计 agents,这才是真本事

Adventure 8

正式开始前
快速校准
三个问题热热脑子,不要查任何东西 — 就靠预测。
Question 1
ChatGPT 能删除你电脑上的文件吗?为什么能或者为什么不能?
Question 2
「chatbot」和「agent」有什么区别?
Question 3
如果你用过 Claude Code 或 Cursor — 它帮你改文件时,背后到底发生了什么?

Adventure 8

被锁住的大脑
想象你认识的最聪明的人。现在把他/她锁在一个屋子里,没有手机,没有网,没有书。
你问:「东京现在天气怎么样?」
他答不上来。不是因为他不聪明 — 而是因为回答这个问题需要 往屋子外面看.

Adventure 8

这就是「裸」LLM
一个裸 LLM(没接 tools)做不到:
  • 读你电脑上的文件
  • 运行代码
  • 查实时数据
  • 发消息
  • 做任何会影响「文本输出」之外世界的动作
它只能 描述 事物。ChatGPT 上线之后的三年里,大多数人脑子里的「AI」就是这个样子。

Adventure 8

Hallucination 长什么样
问一个裸 LLM: 「东京今天天气怎么样?」
有时候 — 诚实
「我没法访问实时数据。」
有时候 — 危险
「东京今天 18°C,多云。」
说得无比自信,完全是编的。
模型根本没办法知道。于是它就预测一个「听起来合理」的答案 应该 长什么样 — 然后把它输出出来。

Adventure 8

📘 Concept Card
Hallucination(在 agents 里)
是什么:模型生成了一个「看起来像真的、但其实是假的」值(一个日期、一个事实、一个 ID),因为它其实没有真实数据。
好比:一个新员工不敢承认自己不知道你的订单号 — 干脆自信地编了一个。
为什么重要:这是 agent 造成数据损坏的 #1 元凶。永远在执行前验证模型的输出。

✓ 重点:自信的输出 ≠ 正确的输出。除非你教它,否则模型不会主动告诉你它在猜。

Adventure 8

意外 — Tools 并没有改变模型
当你「给 LLM 装上一个 tool」时,什么变了?
❌ 没有变的是
  • 模型的权重
  • 它的训练数据
  • 它预测 tokens 的方式
✅ 真正变的是
  • 你随着 prompt 一起,发送了一份 tool 的 JSON 描述
  • 你在模型外面套了一层 runtime,专门盯着 tool calls
模型本身还是在干同一件事: 预测下一个 token。

Adventure 8

一个 tool 的解剖图
{ "name": "get_weather", "description": "Get the current weather in a given city.", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "City name, e.g. 'Tokyo'" } }, "required": ["city"] } }
一个名字、一段描述、一份参数 schema。 真正的函数活在你的代码里,不在模型里。

Adventure 8

Tool Call
模型不会真的运行任何东西。它只是 输出 一份结构化的请求:
{ "tool": "get_weather", "args": { "city": "Tokyo" } }
然后你的代码会:
01
看到这份输出
Runtime 拦截这份结构化的 tool-call JSON
02
验证并执行
执行真正的 get_weather() 函数
03
把结果喂回去
把「18°C,多云」放回到对话 context 里
04
模型继续推理
带着 context 里的新信息继续往下想

Adventure 8

📘 Concept Card
Tool
是什么:一份函数描述(名字 + 参数 + docstring),模型可以请求调用它。
好比:员工手册里的一条。「这是 get_weather — 需要时就调用。」模型决定 什么时候调用,你的代码决定 实际发生什么.
为什么重要:Tools 永远不在模型内部,它们是模型外面的插件式模块。

✓ 重点:tool 只是一份描述,runtime 才是让它真正生效的东西。

Adventure 8

Knowledge Check 1
翻牌之前先预测
模型输出:
{"tool": "delete_file", "args": {"path": "/etc/passwd"}}
Question 1
接下来会发生什么?讨论之前先预测。
Question 2
文件会自动被删除吗?
Question 3
runtime 有机会说「不」吗?

在跟任何人讨论之前,先把你的答案写下来。你的第一直觉就是数据。

Adventure 8

Agent Loop
messages = [system_prompt, user_question] while True: response = model.generate( messages, tools=available_tools) if response.is_tool_call: result = execute_tool( response.tool_name, response.args) messages.append(response) messages.append(result) continue else: return response.text
就这么简单。每一个「AI agent」都是建在这个循环之上。

Adventure 8

走一遍一次迭代
用户问: 「在 Downloads 文件夹里找到提到『rocket』的那个文件。」
1
Step 1
模型输出:「我先列一下这个文件夹。」→ 发出 list_files(directory="Downloads")
2
Step 2
Runtime 执行 → 返回 47 个文件名
3
Step 3
模型看到文件列表 → 发出 read_file(name="essay1.txt")。检查里面有没有「rocket」→ 没有 → 试下一个文件
4
Step 4+
…循环继续,直到模型找到关键词
5
最终输出
「找到了,在 space_essay.txt"

Adventure 8

为什么这件事这么强
模型 根据上一步的结果决定下一步做什么。
读 + 决定
读文件、找规律、决定下一步做什么
浏览 + 跟进
浏览网页、跟着链接走、总结找到的内容
运行 + 修复
运行代码、看到错误、修复它们
任何需要迭代的事
任何你会雇一个谨慎的初级工程师来做的事
一个裸 LLM 这些事一件都做不了。这个 loop 改变了一切。

Adventure 8

📘 Concept Card
Agent Loop
是什么:一个 while 循环,让模型调用 tools、看到结果、决定下一步。
好比:一个人在做调研。你查一个来源,它给你一条线索,你再查下一个 — 不可能一开始就把每一步都规划好。
为什么重要:这个循环是 chatbot 和「真正能干活的工人」之间唯一的差别。agent 世界里的一切都建立在它之上。

✓ 重点:Chatbot = 回一句。Agent = 循环到搞定为止。

Adventure 8

Agent vs Chain

Chain
Agent
步骤
预先定义好
边走边决定
顺序
固定
动态
举例
翻译 → 总结 → 发邮件
「搞清楚用户想要什么,然后用一切办法把它做到」
最适合
可重复的流程
开放式任务
如果某一步失败
Chain 直接断掉
Agent 会试点别的办法
Chains 更容易 debug,agents 更灵活。真实系统大多数是两者混用。

Adventure 8

Claude Code 的 tool 列表
你现在就在用 Claude Code。这是它真实的 tool 列表(简化版):
Read
读一个文件
Write
写一个文件
Edit
在一个文件里查找并替换
Glob
找匹配某个 pattern 的文件(*.py)
Grep
在文件内容里搜索文本
Bash
运行 shell 命令
WebFetch
抓取一个 URL
WebSearch
搜索网页
Task
派生一个 sub-agent
每一个都只是一份 JSON tool 描述。

Adventure 8

看 Claude Code 干活
你问: 「修一下 app.py 里的 bug」
1
1. 读 context
模型读你的消息 + tool 列表 + system prompt
2
2. 先看一眼
决定:得先看代码 → Read(file_path="app.py")
3
3. 改代码
看到代码 + bug → 决定要改哪里 → Edit(old_string=..., new_string=...)
4
4. 验证
可能跑个 Bash("python app.py") — 如果报错,就修一下再试
5
5. 汇报
模型判断自己干完了 → 用一段纯文本回复你

Adventure 8

为什么 Claude Code 的 system prompt 这么长
光有 tools 不够。System prompt 教会模型:
哪个 tool 干哪种活
Glob 找文件名,Grep 找内容 — 不可互换
怎么串 tools
改之前先读,改之后再验证。永远不要跳步骤。
什么事不能做
别 rm -rf,未经允许不要 commit
怎么处理错误
读真正的错误信息,不要猜
怎么跟你说话
简洁、展示 diff、做破坏性动作前先问

Adventure 8

Agent 的判断力住在 system prompt 里
弱 system prompt + 同样的 tools = 一个差很多的 agent。
「Tools 给 agent 能力。
System prompt 给它人格。」
只有 tools
  • 原始能力,没有方向
  • 什么事都用 Bash 解决
  • 完全没有谨慎感
  • 删东西之前不会问你
Tools + 强 system prompt
  • 每件事挑对的 tool
  • 知道什么时候要停下来验证
  • 行为稳定,你能信得过
  • 做任何不可逆的事之前都会问

Adventure 8

没经过你允许,Claude Code 不会做的事
哪怕拥有 Bash tool 权限,Claude Code 也会:
✅ 随便读
读文件、搜代码这些事不问你
⚠️ 改之前会问
把改动写进你文件之前会确认一遍(在 approval 模式下)
⚠️ 跑 shell 之前会问
在跑会影响你系统的 shell 命令之前会问
❌ 硬性边界
不会 rm -rf、force-push,或者跳过 pre-commit hooks,除非你明确说可以

这不是模型「聪明」 — 这是 system prompt 在画边界。

Adventure 8

Knowledge Check 2
设计一个 Agent
你要给这个任务造一个 agent: 「帮我策划朋友的生日 party。」
Question 1
它需要哪 3–4 个 tools?给每个起名字,并说明它是干什么的。
Question 2
它的 system prompt 应该写什么?写 3–4 条关键指示。
Question 3
如果你完全不写 system prompt,可能会出什么问题?

先自己预测答案 — 再跟身边的人讨论。

Adventure 8

Agents 失败的 4 种方式
Agents 很强,但也很脆。有 4 种 failure mode 会反复出现:
1
Context 溢出
Agent「忘掉」了早期的指令
2
没处理 tool 错误
在坏结果上卡住或者开始 hallucinate
3
选错了 tool
用了一条最绕远的路解决问题
4
编出来的参数
凭空编 IDs、URLs 或者它根本没有的文件名
认识症状 = debug 速度快很多。

Adventure 8

Failure 1 — Context 溢出
每一轮都在往对话里加东西:
  • system prompt + 用户消息 + 5 个 tool calls + 5 个结果 + …加起来非常快
  • 一旦超出模型的 context window(比如 200k tokens),老消息就会被丢掉或者被总结掉
症状
Agent「忘」了你 10 分钟前说过的话。自相矛盾。要你给它已经给过的信息。
修法
在老对话从 window 里掉出去之前把它们总结一下。能用小 context 就用小的。让 tool 结果保持简洁。

跑得久的 agents 特别容易中招。从一开始就要为它做准备。

Adventure 8

Failure 2 — 没处理 tool 错误
Tools 会失败。文件不存在。API 返回 500。用户取消。
如果模型拿到一个看不懂的错误,而 system prompt 又没教它怎么办:
悄无声息地搞坏数据
装作错误没发生,继续往下走 — 写入坏数据
无限循环
一直重试,因为它从来没学会「退一步」
Hallucination
凭空编出结果「应该」长什么样 — 直接造假数据

修法:在 runtime 里抓住错误,把它格式化得清清楚楚,然后在 system prompt 里教会模型「优雅地退一步」。

Adventure 8

Failure 3 — 选错了 tool
模型看到 Bash, Read,还有 WebFetch.
它用了 Bash("curl https://...") 而不是 WebFetch。两个都能用 — 但 Bash 更慢、更贵、更难做 sandbox。
症状
  • Agent 用最绕远的方式干活
  • 拿大锤敲小钉子
  • 事后更难审计它到底干了什么
修法
  • 更好的 tool 描述(说清每个 tool 什么时候用)
  • 在 system prompt 里举例,演示首选的 tool
  • 有时候:干脆把多余的那个 tool 删掉

Adventure 8

Failure 4 — 编出来的参数
模型发出:
delete_user(id="usr_123")
但 usr_123 并不存在。这个 ID 是它编的。
症状
悄无声息的数据损坏。「这条记录是从哪儿冒出来的?」假数据出现,真数据消失。
修法
要求模型先用真正的 tools 拿真实的 IDs(list_users),再把它们传给会执行动作的 tools。

把模型的输出当成 不可信输入 — 在执行任何破坏性动作之前先验证。

Adventure 8

Hands-On A
读 Claude Code 的心
打开 Claude Code。给它一个不简单的任务(比如 「把所有 foo.py 改名成 bar.py 在这个文件夹里」)).
在批准每个 tool call 之前,先停一下,预测一下:
  • 它下一步会用哪个 tool?
  • 用什么参数?
  • 结果会告诉它什么?

预测准确率达到 80% → 你就真正理解了 agent loop。记一下你的得分。

Adventure 8

Hands-On B
认出 failure mode
故意给 Claude Code 一个有问题的任务:
  • 让它读一个不存在的文件
  • 让它跑一条注定失败的命令
  • 给一条自相矛盾的指令
观察并记录:
它能恢复吗?
优雅地恢复,还是磕磕绊绊?
它会循环吗?
拿同一个坏的 call 一直重试?
它会 hallucinate 吗?
不承认错误,直接编一个结果?
现在你已经亲眼见过每一种 failure mode 了。

Adventure 8

Hands-On C
在纸上设计一个 Agent
挑一件你平时手动做的事。比如: 「发一条关于今天天气的 tweet,但只在天气有意思的时候发(下雨、下雪、特别热或特别冷)。」
设计 — 不写代码:
01
列出 tools
它需要什么?(get_weather, post_tweet, get_current_city?)
02
写 system prompt
它怎么判断什么算「有意思」?
03
写启动的 user prompt
用户要发什么来启动这个 agent?
04
梳理 failure modes
可能出什么问题?每一种怎么处理?

如果你能在纸上把它设计清楚,你对 agents 的理解就超过了 95% 在用它们的人。

Adventure 8

现场练习
看 Claude Code 干一件真活
挑一件至少需要 3 次 tool calls 的事。跑起来,每一步都停一下。
对每一个 tool call,全班一起预测 下一个 call 是什么,然后再点 Allow。
Round 1
老师跑任务,全班一起预测。
Round 2
一个学生跑自己的任务,其他人预测。
复盘
哪里出乎意料?差点出现哪种 failure mode?
这是培养 agent 直觉最好的一个练习,没有之一。

Adventure 8

讨论 — 你最喜欢的 AI 应用
它有哪些 tools?
ChatGPT + Code Interpreter
有哪些 tools?想想看它真正能 做 什么,而不是只能描述什么。
Cursor
有哪些 tools?跟 Claude Code 的列表有什么不同?
Notion AI
有哪些 tools?它能碰到的东西有哪些边界?
Perplexity
有哪些 tools?让它跑起来的核心循环是什么?

一旦你看出「每个 AI 产品都只是 system prompt + tools + loop」,整个行业的图景就一下子清晰了。

Adventure 8

3 小时总结
现在你理解了:
✅ 被锁住的大脑
裸 LLM 被锁在自己脑袋里 — 能描述,但做不了
✅ Tools 只是 JSON
不是魔法 — 真正执行它们的是模型外面的 runtime
✅ Agent loop 一共 8 行
一个 while 循环,让模型调用 tools 并决定下一步
✅ Claude Code 就是这玩意
看得见的 tools + 一个带判断力的 system prompt
✅ 4 种 failure modes
context 溢出、没处理的错误、选错 tool、编出来的参数 — 你能一眼认出每一种

Adventure 8

Glossary
Tool
一份函数描述(名字 + 参数 + 文档),模型可以请求调用它
Tool call
结构化输出,模型说「请用参数 Y 跑一下 tool X」
Agent loop
一个 while 循环,让模型调用 tools 并决定下一步
Agent
LLM + tools + 把它们串起来的循环
Chain
预先定义好的 LLM/tool 步骤序列;比 agent 灵活度低
Context window
模型一次能看到的最大 token 数(system + 历史 + 新内容)
Hallucination
模型不承认自己没有,直接编一个值(ID、URL、文件名)

Adventure 8

这周的任务 + Week 5 预告
这周
  • 在 3 个真任务上读 Claude Code 的心 — 记下你预测错的地方,那就是你的学习点。
  • 在纸上设计一个 agent。下周准备好分享。
下周 — Frameworks & MCP
每家 AI 公司都从零开始造了一遍同样的 agent loop。同样的「read file」tool,同样的「search web」tool,只是每家都略有不同。
Anthropic 发布了一个标准,叫 MCP — Model Context Protocol。一份协议,让每个 agent 都能用上每个 tool。就像 AI 世界的 USB。
我们会一起学 4 大主流框架,并把一个新的 MCP server 插进 Claude Code。

Adventure 8