跳到正文
AI Agent 教程 · 卷 0 · 学习地图

第一个 Agent:从 20 行到能干活

本合集目录
本章目录

单册说明:本文件是「AI Agent 完整教程」卷 0 的第 5 章,可独立阅读。 前置:必须做完第 3、4 章(实验目录已建、三个环境变量已配、hello_model.py 能跑)。这一章的代码全部在 ai-agent-lab/code 里。

项 内容
所属卷 卷 0 · 学习地图(第 5 / 6 章)
前置章节 第 3 章(环境)+ 第 4 章(三条链路)
本章产出 一个能列目录、读文件、写报告、会收手、写前会问你的 Agent
对应代码 code/first_agent.py(零依赖,约 200 行)
配图 图 0-4(Agent 循环)、图 0-9(上下文膨胀)、图 0-10(四出口 + 人工闸门)
读完的判定 --mock 能完整跑完并解释每一步;能改任务描述让它做你自己的事

5.1 一次问答与一个 Agent 的全部区别

先看区别,再写代码。

Agent 的执行循环

一次问答的流程是:你说 → 它答 → 结束。

Agent 的流程是:你说 → 它想 → 它动手 → 它看结果 → 它再想 → …… → 它说完了。

关键在那个回环:工具的执行结果会被塞回对话里,模型据此决定下一步。这个环,就是 Agent 的心脏。

而这个环必须有出口,否则它就是个烧钱机器。四个出口缺一不可:

五道闸门:四个出口 + 一个人工确认点

出口 判断依据 没有它会怎样
① 达成目标 模型说"做完了" ——
② 超过步数上限 例如最多 8 步 陷入死循环,一直调同一个工具
③ 超过预算 token 或金额上限 一夜之间烧掉几十块
④ 连续无进展 同样的动作重复出现 反复读同一个文件,永远不前进

还有第五个隐形出口:遇到危险动作(写文件、删文件、付款、对外发消息)时停下来问人。这个出口在下面代码里是开着的。


5.2 最小 Agent 的三件套

一个能干活的最小 Agent,只需要三样东西:

组成 是什么 在我们的代码里
模型 会思考、会决定调用什么 call_model()
工具 能真的动手机器的东西 TOOLS 定义 + run_tool()
循环 把"想 → 做 → 看"串起来,并有出口 for step in range(max_steps)

去掉任何一个,它就不是 Agent:去掉工具 → 变成聊天;去掉循环 → 变成一次函数调用;去掉模型 → 变成固定脚本。


5.3 先说安全:为什么只给三个受限工具

在写代码之前,先定一条规矩:给 Agent 的每一个能力,都要假设它会被用错。

下面是我在真实环境里做的越界测试(代码在 safe_path()):

模型可能给出的路径 结果
../../Windows/System32/x.txt 拒绝:路径越界
C:/Windows/x.txt 拒绝:路径越界
inbox/../output/ok.md 允许(解析后确实在 lab 内)
../../evil.md(写操作) 拒绝:写操作基准是 output/,越界即拒

这段逻辑只有三行,但它是整个脚本最重要的一段:

def safe_path(rel: str, base: Path) -> Path:
    p = (base / rel).resolve()
    if not p.is_relative_to(base):
        raise PermissionError(f"路径越界,已拒绝:{rel}")
    return p

为什么不用"检测有没有 .."这种办法:因为路径可以绕过(符号链接、绝对路径、编码变形)。先解析成真实绝对路径,再判断它是否在允许范围内,才是可靠的。

所以本卷给的三个工具是刻意选的:

工具 能力 限制 为什么这么设计
list_files 列目录 只读,最多 80 项 让它"先看再动手",而不是猜
read_text 读文件 只读,最多 4000 字符 防止一次把整个上下文塞满
write_report 写文件 只能写 output/,且必须人工确认 唯一的写权限,风险最高的一个

