MODULE 01 · AGENTFORGE 系列

Agent Loop

理解 Agent 的心脏 — 一个 while True 循环如何让 AI "活"起来

想象你是一个餐厅服务员:客人点菜 → 你告诉厨师 → 厨师做好端上来 → 你送给客人 → 客人可能再点一道 → 循环继续…直到客人说"买单"。

Agent Loop 就是这个永不疲倦的服务员,而 LLM 就是那个厨师。

向下滚动开始学习↓
01 · 核心概念

🔄 什么是 Agent Loop?

一句话:Agent Loop 就是一个 while True 死循环,它让 AI 不停地"思考→行动→观察",直到任务完成。

类比:你在解一道数学题
你不会一步算出答案。你的过程是:
① 读题(输入)→ ② 想下一步怎么做(推理)→ ③ 动笔计算(执行)→ ④ 看看结果对不对(观察)→ ⑤ 如果没做完,回到②继续。

Agent Loop 做的是完全一样的事情,只不过"你"变成了 AI,"动笔计算"变成了"调用工具"。

👤
用户输入
→
🧠
LLM 推理
→
🔧
工具执行
→
📋
结果返回
🔁 循环继续
关键理解:AI 自己不能上网、不能读文件、不能执行命令。它只能"想"。所以它需要工具来帮它做事,而 Agent Loop 负责把工具的结果"喂"回给 AI,让它继续思考。
02 · 循环的两个信号

🚦 循环什么时候停?

循环不能永远转下去。它靠一个叫 stop_reason 的信号来决定"继续"还是"结束"。

类比:交通信号灯
🔴 红灯(stop_reason ≠ tool_use)= "我做完了"→ 循环停止,返回结果
🟢 绿灯(stop_reason = tool_use)= "我还需要用工具"→ 执行工具,继续循环

stop_reason 的值含义循环动作
tool_use AI 说:"我要用一下工具" 执行工具 → 结果喂回去 → 继续循环 🔄
end_turn AI 说:"我说完了" 退出循环,返回最终答案 ✅
max_tokens AI 说太多话了,被强制打断 ⚠️ 异常情况,需要处理

📨 消息是怎么流动的?

在循环过程中,所有对话内容都存在一个列表 messages[] 里,像聊天记录一样不断追加:

👤

user 消息

用户说的话,或者工具返回的结果(没错,工具结果也用 user 角色发送)

🤖

assistant 消息

AI 的回复,可能是文字回答,也可能是"我要调用某个工具"

⚙️

system 消息

系统提示词,告诉 AI "你是谁"以及"你能做什么",在最开头设置一次

为什么要保存所有消息?因为 AI 没有记忆!每次调用它,都要把完整的聊天记录一起发过去,它才能"记住"之前发生了什么。这就像你每天都要给同事重新描述一遍今天发生了什么。
03 · 代码详解

📝 逐行读懂核心代码

下面这段代码就是 Agent 的"心脏"。我们一行一行拆解,保证你看得懂。

agent/core/loop.py
1 def _agent_loop(self, verbose: bool = False) -> str:
2 """Agent 核心循环"""
📌 定义一个函数 _agent_loop。前面加下划线 _ 表示这是"内部方法",外面不应该直接调用它。
3 while True:
🔁 死循环开始!就像一个永不停歇的转盘。只有满足退出条件(return)才会停下来。
4 if self.state.has_exceeded_max_turns():
5 return f"Error: Exceeded maximum turns"
🛡️ 安全阀!如果循环次数超过上限(默认100次),强制停止。防止 AI 陷入无限循环——就像给跑步机设了最长时间。
6 self.state.increment_turn()
📊 轮次计数器 +1。每转一圈就记录一次,方便监控和调试。
7 response = self._call_llm()
🧠 核心操作:调用 LLM!把所有聊天记录发给 AI 大模型,等它"思考"并给出回答。这一步可能需要几秒到几十秒。
8 self.history.add_assistant(response.content)
💾 把 AI 的回复保存到聊天记录里。这样下次调用时,AI 能"记住"自己说了什么。
9 if not self._has_tool_use(response):
🚦 关键判断点!检查 AI 的回复里有没有说"我要用某个工具"。如果没有 → 说明 AI 觉得任务做完了。
10 final_text = self._extract_text(response)
11 hook_result = self._trigger_hooks("Stop", ...)
12 if hook_result:
13 continue # Hook 说"还要继续"
14 return final_text # 🎉 正常退出!
🏁 循环出口!提取 AI 的文字回答,触发停止钩子(Hook),然后 return 跳出 while True 循环。如果没有 Hook 阻止,任务就完成了!
15 tool_results = self._execute_tools(response, verbose)
🔧 执行工具!AI 说"我要读个文件"或"我要跑个命令",这里就真的去执行,拿到结果。
16 self.history.add_tool_results(tool_results)
📋 把工具执行结果存进聊天记录,下一轮循环时 AI 会看到这些结果,然后继续思考。→ 回到第3行,循环继续!
04 · 关键函数

