一个循环，就是 Agent 的全部

「拆解 Agent Harness」系列 · 第一篇

本系列文章基于开源教学项目 learn-claude-code 撰写。从最简单的 Agent Loop 开始，逐步叠加工具调度、任务管理、子代理、上下文压缩、多 Agent 协作等机制，完整还原一个生产级 AI 编程 Agent 的构建过程。

每篇文章对应一个脚本，配合真实 API 通信数据逐轮拆解，让你不仅知道“是什么”，更知道“为什么”和“怎么做”。

适用人群：产品经理、设计师等非专业开发者；想了解Agent的基本实现过程；以及Harness到底在做什么；

Codex、Claude Code、Windsurf——这些 AI 编程工具能自动帮你读文件、写代码、跑命令。它们看起来很“智能”，但背后的核心机制其实只有一个——Agent Loop（代理循环）。今天我们从原理到实战，把它讲透。

一、你在 ClaudeCode 里敲了一句话，然后发生了什么？

打开 ClaudeCode，输入：

“查看当前目录有哪些文件，创建一个 hello_agent.txt，写入 Hello，最后读取确认。”

3 秒后，文件创建好了，内容也确认了。这中间到底发生了什么？

大多数人的直觉是：“AI 理解了我的话，然后自己去操作了”。

但这个直觉是完全错的。接下来我要告诉你两个可能会颠覆你认知的事实。

二、两个关键真相

真相一：AI 模型不能执行任何操作

ChatGPT 也好，Claude 也好，它们本质上只做一件事——接收一段文本，输出一段文本。就这样。（暂不考虑多模态）

它不能碰你的文件系统，不能敲终端命令，不能访问网页。你在 ClaudeCode 里看到的“AI 帮我创建了文件”——那不是 AI 干的。

真相二：有一个“看不见的程序”在帮 AI 干活

这个程序叫 Harness（驾驭程序）。它是 AI 和你电脑之间的桥梁：

1. 读取 AI 输出的文本
2. 从中解析出“我想执行 ls -la”这样的指令
3. 在你的电脑上真正执行
4. 把执行结果传回给 AI

所以真相是：AI 只是“大脑”，Harness 才是“手脚”。

Agent 幕后真相

大脑想了一个动作 → 手脚去执行 → 执行完把结果反馈给大脑 → 大脑再想下一步——这个循环，就叫 Agent Loop。

三、Agent Loop 到底怎么转？

理解了“大脑+手脚”的分工，现在我们看这个循环具体怎么运作。整个过程只有 4 步，然后不断重复：

Agent Loop 运作流程

第 1 步：发送请求

你的话（加上之前的对话历史）被打包成一个 messages 数组，连同可用工具列表一起发送给 AI 模型的 API。

第 2 步：AI 思考并做决定

模型不直接回答你的问题，而是输出**“我需要执行哪些工具”**。比如：

同时，AI 的回复里携带一个关键信号 —— stop_reason：

• tool_use：“我还要用工具，先帮我执行” → 循环继续
• end_turn：“我说完了” → 循环结束

第 3 步：Harness 执行工具

Harness 拿到 AI 的指令后，在你的电脑上逐个执行命令，收集每条命令的真实输出。

第 4 步：把结果喂回给 AI

Harness 把所有执行结果追加到对话历史末尾，重新发送给 AI。AI 看到结果后，要么继续调用工具（回到第 2 步），要么认为任务完成，返回最终回复。

这就是 Agent Loop 的全部。 没有魔法，没有复杂架构——就是“AI 说要干什么 → 程序代它去干 → 把结果告诉 AI → AI 决定继续还是收工”的循环。

四、驱动一切的代码，只有 20 行

你可能不信，上面演示的全部能力，核心代码只有这么点：

def agent_loop(messages):
    while True:
        # ① 把消息历史发给 AI，拿到响应
        response = call_ai_model(messages)

        # ② 把 AI 的回复追加到历史
        messages.append({"role": "assistant", "content": response.content})

        # ③ 如果 AI 没调工具 → 循环结束
        if response.stop_reason != "tool_use":
            return

        # ④ 逐个执行 AI 要求的工具，收集结果
        results = []
        for tool_call in response.content:
            output = execute(tool_call)
            results.append({"tool_use_id": tool_call.id, "content": output})

        # ⑤ 把工具结果追加到历史 → 回到循环顶部
        messages.append({"role": "user", "content": results})

注意看这个代码的结构——它就是上面流程图的精确映射：

这个 while 循环，就是 Codex、Claude Code、Windsurf、GitHub Copilot 的共同底层。 所有差异——工具多少、安全控制、上下文管理——都是在这个循环之上叠加的工程机制。

五、实战拆解：看看 API 里真实传了什么

原理和代码都讲完了，但你可能还想知道：“模型收到的和返回的到底长啥样？”

我们实际跑了项目中的 s01_agent_loop.py，抓取了真实 API 通信数据。下面逐轮拆解。

第一轮：用户发话 → AI 规划操作