没有给它的能力:删文件、执行 shell 命令、访问网络、发邮件。这些不是"以后再说",而是"等你理解了它们的风险再给"。卷 2 讲权限与安全时会展开。


5.4 完整实现

完整可运行文件:code/first_agent.py(约 200 行,其中真正的 Agent 逻辑不到 60 行,其余全是边界和错误处理——这个比例是刻意的)。

第一步:工具定义(告诉模型"你能做什么")

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "list_files",
            "description": "列出 lab 目录下某个子目录里的文件,返回文件名、大小。只读。",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "相对 lab 的目录路径,例如 inbox"},
                },
                "required": ["path"],
            },
        },
    },
    # read_text、write_report 结构相同,略
]

三个设计要点,卷 2 会展开,这里先记住:

  1. description 是写给模型看的,写得越清楚,它选错工具的概率越低;
  2. 参数用 JSON Schema 约束,required 里的字段它必须给;
  3. 工具名要动词开头、语义单一(read_text 而不是 file_ops)。

第二步:执行工具(真的动手)

def run_tool(name: str, args: dict, auto_yes: bool) -> str:
    try:
        if name == "list_files":
            return tool_list_files(args)
        if name == "read_text":
            return tool_read_text(args)
        if name == "write_report":
            return tool_write_report(args, auto_yes)
        return f"错误:没有名为 {name} 的工具。"
    except PermissionError as e:
        return f"已拒绝:{e}"
    except Exception as e:
        return f"工具执行异常:{type(e).__name__}: {e}"

注意最后两个 except:工具出错时,不要把异常抛出去让程序崩掉,而是把错误信息作为"工具结果"返回给模型。

这是 Agent 和普通程序最大的差别之一:模型能读懂错误信息并自我修正。 你告诉它"文件不存在,先用 list_files 看看",它下一步就真的会去看。

第三步:主循环(心脏)

messages = [
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": task},
]

for step in range(1, max_steps + 1):                 # 出口②:步数上限
    resp = model(messages, TOOLS, cfg)               # 1. 让模型想
    msg = resp["choices"][0]["message"]
    calls = msg.get("tool_calls") or []
    content = (msg.get("content") or "").strip()

    # 出口①:模型不再调用工具,给出结论
    if content and not calls:
        print(content)
        break
    if not calls:                                    # 既没内容也没调用 → 别空转
        break

    # 把模型这一步的决定记进对话
    messages.append({"role": "assistant", "content": msg.get("content"),
                     "tool_calls": calls})

    repeat_hit = False
    for c in calls:                                  # 2. 执行它要的每一个工具
        name = c["function"]["name"]
        targs = json.loads(c["function"]["arguments"] or "{}")

        sig = name + json.dumps(targs, sort_keys=True)
        if sig in seen_calls:                        # 出口④:同样动作重复 → 收手
            repeat_hit = True
            result = "你已经用同样的参数调用过这个工具,不要重复。请换思路或结束任务。"
        else:
            seen_calls.add(sig)
            result = run_tool(name, targs, args.yes)

        # 3. 把结果塞回对话 —— 这一行就是“回环”
        messages.append({"role": "tool", "tool_call_id": c.get("id", ""),
                         "content": result})

    if repeat_hit:
        break
    if used_tokens > budget:                         # 出口③:超预算
        break

就这些。 去掉打印、参数解析、错误处理,核心不到 20 行。


5.5 逐段拆解:四个必须理解的点

① messages 数组是整个 Agent 的状态

它里面有四种角色:

role 谁 作用
system 你(开发者) 定规矩:能做什么、不能做什么、怎么输出
user 用户 提需求
assistant 模型 它的回答,或者它要调用的工具
tool 你的程序 工具的执行结果,必须带 tool_call_id 对应是哪次调用

每转一圈,这个数组都会变长——这就是成本来源。第 8 步的时候,前 7 步的全部内容(包括工具返回的完整文件内容)都会被重新发一遍。