⚙️ 三个关键函数拆解

核心循环虽然只有十几行,但它调用了三个"打工人"函数来完成具体工作。

📡

_call_llm()

信使:把聊天记录和工具定义打包发给 AI 大模型,等它回复。就像把信寄出去,等回信。

🔍

_has_tool_use()

检查员:翻看 AI 的回复,找有没有"tool_use"标记。有的话说明 AI 想用工具。

🔨

_execute_tools()

执行者:拿到 AI 指定的工具名称和参数,真的去执行,然后把结果收集起来。

📡 _call_llm() — 给 AI 发消息

_call_llm()
def _call_llm(self): # 获取完整的聊天记录 messages = self.history.get_messages() # 调用 Anthropic API(就是 Claude 的接口) return self.client.messages.create( model=self.model, # 用哪个模型(如 claude-3) system=self.system_prompt, # 系统提示词(AI 的人设) messages=messages, # 聊天记录 tools=self.tools, # 可用工具列表 max_tokens=self.max_tokens, # 最多生成多少字 )

类比:点外卖
model = 选哪家餐厅(模型)
system = 备注"不要辣"(AI 的人设约束)
messages = 你之前跟店家的所有聊天记录
tools = 店家能做的菜品列表(AI 可用的工具)
max_tokens = 最多做几道菜(限制回复长度)

🔨 _execute_tools() — 执行工具

_execute_tools()
def _execute_tools(self, response, verbose=False): results = [] for block in response.content: if block.type != "tool_use": continue # 跳过文字部分,只处理工具调用 # 执行前的钩子(可以阻止某些工具执行) hook_result = self._trigger_hooks("PreToolUse", block) if hook_result: continue # 钩子阻止了执行 # 找到对应的工具处理器,执行它 handler = self.tool_handlers.get(block.name) output = handler(**block.input) # 真正执行! # 执行后的钩子 self._trigger_hooks("PostToolUse", block, output) results.append({...}) # 收集结果 return results
Hook 是什么?Hook 就像"中间人"或"安检员"。在工具执行之前(PreToolUse)和之后(PostToolUse),都可以插入自定义逻辑。比如:禁止 AI 执行 rm -rf / 这种危险命令。
05 · 设计模式

🎨 代码里用了哪些设计模式?

设计模式就是"前辈们总结的编程套路"。Agent Loop 用了三种经典模式。

🔄

状态模式

Agent 有不同的状态(空闲→运行→等待→完成),每个状态有不同的行为。就像红绿灯,不同颜色对应不同动作。

📢

观察者模式

Hook 系统就是观察者。当 Agent 发生事件(工具执行前/后),所有注册的 Hook 都会被通知。就像微信群发消息,所有人都能看到。

🧩

策略模式

不同的工具(读文件、执行命令、搜索)都是"策略",Agent 根据 AI 的选择调用对应的策略。就像餐厅菜单,点什么做什么。

06 · 实战测验

🧪 来检验一下你的理解!

做完这些题,你就知道自己是不是真的理解了 Agent Loop。