Harness 发给 AI 三样东西：

HTTP 请求结构

① system（人设指令）——告诉 AI “你是谁”：

"You are a coding agent. Use bash to solve tasks. Act, don't explain."

② tools（可用工具列表）——告诉 AI “你能用什么工具”：

[{ "name": "bash", "description": "Run a shell command." }]

这里只注册了 1 个工具 bash。真正的 Claude Code 有几十个（读文件、写文件、搜索、浏览器等），但原理完全一样。

③ messages（对话历史）——此时只有用户的 1 条消息：

[{ "role": "user", "content": "查看文件，创建 hello_agent.txt，写入 Hello，读取确认。" }]

AI 返回了什么？

3 个工具调用指令（在 content 数组里）：

{"name":"bash","input":{"command":"ls -la"}}
{"name":"bash","input":{"command":"echo 'Hello from Agent Loop!' > /tmp/hello_agent.txt"}}
{"name":"bash","input":{"command":"cat /tmp/hello_agent.txt"}}

停止信号：

stop_reason: "tool_use"   ← "先帮我执行这些，我还没说完"

注意：AI 并没有真的执行任何命令——它只是输出了一段 JSON 文本，说“我想执行这三个命令”。是 Harness 读了这段文本，在你电脑上真正敲了这三条命令。

Token 消耗：输入 114 tokens，输出 65 tokens。

然后：Harness 在本地执行

Harness 看到 stop_reason == "tool_use"，知道循环要继续。它逐个执行 AI 的指令：

$ ls -la
total 192  drwxr-xr-x  15 qianweiqiang  staff ...
agents/  docs/  skills/  web/  ...

$ echo 'Hello from Agent Loop!' > /tmp/hello_agent.txt
(no output)

$ cat /tmp/hello_agent.txt
Hello from Agent Loop!

三条命令的输出收集完毕，准备回传给 AI。

第二轮：AI 看到结果 → 确认完成

现在到了最精华的地方——看 messages 数组发生了什么变化。

两轮循环 messages 增长对比

第一轮发了 1 条消息，现在变成了 3 条：

messages: [
  // ❶ 你的原始请求（第一轮就有的）
  { "role": "user",      "content": "查看文件，创建文件..." },

  // ❷ AI 上轮的回复——3 个 tool_use 指令（原样传回）
  { "role": "assistant",  "content": [3个 tool_use 指令] },

  // ❸ 新增！Harness 的执行结果
  { "role": "user",      "content": [3个 tool_result 执行结果] }
]

这就是 Agent “记忆”的全部秘密。 模型本身没有记忆——每次调 API，对它来说都是“初次见面”。所谓“记忆”，就是 Harness 每次都把完整的对话历史重新发一遍。第一轮发 1 条消息（114 tokens），第二轮发 3 条消息（671 tokens，膨胀了近 6 倍）。这就是为什么 AI 工具用得越久越费钱——历史越来越长，每轮都要全量重发。

AI 拿到完整历史后的反应：命令都执行了，文件内容确认了，任务完成。

它返回纯文字回复，不再调用工具：

content: [{ "type": "text", "text": "任务完成！文件已创建，内容确认无误。" }]
stop_reason: "end_turn"   ← "我说完了，循环结束"

Harness 检测到 stop_reason != “tool_use”，退出循环，把最终回复展示给你。

整个过程就 2 轮循环，搞定。

六、三个你应该记住的关键认知

1. 模型没有记忆——“记忆”靠重发

每次调 API，对 AI 都是全新的对话。Harness 用全量重发模拟出“记忆”的效果：

如果任务需要 10 轮循环，最后一轮可能要发几万 tokens。这就是 AI 产品的核心成本结构。

2. 安全边界在 Harness，不在 AI

AI 说“执行 rm -rf /”——但它自己执行不了。Harness 可以选择拒绝。

安全靠的是工程架构，不是 AI 的自觉。这也是为什么 Claude Code 有权限审批系统、Cursor 有沙箱隔离——都是 Harness 层面的安全机制。

3. 循环何时结束，由 AI 自己决定

不是“跑 3 次就停”，是 AI 自己判断任务完没完，返回 end_turn 才停。

复杂任务可能循环 10+ 轮。这就是为什么有时你在 Cursor 里等得久——AI 在循环里来回跑了很多轮。

七、从玩具到产品：这个循环之上还需要什么？

上面演示的 Agent 只有 1 个工具、没有安全控制、没有上下文管理。真正的商业产品呢？

但底层那个 while 循环？一模一样。

所有的高级功能，都是在这个循环之上叠加的工程机制——就像所有的高楼大厦，地基都是钢筋混凝土。

下一篇，我们看怎么给 AI 加一个“记事本”（TodoManager），强制它每步汇报进度——三步不汇报，程序自动催它。依然用真实 API 数据逐轮拆解。

本文基于开源项目 learn-claude-code 的 s01_agent_loop.py 真实代码和执行数据撰写。完整代码和运行方法见项目 README。