IronClaw 学习笔记 02：Agent Loop

上一篇我们装好了"手"（Tool）和"脑"（LLM Provider），但它们还没有接线。这一篇把它们连起来，造一个真正的 Agent。

🎯 这一篇要解决什么问题？

Phase 01 结束时，tiny-claw 有了工具系统和 LLM 接口，但 REPL 依然只是 echo。工具没人调用，LLM 没人询问。就像一个有手有脑但没有神经系统的生物——零件齐全，但不会动。

这一篇要接的那根"神经"叫做 Agent Loop。它是 agent 的核心控制循环：

用户说话 → LLM 思考 → 调用工具（可能多轮） → LLM 总结 → 返回答案

这不是简单的"调一次 API 拿个回复"。LLM 可能决定先查时间、再查天气、最后综合回答——一个请求触发多轮工具调用。这种"思考→行动→观察→再思考"的循环就是 ReAct 模式。

---

🧠 ReAct：Reasoning + Acting

ReAct 是 2022 年提出的 agent 范式，核心思想是让 LLM 交替进行推理（Reasoning）和行动（Acting）：

关键在于步骤 2-4 是可重复的。如果用户问的问题需要多个工具，LLM 会连续发出多个 tool_call，每次都把工具结果追加到对话历史中，直到它认为信息足够了，才输出最终的文本回复。

循环的终止条件很简单——LLM 返回纯文本，不包含 tool_call。

---

🏛️ 从 OpenCode 到 IronClaw：Agent Loop 的概念迁移

---

🏛️ Dispatcher：ReAct 循环的实现细节

循环体逻辑：

loop {
    若达到迭代上限 → 移除所有工具（Force text）
    调用 LLM → 获得回复
    若回复是纯文本 → 返回，循环结束
    若回复包含 tool_calls → 并行执行（JoinSet）→ 结果追加到对话 → 继续循环
}

并行工具执行

IronClaw 利用 Rust 的 JoinSet 实现工具的并行执行。如果 LLM 一次返回多个 tool_call（比如同时查时间和搜索新闻），它们会被并行执行。

谁决定哪些工具可以并行？完全由 LLM 决定。 客户端不做任何依赖分析——LLM 若认为两个工具之间没有数据依赖，会在同一 response 中返回多个 tool_calls；若存在依赖，会先返回一个，等结果回来再下一轮返回另一个。tiny-claw 同样用 JoinSet 并行执行，通过 tool_call_id 匹配结果，不依赖消息顺序。

---

📝 tiny-claw Phase 02 的简化策略

目标：用最少的代码实现完整的 ReAct 闭环——用户提问，LLM 推理，调用工具，LLM 总结，返回答案。

---

🧪 动手试试

tiny-claw Phase 02 有 6 个工具：echo、time、web_search、list_dir、read_file、write_file。试试这几个 query，观察日志中的 iteration 次数和并行行为：

---

📝 本篇总结

下一篇：IronClaw 学习笔记 03：持久化 —— Workspace 文件系统设计、FTS + Vector 混合搜索原理、RRF 融合算法。