第一章 智能体循环（Agent Loop）——手写ClaudeCode核心机制
[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12
一、面临的问题
即便语言模型的推理能力再出色，它也无法直接触碰真实世界——它不能读取文件、无法运行测试、也不会查看报错信息。在没有自动循环机制的情况下，每次调用工具后，你都需要手动将结果粘贴回模型。说白了，你本人就是那个笨重的循环。
二、解决方案
如何突破这一瓶颈？引入一个自动循环，让模型能够持续地思考→行动→观察→再思考，直至任务完成。这就是经典的ReAct（Reasoning and Acting）范式。下面的ASCII图清晰展示了其骨架结构：
+--------++-------++---------+
| User | ---> | LLM | ---> | Tool |
| prompt|| || execute |
+--------++---+---++----+----+
^||
| tool_result|
+----------------+
(loop until stop_reason != "tool_use")一个简单的退出条件控制着整个流程。循环不断运行，直到模型决定不再调用任何工具。s01_agent_loop.py 所要达到的效果，就是用不到50行代码，把你手动搬砖的那部分工作彻底自动化。
这就是经典的ReAct范式——一种让AI边思考边行动的交互模式，使大语言模型能够像人类一样推理→行动→观察→再推理，从而逐步解决复杂的实际问题。
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Thought │ ──→ │ Action │ ──→ │ Observation │ ──→ │ Thought │
│ (思考) │ │ (行动) │ │ (观察) │ │ (再思考) │
└─────────────┘ └─────────────┘ └─────────────┘ └──────┬──────┘
│
任务完成 ←────────────────────────────┘
给出答案三、工作原理详解
- 将用户的 prompt 作为第一条消息送入对话。
messages.append({"role": "user", "content": query})- 将消息列表和工具定义一起发送给大模型。我们定义的 TOOLS 列表就像一本“工具使用手册”，它作为输入的一部分被喂给大模型。
response = client.messages.create(
model=MODEL, system=SYSTEM, messages=messages,
tools=TOOLS, max_tokens=8000,
)- 追加助手响应，然后检查
stop_reason——如果模型没有调用工具，则循环结束。
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
return- 逐一执行每个工具调用，收集返回结果，并以 user 消息的形式追加到对话中。然后回到第2步继续。
results = []
for block in response.content:
if block.type == "tool_use":
output = run_bash(block.input["command"])
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})- 将所有步骤组装成一个完整的函数：
def agent_loop(query):
messages = [{"role": "user", "content": query}]
while True: # 循环开始，理论上可以无限跑
# ... 这里是 LLM 思考的过程 ...
response = client.messages.create(
model=MODEL, system=SYSTEM, messages=messages,
tools=TOOLS, max_tokens=8000,
)
messages.append({"role": "assistant", "content": response.content})
# ... 这里就是那个“唯一的退出条件” ...
if response.stop_reason != "tool_use":
return
results = []
for block in response.content:
if block.type == "tool_use":
output = run_bash(block.input["command"])
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})不到30行代码，这就是一个完整的智能体核心。后面11个章节都会在这个循环上叠加各种机制——而循环本身始终不变。
四、变更内容一览
| 组件 | 之前 | 之后 |
|---|---|---|
| Agent loop | (无) | while True + stop_reason |
| Tools | (无) | bash (单一工具) |
| Messages | (无) | 累积式消息列表 |
| Control flow | (无) | stop_reason != "tool_use" |
五、动手试一试
在运行之前，别忘了先添加 .env 配置文件。
cd learn-claude-code
python agents/s01_agent_loop.py可以试试以下 prompt（英文提示词对 LLM 效果更好，中文也可以）：
Create a file called hello.py that prints "Hello, World!"List all Python files in this directoryWhat is the current git branch?Create a directory called test_output and write 3 files in it
六、补充说明
block 长什么样？
将 block 打印出来，也就是 response.content，它是一个 ToolUseBlock 对象。
ToolUseBlock(
id='bash_0', # 工具调用唯一标识符
caller=None, # 调用者信息（教学版中为None）
input={'command': 'echo \'print("Hello, World!")\' > hello2.py'}, # ← 核心参数
name='bash', # 工具名称
type='tool_use' # 块类型
)