每一步都把前面全部重发一遍:上下文是怎么膨胀的

② tool_calls 是"意图",不是"执行"

模型返回的 tool_calls 只是一份申请:它说"我想调 read_text,参数是 {"path":"inbox/notes.md"}"。真正执行的是你的代码。 这个区别极其重要:

模型永远不能直接操作你的电脑。它能做的只有"请求",批准和执行权在你手里。

理解了这一点,你就明白了为什么"Agent 删了我的文件"这类新闻,本质是程序给了它不该给的权限,而不是模型有了自主意识。

③ 工具结果必须回填,否则它不知道发生了什么

messages.append({"role": "tool", ...}) 这一行是整个循环的关键。漏了它,模型会一直重复同一个调用——因为它以为工具还没执行。

④ 四个出口都要写,少一个都是隐患

对照 5.1 的表格:达成目标(第 1 个 break)、步数上限(for 的上界)、预算(if used_tokens > budget)、无进展(seen_calls + repeat_hit)。四个都写了,才敢让它自己跑。

为什么"无进展"要先拦一次再退出:代码里把重复动作的提示作为工具结果回给模型,让它有机会换思路;同一轮里发现重复才退出。这样既不冤枉它,也不会真的绕进去。


5.6 跑起来:三个任务,从演示到真跑

先跑不需要密钥的演示

cd ai-agent-lab/code
python first_agent.py "把 inbox 里的文件整理成一份清单,写到 output/inventory.md" --setup --mock --yes

--setup 会建好目录和两个演示文件,--mock 用一个假模型按剧本走完整个循环。实际输出:

已准备好演示数据:C:\Users\你\ai-agent-lab
  inbox
  inbox\data.csv
  inbox\notes.md
  output

==============================================================
任务:把 inbox 里的文件整理成一份清单,写到 output/inventory.md
工作目录:C:\Users\你\ai-agent-lab
模式:mock(假模型)
上限:8 步 · 20000 tokens
==============================================================

--- 第 1 步 ---
[工具] list_files {"path": "inbox"}
[结果] [文件] data.csv  29 字节
[文件] notes.md  95 字节

--- 第 2 步 ---
[工具] read_text {"path": "inbox/notes.md"}
[结果] # 会议记录
- 下周一交初稿
- 图表要改成 300dpi
- 参考文献补到 40 篇

--- 第 3 步 ---
[工具] write_report {"filename": "inventory.md", "content": "..."}

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Agent 想写文件:C:\Users\你\ai-agent-lab\output\inventory.md
内容长度:68 字符,前 200 字预览:
--------------------------------------------------------------
# 清单
- 由 first_agent.py 的 mock 模式生成
--------------------------------------------------------------
[结果] 已写入 ...\output\inventory.md(68 字符)。

--- 第 4 步 ---
[模型] mock 剧本已走完。上面每一步的工具调用与结果都是真实的,
       只有这段总结是我写死的;真跑的时候,这段由模型自己生成。

==============================================================
结束原因:模型判断任务已完成
累计消耗:720 tokens · 共 8 条消息在上下文里

这段输出你要看懂三件事:

  1. 每一步都有一个 [工具] 和一个 [结果] —— 这就是"动手 → 看结果";
  2. 第 3 步被拦下来问你确认 —— 这就是人工闸门;
  3. 最后一行"共 8 条消息在上下文里" —— 才 4 步,上下文已经有 8 条消息。这就是成本增长的方式。

再看它会拒绝

python first_agent.py "整理清单" --mock
# 不带 --yes 时,写文件前会要求确认;非交互环境下会直接拒绝

真跑

python first_agent.py "把 inbox 里的文件整理成一份清单,写到 output/inventory.md"

换三个你自己的任务

任务 它在验证什么
把 inbox 里的文件按类型分类,写一份说明 多工具协作
读 inbox/notes.md,把里面的待办事项提取成清单 读 + 结构化输出
看看 output 里有什么,如果没有报告就生成一份 条件判断 + 写权限