📝 选择题

Q1当 LLM 返回的 stop_reason 是 "tool_use" 时,Agent Loop 应该怎么做?
Q2为什么每次调用 LLM 都要发送完整的聊天记录?
Q3max_turns 的作用是什么?
Q4在 _execute_tools() 函数中,"PreToolUse" Hook 的作用是?
Q5(填空)Agent Loop 的核心是一个 True 循环。
0/5
答对题数
07 · 深入探索

🔬 想了解更多?

这些内容超出基础范围,但如果你想深入理解 Agent,值得看看。

🧪 Stop Hook 的高级用法

▼

在代码第 11-13 行,我们看到当 LLM 表示"我说完了"时,还会触发一个 Stop Hook。这个 Hook 可以返回新的用户消息,让循环继续!

实际应用场景:

• 自动审查:AI 说"我做完了",但 Hook 检查结果发现有遗漏,自动追加"请再检查一遍"

• 多轮确认:AI 完成任务后,Hook 自动添加"请确认你的修改",实现人机协作

• 自我纠错:Hook 检查 AI 的输出是否符合格式要求,不符合就要求重做

这种设计让 Agent 不仅能"做事",还能"自我反思和改进"——这正是高级 Agent 的核心能力。

⚡ 并行工具执行 vs 串行执行

▼

在 _execute_tools() 中,工具是逐个串行执行的(for 循环)。但如果 AI 一次请求了多个工具呢?

比如 AI 说:"同时读取 file1.py 和 file2.py"——两个读文件操作完全独立,串行执行就浪费时间了。

优化方案:

• 使用 asyncio.gather() 并行执行独立的工具调用

• 用有向无环图(DAG)分析工具间的依赖关系

• 只对有依赖的工具串行,无依赖的并行

这就是为什么生产级 Agent 比教学示例快得多的原因之一。

🌊 Token 窗口与上下文压缩

▼

随着循环进行,messages[] 会越来越长。但 LLM 的上下文窗口是有限的(比如 Claude 约 200K tokens)。

当消息太长时怎么办?

• 截断:丢弃最早的消息(简单但可能丢失重要信息)

• 摘要压缩:让 LLM 把旧消息总结成一段话,替代原始消息

• 滑动窗口:只保留最近 N 轮对话

• 重要性排序:根据消息的重要性选择性保留

这就是文档中提到的 [[06-Memory System]] 要解决的问题——Agent 的"记忆管理"。

🤔 为什么叫 "stop_reason" 而不是 "status"?

▼

这是 Anthropic API 的设计选择。stop_reason 回答的问题是"模型为什么停了?"而不是"模型的状态是什么?"

这种设计更精确:状态可以有很多种,但"停止原因"直接告诉你下一步该做什么:

• tool_use → "我需要工具" → 你该去执行工具

• end_turn → "我说完了" → 你该返回结果

• max_tokens → "我被截断了" → 你该处理异常

每个值都是一个明确的行动指令,而不仅仅是一个状态标签。这是 API 设计的好范例。

08 · 总结

📋 本节核心要点

🎯 你学到了什么

  • Agent Loop = while True 循环,是所有 Agent 行为的基础骨架
  • 两个关键信号:tool_use(继续循环)和 end_turn(退出循环)
  • 消息历史是 Agent 的"短期记忆",每次调用 LLM 都要带上完整记录
  • 三个核心函数:_call_llm(通信)、_has_tool_use(判断)、_execute_tools(执行)
  • Hook 系统让循环可扩展:执行前可拦截,执行后可审计,停止时可继续
  • 安全阀 max_turns 防止无限循环,是生产环境的必要保护

最终类比:Agent Loop 就像一个永不停歇的厨师学徒
它拿到订单(用户输入)→ 做菜(LLM 推理)→ 需要什么食材就去拿(工具执行)→ 做好了端给客人 → 如果客人说"再来一道"就继续做 → 直到客人满意离开。

30 行的 while True 就是 Agent 的核心。所有复杂功能都是在这个循环上叠加的。