文档首页
阶段 03 · Agent 核心机制 在线知识文档
学习路线 第 4 / 6 步 · 模块 ⑤⑥Agent 概念 / Function Calling← 上一站 ③④ 大模型与 Prompt下一站 ⑦ RAG 检索增强 →完整顺序:① Python → ② FastAPI → ③④ Prompt → ⑤⑥ Agent → ⑦ RAG → ⑧⑨ 框架与 MCP → ⑩ 多 Agent(回看)→ ⑪~⑭ 编写中 · 查看学习路线图 →

从「会聊天」到「会做事」

这一阶段只做一件事:给模型配上工具,并让它按「思考 → 调用 → 观察 → 判断」的循环把事情做完。左边目录、右边知识点,每章都有可在本机运行的示例、小结表和章末小测,不要求联网,也不要求 API 密钥。

去做在线自测 → AI Agents 学习路线 →
6个章节
24个小节
30道章末小测
测
配套推荐
Agent 核心机制在线自测 - 我的图片

按 6 个模块、L1~L5 难度自己测一遍,10 题一组即答即批,适合学完几章之后查漏补缺。 链接:https://myimage.cn/agent-mechanism/

打开在线自测 →

全部章节

第 01 章

第 1 章 从「会聊天」到「会做事」

1.1 Agent 到底多了什么

上一阶段的模型只能输出文字。你说「帮我查一下北京天气」,它可能编一个温度给你。Agent(智能体)多出来的东西是:给它工具,并允许它一轮一轮地用工具,直到把事情做完。

普通对话Agent
能输出文字文字 + 调用工具的动作
遇到不会的靠猜去查、去算、去调接口
一轮不够结束看结果,再决定下一步
风险编造可能误调工具,需要权限控制

所以最简洁的公式是:Agent = 模型(大脑)+ 工具(手脚)+ 循环(节奏)。三者缺一不可。只给工具不循环,那叫「一次函数调用」;只循环不给工具,那只是让它自言自语。

给小白的提醒:不要被「自主规划」「数字员工」这类词唬住。入门阶段你只需要理解一个 while 循环里发生了什么。

1.2 一个生活化的例子

任务:「帮我算一下这三笔开销一共多少,顺便按金额从大到小排好」。

  1. 模型想:我需要先拿到三笔数字,再求和、再排序。
  2. 模型决定用工具:调用 calculator,参数是这三笔数字。
  3. 你的程序执行工具:真正算出结果,把「合计 328,排序 ...」返回。
  4. 模型看结果:够了,可以回答了 → 输出最终答案。

关键在第 3 步:模型只「决定要调用什么」,真正执行的是你的代码。这一点想通了,后面所有安全设计都顺理成章。

1.3 入门前必须知道的三条边界

  • 模型没有超能力:它只能从你给的工具列表里选,没给的工具它「用不了」,只能编。
  • 结果要回喂:工具跑完的结果必须放回消息列表,模型才看得见(回忆上一阶段的 messages)。
  • 必须能停下:循环要有最大步数、超时和失败出口,否则可能一直转下去烧钱。

1.4 【本章小结】

你学到了什么关键记忆点
Agent 公式模型 + 工具 + 循环
谁执行工具你的代码,不是模型
工具从哪来你预先声明的列表,没给就用不了
结果怎么被看到以 tool 角色放回 messages
第一条安全线最大步数 + 超时 + 失败出口
第 02 章

第 2 章 工具调用:把「手脚」交给模型

2.1 先声明,再使用

你要先给模型一份工具说明书:名字、干什么用、需要哪些参数、参数什么类型。模型看懂后,才会在需要时输出「我要调用它」。

PYTHON
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 模拟一整轮工具调用,不需要联网、不需要密钥,可以直接跑:

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
参数校验必填、类型、范围、路径边界,一个都不能省
第 03 章

第 3 章 循环:Agent 的「心跳」

3.1 一轮里发生四件事

常见的 ReAct 思路,把每一轮拆成 思考 → 行动 → 观察 → 再判断:模型先说打算做什么,选一个工具;你的代码执行;把结果回喂;模型看结果决定「继续」还是「可以回答了」。

  1. Thought(思考):现在缺什么信息?下一步做什么?
  2. Action(行动):选工具、给参数。
  3. Observation(观察):工具返回的结果。
  4. 判断:信息够了就输出最终答案,不够就回到第 1 步。

和上一章的区别只有一句:把一整轮放进 while 循环里,并让模型自己决定何时停。

3.2 一个能跑的最小循环骨架(纯 Python)

下面用「假模型」模拟,重点看循环结构和三条出口,可直接运行:

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
第 04 章

第 4 章 拆解任务:别指望一口吃成胖子

4.1 什么时候需要规划

简单任务(「算个和」)不需要规划,一轮就完。只有多步骤、有依赖、结果不确定时才需要拆,比如「找出上月发票里金额最大的三张,汇总成表」。

任务特征处理方式
一步能完成直接调工具,别加复杂度
多步但顺序固定写成固定的流水线,比让模型自由发挥更稳
步骤之间有依赖、可能失败先让模型列计划,再逐步执行
步骤可并行分开跑再汇总,注意顺序不影响结果

