第 00 章 · 先修 · 最小 Agent Loop

Agent 到底是怎么干活的

剥开所有产品外壳，任何 Agent 程序都是同一个东西：一个让模型在「想 → 做 → 记」里循环的调度系统。本章用六个步骤、四个角色、一个真实任务，把这个最小骨架拆给你看。

① 一句话定义想 · 做 · 记

→

② 四角色类比大脑 · 手 · 小本子 · 代理

→

③ 六步骤 Agent 的最小结构

→

④ 五轮预演真实开源任务

→

⑤ 真实轨迹 58 次调用 · 1 次修改

按 → 开始 · 节点可点击直达 · 本章是全课程先修

深挖完整讲义 · 专题 1 最小化 Agent Loop ↗

00-A · 一句话定义

Agent = 让模型循环干活的程序

1

模型只会两件事：想（生成文字）和说要动手（发工具调用） 它自己碰不到文件系统、跑不了命令——动手永远发生在你的程序里

2

Agent 程序补上剩下的三件事：执行、记录、循环 替模型跑工具、把结果记下来、带着记录再问模型——直到它说"完成了"

3

"AI 自主完成任务"的真相：一个循环在转 没有任何魔法——课程后面所有的评测、分析、训练，分析的都是这个循环的运转记录

这个程序长什么样？——先看它的六个组成部分

00-B · 总图

六个部分，一条数据流

Agent Loop 数据流（六部分如何接力）

用户任务
   ↓
⑥ 主循环启动 ── ② 系统提示词 + 任务写入 ③ 对话历史
   ↓
④ 模型调用器：把 ③ 历史 + ① 工具清单发给大模型
   ↓
⑤ 响应解析：这次回复里有工具调用吗？
   ↓
   ├─ 没有（纯文本）→ 任务完成，⑥ 终止，输出总结
   │
   └─ 有 → ① 执行对应本地函数 → 结果写回 ③
              ↓
         回到 ④，发起下一轮……

背下这条流，任何 Agent 的源码你都能对号入座

深挖六部分规格详解 ↗

00-C · 四角色类比

大脑、手、小本子、代理

会想，不会做大脑大模型 + 系统提示词（②）。每轮只决定"下一步干什么"，转身就忘

会做，不会想手工具清单（①）。读写文件、跑命令——真正干活的本地代码

不会思考，但记得一切小本子对话历史（③）。大脑唯一的记忆来源——没记下来 = 没发生过

替用户把任务办成代理主循环（⑥）。安排"想→做→记"循环、管何时停——Agent 一词的本义

Agent = Agent：它就是"代理"——办事的过程就是那个循环

00-D · 六步骤之 ①

工具清单：声明"能做什么"

1

每个工具四要素：名称、描述、参数定义、本地执行函数 前三样发给模型看（API 的 tools 字段），第四样留在本地——模型永远只见声明

2

最常用的就四件：读、改、写、bash read / edit / write / bash 恰好映射工程师在终端做的一切——bash 是逃生舱

3

没有它会怎样：模型只会聊天 再聪明的模型，没有工具接口也改不了一个逗号

模型凭什么知道何时调哪个工具？——靠描述文本，也靠下一屏

00-D · 六步骤之 ②

系统提示词：约束"该怎么做"

1

它是给大脑的岗位说明书 身份（你是代码修改助手）+ 规则（改前先读）+ 安全边界（只许动当前目录）

2

对应的 API 概念：messages 里 role: system 的第一条排在所有对话之前，模型每轮都会看到它

3

没有它会怎样：模型按通用聊天行事拿到任务先反问你十个问题，而不是动手

说明书有了，但模型的记忆在哪？——下一屏

00-D · 六步骤之 ③

对话历史：记住"做过什么"

1

模型 API 是无状态的：每次调用从零开始它不记得上一轮说过什么——必须把完整历史重新传入

2

历史就是一个消息列表：system / user / assistant / tool 工具结果用 role: tool 回填，靠 tool_call_id 关联"哪次调用的结果"

3

没有它会怎样：模型每轮失忆 读了文件、跑完测试，下一轮全忘——任务永远做不完

这本"小本子"谁负责递给模型？——下一屏

00-D · 六步骤之 ④

模型调用器：负责"怎么通信"

1

把 ③ 历史 + ① 工具清单打包成一次 API 请求 client.chat.completions.create(...)——模型、参数、密钥都在这层管

2

脏活全在这层：超时、限流、重试、格式异常 上层只管"发历史、收回复"，不碰网络细节

3

没有它会怎样：业务逻辑和网络细节搅在一起 每换一个模型供应商就要改一遍主循环

回复回来了——里面装的是什么？下一屏拆开看

00-D · 六步骤之 ⑤

解析与调度：决定"下一步做什么"

1

回复只有两种情况需要区分：带不带工具调用 tool_calls 非空 → 执行；为空（纯文本）→ 任务完成的信号

2

工具调用三步：取名字和参数 → 路由到本地函数 → 结果回填历史 注意 arguments 是 JSON 字符串，要先解析——新手第一大坑

3

错误也要回填：报错信息照写进历史模型下一轮看到错误会自己换方法——Agent 自我修复的种子

单步会了——怎么串成完整任务？靠最后一环

00-D · 六步骤之 ⑥

主循环：控制"何时停下来"

1

循环体就五行：调模型 → 有调用？→ 执行 → 回填 → 再来 终止条件：模型不再要动手（纯文本）= 它认为任务完成

2

必须有守门机制：最大轮数、超时、异常捕获没有守门，一个死循环就能烧光预算——真实产品三重守门（轮数/费用/时间）

3

业界实证：agent loop 就是一个 while 循环 没有规划器、没有状态机——规划发生在模型上下文里，代码只管接工具、喂结果

六个零件齐了——看它们在一个真实任务里转起来

深挖六部分到工程 harness ↗

00-E · 例 · 教学预演

真实任务，五轮转完

任务来自 SWE-bench Lite（pytest-dev__pytest-5227）：把 pytest 默认日志格式加上模块名——官方修复只改一行常量。

五轮消息流（压缩版）

第 1 轮 · 找位置    bash: grep -n DEFAULT_LOG_FORMAT … → 命中 logging.py
第 2 轮 · 看上下文  read_file: logging.py → 看见常量定义与用法
第 3 轮 · 精准改    edit_file: 旧格式串 → 新格式串（"已替换 1 处"）
第 4 轮 · 验证      bash: python -c "print(DEFAULT_LOG_FORMAT)" → 新串 ✓
第 5 轮 · 收工      纯文本总结 → ⑥ 终止条件满足，循环结束

注意：真正"改代码"只占一个动作——其余四轮都在定位、看、验证

深挖专题 1 · 完整五轮 + 100 行实现 ↗

00-F · 例 · 本仓实测轨迹