从「会聊天」到「会做事」
这一阶段只做一件事:给模型配上工具,并让它按「思考 → 调用 → 观察 → 判断」的循环把事情做完。左边目录、右边知识点,每章都有可在本机运行的示例、小结表和章末小测,不要求联网,也不要求 API 密钥。
按 6 个模块、L1~L5 难度自己测一遍,10 题一组即答即批,适合学完几章之后查漏补缺。 链接:https://myimage.cn/agent-mechanism/
全部章节
第 1 章 从「会聊天」到「会做事」
1.1 Agent 到底多了什么
上一阶段的模型只能输出文字。你说「帮我查一下北京天气」,它可能编一个温度给你。Agent(智能体)多出来的东西是:给它工具,并允许它一轮一轮地用工具,直到把事情做完。
| 普通对话 | Agent | |
|---|---|---|
| 能输出 | 文字 | 文字 + 调用工具的动作 |
| 遇到不会的 | 靠猜 | 去查、去算、去调接口 |
| 一轮不够 | 结束 | 看结果,再决定下一步 |
| 风险 | 编造 | 可能误调工具,需要权限控制 |
所以最简洁的公式是:Agent = 模型(大脑)+ 工具(手脚)+ 循环(节奏)。三者缺一不可。只给工具不循环,那叫「一次函数调用」;只循环不给工具,那只是让它自言自语。
给小白的提醒:不要被「自主规划」「数字员工」这类词唬住。入门阶段你只需要理解一个 while 循环里发生了什么。
1.2 一个生活化的例子
任务:「帮我算一下这三笔开销一共多少,顺便按金额从大到小排好」。
- 模型想:我需要先拿到三笔数字,再求和、再排序。
- 模型决定用工具:调用
calculator,参数是这三笔数字。 - 你的程序执行工具:真正算出结果,把「合计 328,排序 ...」返回。
- 模型看结果:够了,可以回答了 → 输出最终答案。
关键在第 3 步:模型只「决定要调用什么」,真正执行的是你的代码。这一点想通了,后面所有安全设计都顺理成章。
1.3 入门前必须知道的三条边界
- 模型没有超能力:它只能从你给的工具列表里选,没给的工具它「用不了」,只能编。
- 结果要回喂:工具跑完的结果必须放回消息列表,模型才看得见(回忆上一阶段的 messages)。
- 必须能停下:循环要有最大步数、超时和失败出口,否则可能一直转下去烧钱。
1.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| Agent 公式 | 模型 + 工具 + 循环 |
| 谁执行工具 | 你的代码,不是模型 |
| 工具从哪来 | 你预先声明的列表,没给就用不了 |
| 结果怎么被看到 | 以 tool 角色放回 messages |
| 第一条安全线 | 最大步数 + 超时 + 失败出口 |
第 2 章 工具调用:把「手脚」交给模型
2.1 先声明,再使用
你要先给模型一份工具说明书:名字、干什么用、需要哪些参数、参数什么类型。模型看懂后,才会在需要时输出「我要调用它」。
import json
# ① 工具说明书:模型靠它判断"什么时候该用什么工具"
tools = [
{
"name": "add", # 工具名,模型调用时用它
"description": "把两个数字相加,返回它们的和", # 描述写清用途,别含糊
"parameters": { # 参数结构,用 JSON Schema 描述
"type": "object",
"properties": {
"a": {"type": "number", "description": "第一个数"},
"b": {"type": "number", "description": "第二个数"}
},
"required": ["a", "b"] # 哪些参数必须给
}
}
]
# ② 打印出来看一眼:这就是你会发给模型的"工具清单"
print(json.dumps(tools, ensure_ascii=False, indent=2))
print("工具数量:", len(tools))
# 输出:
# [
# {
# "name": "add",
# "description": "把两个数字相加,返回它们的和",
# "parameters": {
# "type": "object",
# "properties": {
# "a": {
# "type": "number",
# "description": "第一个数"
# },
# "b": {
# "type": "number",
# "description": "第二个数"
# }
# },
# "required": [
# "a",
# "b"
# ]
# }
# }
# ]
# 工具数量: 1这段只是把「工具说明书」打印出来。description 是写给模型看的自然语言,决定它「什么时候该用」;parameters 是给程序用的参数规格,决定「怎么调用才合法」。两者缺一不可。
这段可以直接在本机运行。真实项目里,这份 JSON 会随请求一起发给模型。
description 写清楚比参数多更重要。模型靠描述判断「什么时候该用它」;描述含糊,它就会该用不用、不该用乱用。
2.2 完整一轮:决定 → 执行 → 回喂(本机可运行)
下面用纯 Python 模拟一整轮工具调用,不需要联网、不需要密钥,可以直接跑:
import json
# ① 你的工具实现:真正干活的代码写在这里(这里同时也是白名单)
REGISTRY = {
"add": lambda a, b: a + b,
}
def run_tool(name, args):
"""执行模型指定的工具,返回统一格式的结果"""
if name not in REGISTRY: # 白名单:没登记的一律拒绝
return {"error": "未授权的工具:" + name}
try:
return {"result": REGISTRY[name](**args)}
except Exception as e: # 工具报错也不能让整个程序崩掉
return {"error": "执行失败:" + str(e)}
# ② 假设模型返回了"想调用什么"(真实场景里,这段是 API 的返回值)
model_output = '{"tool": "add", "args": {"a": 12, "b": 30}}'
call = json.loads(model_output)
# ③ 你的代码执行,并把结果以 tool 角色放回消息列表
result = run_tool(call["tool"], call["args"])
messages = [
{"role": "user", "content": "12 加 30 等于多少?"},
{"role": "assistant", "content": model_output},
{"role": "tool", "content": json.dumps(result, ensure_ascii=False)},
]
print(json.dumps(messages, ensure_ascii=False, indent=2))
print("未授权调用:", run_tool("delete_all", {}))
# 输出:
# [
# {
# "role": "user",
# "content": "12 加 30 等于多少?"
# },
# {
# "role": "assistant",
# "content": "{\"tool\": \"add\", \"args\": {\"a\": 12, \"b\": 30}}"
# },
# {
# "role": "tool",
# "content": "{\"result\": 42}"
# }
# ]
# 未授权调用: {'error': '未授权的工具:delete_all'}小白提示:注意消息列表里出现了三种
role:user提问 →assistant决定调用工具 →tool把执行结果回喂。「把结果放回对话里再问一次」就是 Agent 循环最核心的那个动作。最后一行演示了白名单:模型想调delete_all,代码直接拒绝,根本不执行。
注意最后一行:模型若「想」调用一个没登记的工具,你的代码直接拒绝。权限边界必须由代码守住,不能指望模型自觉。
这一轮里,三个角色齐了:user 提问、assistant 说要调用、tool 把结果送回去。下一章的循环,就是把这一轮重复若干次。
2.3 参数校验不能省
模型给出的参数可能缺字段、类型不对、甚至夹带危险字符。执行前一律校验:名字在白名单里、必填参数齐全、类型正确、数值在合理范围。
- 路径类参数:禁止越出允许目录。
- 金额 / 数量类:设上限。
- 删除 / 发送类:必须人工确认或干脆不开放。
把上一阶段学的「结构化输出 + 代码校验」搬过来即可 —— 工具调用参数本质上就是一次结构化输出。
2.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 工具说明书 | 名字 / 描述 / 参数结构,描述要写清用途 |
| 模型输出的是 | 调用意图(工具名 + 参数),不是执行结果 |
| 执行者 | 你的代码,且必须走白名单 |
| 结果回喂 | 以 tool 角色放回 messages |
| 参数校验 | 必填、类型、范围、路径边界,一个都不能省 |
第 3 章 循环:Agent 的「心跳」
3.1 一轮里发生四件事
常见的 ReAct 思路,把每一轮拆成 思考 → 行动 → 观察 → 再判断:模型先说打算做什么,选一个工具;你的代码执行;把结果回喂;模型看结果决定「继续」还是「可以回答了」。
- Thought(思考):现在缺什么信息?下一步做什么?
- Action(行动):选工具、给参数。
- Observation(观察):工具返回的结果。
- 判断:信息够了就输出最终答案,不够就回到第 1 步。
和上一章的区别只有一句:把一整轮放进 while 循环里,并让模型自己决定何时停。
3.2 一个能跑的最小循环骨架(纯 Python)
下面用「假模型」模拟,重点看循环结构和三条出口,可直接运行:
MAX_STEPS = 5 # 出口①:最大步数
def fake_model(step, history):
"""假装是模型:前两步要工具,第三步给出最终答案"""
if step < 2:
return {"type": "tool", "name": "add", "args": {"a": step + 1, "b": 10}}
return {"type": "final", "text": "信息够了,合计完成"}
def execute(name, args):
return {"result": args["a"] + args["b"]} # 出口②:执行异常在此捕获(略)
history = []
for step in range(MAX_STEPS): # 循环 = Agent 的心跳
decision = fake_model(step, history) # ① 思考:模型这一步想干什么
if decision["type"] == "final": # 出口③:模型自己说「可以收工」
print("最终答案:", decision["text"])
break
obs = execute(decision["name"], decision["args"]) # ② 行动:执行工具
history.append({"action": decision["name"], "observation": obs})
print("第", step + 1, "轮观察:", obs) # ③ 观察:结果回喂
else:
print("达到最大步数,强制收工并告知用户未完成任务")
print("共执行", len(history), "次工具调用")
# 输出:
# 第 1 轮观察: {'result': 11}
# 第 2 轮观察: {'result': 12}
# 最终答案: 信息够了,合计完成
# 共执行 2 次工具调用fake_model 是个「假模型」:用几个 if 假装模型做了决定,所以整段不需要联网、不需要 API Key、也不需要花钱。重点看 for 循环里的四步(观察 → 决定 → 执行 → 回喂),以及 MAX_STEPS 这个必须存在的出口——没有它,模型一旦反复调工具就永远停不下来。
三条出口缺一不可:模型说停、步数用尽、执行异常。真实项目还要加超时和费用上限。
为什么要有
for...else:循环被break正常结束时不进 else;只有步数耗尽才进,正好用来兜底提示「任务未完成」。
3.3 三个最常见的循环故障
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 反复调同一个工具 | 观察结果没回喂,或回喂后模型没「看见」 | 检查 tool 消息是否真的进了 messages |
| 永远不收工 | 没有终止条件 / 参数每次都一样 | 加最大步数、检测重复调用 |
| 费用突然暴涨 | 循环 + 长历史 + 没上限 | 设步数上限、超时、总 token 预算 |
排错时先把每一轮的 messages 打印出来看。八成的问题都是「结果没回喂」或「历史没带上」。
3.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 一轮四步 | 思考 → 行动 → 观察 → 判断 |
| 循环的本质 | 把一轮放进 while,由模型决定何时停 |
| 三条出口 | 模型说停 / 步数用尽 / 执行异常 |
| 必备上限 | 最大步数、超时、总费用预算 |
| 排错第一招 | 打印每一轮的 messages |
第 4 章 拆解任务:别指望一口吃成胖子
4.1 什么时候需要规划
简单任务(「算个和」)不需要规划,一轮就完。只有多步骤、有依赖、结果不确定时才需要拆,比如「找出上月发票里金额最大的三张,汇总成表」。
| 任务特征 | 处理方式 |
|---|---|
| 一步能完成 | 直接调工具,别加复杂度 |
| 多步但顺序固定 | 写成固定的流水线,比让模型自由发挥更稳 |
| 步骤之间有依赖、可能失败 | 先让模型列计划,再逐步执行 |
| 步骤可并行 | 分开跑再汇总,注意顺序不影响结果 |
新手最常见的过度设计:一上来就写「自主规划多智能体」。能写死流程的地方写死,稳定性高得多、也便宜得多。
4.2 把计划写成可检查的结构
让模型输出「计划」时,同样要结构化:每一步有编号、动作、是否完成。这样你的代码能追踪进度,而不是面对一段散文。
plan = [
{"id": 1, "todo": "取出发票列表", "done": False},
{"id": 2, "todo": "按金额降序排序", "done": False},
{"id": 3, "todo": "取前三张并汇总成表", "done": False},
]
def mark_done(plan, step_id):
"""按 id 把某一步标记为已完成(结构化计划的好处:随时能查进度)"""
for p in plan:
if p["id"] == step_id:
p["done"] = True
return plan
mark_done(plan, 1)
mark_done(plan, 2)
print([(p["id"], p["done"]) for p in plan])
print("剩余步骤:", [p["todo"] for p in plan if not p["done"]])
# 输出:
# [(1, True), (2, True), (3, False)]
# 剩余步骤: ['取前三张并汇总成表']把计划写成数据,而不是一段自然语言,好处是随时能检查:done 为 False 的还剩几条、卡在第几步一目了然。输出里前两步已完成、第三步没完成,于是「剩余步骤」只列了它。
有了这个结构,你就能做到「失败时从第 N 步重试」,而不是整个任务重来。
这就是「有框架、有步骤」的具体含义:把模糊的目标变成可逐项打勾的清单。
4.3 失败与重试的节奏
- 第 1 步:工具报错 → 把错误信息原样回喂给模型,让它换参数或换工具。
- 第 2 步:同一失败出现 2 次 → 停止重试,避免烧钱。
- 第 3 步:仍无法完成 → 明确告诉用户「卡在哪一步、缺什么」,而不是编一个结果。
「诚实地失败」比「假装成功」重要得多。Agent 最容易伤人的地方,就是悄悄把失败包装成一份看起来正常的答案。
4.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 何时规划 | 多步、有依赖、可能失败时才需要 |
| 能写死就写死 | 固定流水线比自由规划更稳更省 |
| 计划结构化 | 编号 + 动作 + done,便于追踪与续跑 |
| 重试上限 | 同一失败 2 次即停 |
| 失败姿态 | 说清卡在哪,绝不假装成功 |
第 5 章 记忆、日志与安全边界
5.1 Agent 的「记忆」到底是什么
还是那句话:模型本身没有记忆。所谓记忆,全是你替它保管并每次塞回 messages 的东西。
| 类型 | 放什么 | 注意 |
|---|---|---|
| 短期(本次会话) | 最近几轮消息与工具结果 | 最容易撑爆上下文窗口 |
| 长期(跨会话) | 用户偏好、已确认的事实 | 存数据库,按需检索,不要全量塞回 |
| 任务状态 | 计划清单、已完成步骤 | 结构化保存,便于断点续跑 |
长会话常用做法是把旧轮次压成摘要,但硬约束(格式、禁止事项)不要参与压缩,单独留在 system 里每轮重申。
5.2 日志:没有它就没法排错
Agent 出问题时,光看最终答案等于瞎猜。至少记下每一轮的:步数、模型决定、工具名与参数、返回结果、耗时、token 用量。
import json
trace = [] # 每一轮记一条,方便事后排查
def log(step, decision, result, cost_ms):
"""把一轮的决定、参数、结果、耗时都记下来"""
trace.append({
"step": step, "tool": decision.get("name"),
"args": decision.get("args"), "result": result,
"cost_ms": cost_ms,
})
log(1, {"name": "add", "args": {"a": 1, "b": 2}}, {"result": 3}, 12)
log(2, {"name": "add", "args": {"a": 3, "b": 4}}, {"result": 7}, 9)
print(json.dumps(trace, ensure_ascii=False, indent=1))
print("总耗时(ms):", sum(x["cost_ms"] for x in trace))
# 输出:
# [
# {
# "step": 1,
# "tool": "add",
# "args": {
# "a": 1,
# "b": 2
# },
# "result": {
# "result": 3
# },
# "cost_ms": 12
# },
# {
# "step": 2,
# "tool": "add",
# "args": {
# "a": 3,
# "b": 4
# },
# "result": {
# "result": 7
# },
# "cost_ms": 9
# }
# ]
# 总耗时(ms): 21小白提示:
trace里每一轮都记了step / tool / args / result / cost_ms。出问题时先翻日志,比盯着模型输出猜快得多:你能看到它第几步选错了工具、传了什么参数、哪一步特别慢。
这份 trace 就是最朴素的「可观测性」。有了它,反复调用、参数异常、耗时飙升都能一眼看到。
5.3 四条安全底线
- 最小权限:只开放完成任务必需的工具;删除、转账、发邮件一律人工确认。
- 不信任外部文本:网页、邮件、用户上传的文件里可能夹带指令(提示注入),材料永远只当数据。
- 硬上限:最大步数、超时、总 token 预算、单次调用金额上限。
- 可回滚 / 可审计:危险动作先记日志、可撤销;保留完整 trace 便于复盘。
记住一句话:模型给的是「建议」,你的代码才是「决策者」。任何有副作用的动作,决定权都不能交给模型。
5.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 记忆的真相 | 全是你保管并塞回 messages 的内容 |
| 长期记忆 | 存库按需检索,别全量回喂 |
| 压缩原则 | 旧轮次可摘要,硬约束单独保留 |
| 可观测性 | 逐轮 trace:决定 / 参数 / 结果 / 耗时 / token |
| 安全四线 | 最小权限、不信外部文本、硬上限、可回滚可审计 |
第 6 章 小结:学完能做出什么
6.1 一个可以动手的最小项目
把这一阶段串起来,做一个「本地票据小助手」:给它两个工具 read_list(读一份本地清单)和 sum_values(求和),让它按循环完成「读取 → 汇总 → 排序 → 回答」。
- 第 1 步:用第 2 章的格式声明两个工具,白名单只允许这两个。
- 第 2 步:用第 3 章的循环骨架,设 MAX_STEPS=5、失败上限 2 次。
- 第 3 步:把每轮 trace 打到控制台,先跑通「不联网、假模型」的版本。
- 第 4 步:确认流程稳定后,再把 fake_model 换成真实 API 调用。
- 第 5 步:补上参数校验、超时与费用上限,再考虑加新工具。
顺序很重要:先用假模型把循环、回喂、终止、日志跑通,再接真 API。否则一个 bug 会同时来自三层,极难定位。
6.2 能力自检表
| 自检项 | 做到了吗 |
|---|---|
| 能说清 Agent = 模型 + 工具 + 循环 | □ |
| 知道模型只输出调用意图、执行在你的代码 | □ |
| 会写工具说明书并做参数白名单校验 | □ |
| 能写出带三条出口的循环骨架 | □ |
| 知道结果要以 tool 角色回喂 | □ |
| 会把任务拆成可打勾的结构化计划 | □ |
| 知道最小权限、硬上限、trace 日志四条底线 | □ |
6.3 下一站:为什么需要 RAG
现在你的 Agent 会「做事」了,但它依然只知道你塞给它的东西。你问「公司报销制度里出差住宿上限多少」,它既没读过制度文件,也不能凭空知道 —— 只会编。
下一阶段做两件事:先把你的资料切成小块、检索出相关片段喂给模型(RAG);再学多个角色如何分工协作(多智能体)。到那时,「会聊天 + 会做事 + 有资料」才算齐了。
6.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 最小项目 | 本地票据小助手:读取 → 汇总 → 排序 → 回答 |
| 实现顺序 | 先假模型跑通循环,再接真 API |
| 必配防线 | 白名单、参数校验、步数/超时/预算、trace |
| 本阶段闭环 | 声明工具 → 循环回喂 → 拆解计划 → 安全收口 |
| 下一站 | RAG 让模型用上你自己的资料 |