5.7 它一定会失败:四种典型崩法

这一节比前面所有代码都重要。 第一次跑真实模型,大概率不会一次成功。下面是必然遇到的四种情况:

崩法 现象 根本原因 怎么改
不调工具,直接编 它说"我已经帮你整理好了",但 output/ 里什么都没有 模型觉得"我能推理出来";或系统提示没强调"必须先看" 系统提示加硬规则:"需要了解文件时先调用工具,不要凭猜测回答"
参数给错 read_text 收到 {"file": "notes.md"},缺 path 工具描述的字段名不清晰 参数名用最直白的词;description 写清"相对 lab 的路径,例如 inbox/notes.md"
重复调用 反复读同一个文件,5 步都卡在这 它没意识到"上次结果已经在上下文里" 我们加了 seen_calls 拦截;同时给它提示:"同样的参数不要重复"
过早收手 只读了目录就说"完成了" 它把"了解情况"当成了"完成任务" 系统提示里写清完成标准:"任务完成的标准是 output/ 里出现了文件"

这四种崩法对应四种能力:约束(提示词)、描述(工具设计)、状态(循环)、验收(完成标准)。你未来 80% 的调试时间,都会花在这四件事上。

想自己复现一遍?把任务改成"读完 notes.md 直接写报告,不要列目录",然后观察它第一步做了什么——这就是第 3 种和第 4 种崩法的合体。


5.8 加一个人工确认点

代码里最关键的一段不是循环,是这个函数:

def tool_write_report(args: dict, auto_yes: bool) -> str:
    target = safe_path(args.get("filename", "report.md"), OUTPUT)   # 只能写 output/
    content = args.get("content", "")
    print(f"Agent 想写文件:{target}")
    print(content[:200])

    if not auto_yes:
        if not sys.stdin.isatty():          # 非交互环境(如定时任务)不能默默通过
            return "已拒绝:写文件需要人工确认。确认无误请加 --yes 重跑。"
        if input("确认写入?[y/N] ").strip().lower() not in ("y", "yes"):
            return "用户拒绝了这次写入。请换一种方式。"

    target.write_text(content, encoding="utf-8")
    return f"已写入 {target}"

三个设计意图:

  1. 确认发生在"写入前",而不是"写入后"——事后通知没有意义;
  2. 拒绝也要作为工具结果返回给模型,让它知道"被拒了,别硬来";
  3. 非交互环境默认拒绝——定时任务里没人看着,宁可不做,不能乱做。

这就是"Human-in-the-loop"最朴素的形态。卷 2 会讲它的完整版(审批流、中断恢复、超时兜底),但核心就是这三行判断。


5.9 本章验收

  • 应当会跑通 --mock 演示,并解释每一步发生了什么;
  • 应当会修改任务描述,让它完成一件你自己的小事(真实文件,不是演示数据);
  • 应当会说出四个终止条件分别在哪一行代码里;
  • 应当会说明为什么 write_report 必须人工确认,而 list_files 不需要;
  • 应当会制造一次失败(把任务改成"读完 notes.md 直接写报告,不要列目录"),观察它怎么应对。

自测题:

题 关键点
删掉 messages.append({"role": "tool", ...}) 会怎样? 模型以为工具没执行,反复重复同一调用
只写步数上限、不写预算上限,风险是什么? 步数虽封顶,但单步上下文可能已经很大;长任务仍可能超支
--yes 在什么场景下绝对不能加? 无人值守的定时任务,或写操作指向不熟悉的目录时
为什么工具错误要 return 而不是 raise? 错误信息要成为工具结果回填,模型才能自我修正

5.10 下一步

Agent 有了,去验收和选路径 → 第 6 章 收口:自检、分叉与下一卷

回看:第 4 章 三条链路打通 · 返回导读