Harness 工程 · 第 3 章 Agent 主循环

Harness 工程 · 第 3 章 Agent 主循环

章节摘要：组件篇第一章，解剖 harness 唯一不可省略的组件——主循环。3.1 把循环拆成四拍：感知（组装上下文）、决策（调用模型）、行动（执行工具）、观察（结果回填），并给出约 60 行的最小可运行循环 mini_loop.py——它是本书第一块积木，也是第 10 章 mini-harness 的心脏。3.2 处理循环的"暗面"：终止条件（最大步数、空转检测）与失败处理（错误风暴熔断、优雅放弃），这些边角代码决定了 agent 是"能干活"还是"能闯祸"。3.3 讲上下文组装的时机与策略：无状态 API 决定了每一步都是重新供料，装什么、怎么裁、预算怎么分，是循环设计里杠杆最大的一格。章末把循环骨架升级为带守卫的版本，交棒给第 4 章工具系统。

学习目标

阅读完本章，你应当能够：

1. 说出主循环四拍（感知—决策—行动—观察）各自的输入输出。
2. 读懂并运行 mini_loop.py，指出每行对应四拍的哪一拍。
3. 为循环设计四类终止条件与错误风暴熔断器。
4. 解释"每一步都是重新组装上下文"及其工程含义。
5. 列出流式输出、并行工具调用等生产化细节的最小处理方式。

核心概念速览

（文字流程图）
T ──"返回 tool_calls"──▶ "③ 行动：执行工具·（权限门 → 派发）"
"③ 行动：执行工具·（权限门 → 派发）" ──▶ "④ 观察：结果回填 messages"
"④ 观察：结果回填 messages" ──"下一步"──▶ S
T ──"无 tool_calls"──▶ "终止：最终答案"
​

一句话金句：主循环十行就能跑起来，剩下四百九十行都在处理"它不按你想的跑"的情况。

子章节导航

3.1 感知决策行动：循环的解剖

四拍模型、最小循环 mini_loop.py（约 60 行）、每行的组件归属；流式与并行的最小处理。

3.2 终止条件与失败处理

正常终止的判别（含"假完成"防线）、四类终止条件、空转检测、
错误风暴熔断（熔断器参考实现 breaker.py）、优雅放弃的结构化报告——
"放弃也是一种交付"。

3.3 上下文组装的时机与策略

为什么每步重组、上下文五层清单、预算分配与裁剪三板斧（截断/摘要/引用化）、
与主循环的接口约定 assemble_context(state, budget)——供料必须是可替换的策略函数。

子章节之间的逻辑关系

3.1 循环的解剖（正向路径：四拍怎么转起来）
   │
   ▼
3.2 终止与失败（反向路径：怎么让它停下来、坏了怎么办）
   │
   ▼
3.3 上下文组装（第一拍的深挖：供料策略决定循环质量）
​

前置知识与后续延伸

前置知识：第 1.3 节全景图（循环是脊柱）；function calling 的基本概念（messages、tool_calls）。

为后续奠定基础：mini_loop.py 是第 4 章 registry.py 的宿主、第 10 章 mini-harness 的心脏；3.2 的熔断器是第 8 章 Hook 与反馈的接点；3.3 是第 7 章上下文工程的序章。