新手最常见的过度设计:一上来就写「自主规划多智能体」。能写死流程的地方写死,稳定性高得多、也便宜得多。

4.2 把计划写成可检查的结构

让模型输出「计划」时,同样要结构化:每一步有编号、动作、是否完成。这样你的代码能追踪进度,而不是面对一段散文。

PYTHON
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. 第 1 步:工具报错 → 把错误信息原样回喂给模型,让它换参数或换工具。
  2. 第 2 步:同一失败出现 2 次 → 停止重试,避免烧钱。
  3. 第 3 步:仍无法完成 → 明确告诉用户「卡在哪一步、缺什么」,而不是编一个结果。

「诚实地失败」比「假装成功」重要得多。Agent 最容易伤人的地方,就是悄悄把失败包装成一份看起来正常的答案。

4.4 【本章小结】

你学到了什么关键记忆点
何时规划多步、有依赖、可能失败时才需要
能写死就写死固定流水线比自由规划更稳更省
计划结构化编号 + 动作 + done,便于追踪与续跑
重试上限同一失败 2 次即停
失败姿态说清卡在哪,绝不假装成功
第 05 章

第 5 章 记忆、日志与安全边界

5.1 Agent 的「记忆」到底是什么

还是那句话:模型本身没有记忆。所谓记忆,全是你替它保管并每次塞回 messages 的东西。

类型放什么注意
短期(本次会话)最近几轮消息与工具结果最容易撑爆上下文窗口
长期(跨会话)用户偏好、已确认的事实存数据库,按需检索,不要全量塞回
任务状态计划清单、已完成步骤结构化保存,便于断点续跑

长会话常用做法是把旧轮次压成摘要,但硬约束(格式、禁止事项)不要参与压缩,单独留在 system 里每轮重申。

5.2 日志:没有它就没法排错

Agent 出问题时,光看最终答案等于瞎猜。至少记下每一轮的:步数、模型决定、工具名与参数、返回结果、耗时、token 用量。

PYTHON
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 四条安全底线

  1. 最小权限:只开放完成任务必需的工具;删除、转账、发邮件一律人工确认。
  2. 不信任外部文本:网页、邮件、用户上传的文件里可能夹带指令(提示注入),材料永远只当数据。
  3. 硬上限:最大步数、超时、总 token 预算、单次调用金额上限。
  4. 可回滚 / 可审计:危险动作先记日志、可撤销;保留完整 trace 便于复盘。

记住一句话:模型给的是「建议」,你的代码才是「决策者」。任何有副作用的动作,决定权都不能交给模型。

5.4 【本章小结】

你学到了什么关键记忆点
记忆的真相全是你保管并塞回 messages 的内容
长期记忆存库按需检索,别全量回喂
压缩原则旧轮次可摘要,硬约束单独保留
可观测性逐轮 trace:决定 / 参数 / 结果 / 耗时 / token
安全四线最小权限、不信外部文本、硬上限、可回滚可审计
第 06 章

第 6 章 小结:学完能做出什么

6.1 一个可以动手的最小项目

把这一阶段串起来,做一个「本地票据小助手」:给它两个工具 read_list(读一份本地清单)和 sum_values(求和),让它按循环完成「读取 → 汇总 → 排序 → 回答」。

  1. 第 1 步:用第 2 章的格式声明两个工具,白名单只允许这两个。
  2. 第 2 步:用第 3 章的循环骨架,设 MAX_STEPS=5、失败上限 2 次。
  3. 第 3 步:把每轮 trace 打到控制台,先跑通「不联网、假模型」的版本。
  4. 第 4 步:确认流程稳定后,再把 fake_model 换成真实 API 调用。
  5. 第 5 步:补上参数校验、超时与费用上限,再考虑加新工具。

顺序很重要:先用假模型把循环、回喂、终止、日志跑通,再接真 API。否则一个 bug 会同时来自三层,极难定位。

6.2 能力自检表

自检项做到了吗
能说清 Agent = 模型 + 工具 + 循环□
知道模型只输出调用意图、执行在你的代码□
会写工具说明书并做参数白名单校验□
能写出带三条出口的循环骨架□
知道结果要以 tool 角色回喂□
会把任务拆成可打勾的结构化计划□
知道最小权限、硬上限、trace 日志四条底线□

6.3 下一站:为什么需要 RAG

现在你的 Agent 会「做事」了,但它依然只知道你塞给它的东西。你问「公司报销制度里出差住宿上限多少」,它既没读过制度文件,也不能凭空知道 —— 只会编。

下一阶段做两件事:先把你的资料切成小块、检索出相关片段喂给模型(RAG);再学多个角色如何分工协作(多智能体)。到那时,「会聊天 + 会做事 + 有资料」才算齐了。

6.4 【本章小结】

你学到了什么关键记忆点
最小项目本地票据小助手:读取 → 汇总 → 排序 → 回答
实现顺序先假模型跑通循环,再接真 API
必配防线白名单、参数校验、步数/超时/预算、trace
本阶段闭环声明工具 → 循环回喂 → 拆解计划 → 安全收口
下一站RAG 让模型用上你自己的资料