1. 从一次对话“卡死”说起：为什么你需要深拆 Agent Loop
先讲个真实场景。上个月我在调一个多步骤任务型的 Agent，目标是让它从一堆报销单据里提取金额、核对账目、再生成汇总表。一开始我只给了它一个 API Key、一套工具函数和一个“去干活”的提示词，结果它经常干到一半就停住了——有时候是没调工具就自己猜数据，有时候是连续调同一个工具绕圈圈，最气人的是有一次它已经生成完表格了，却没有返回结果，整个流程挂在“思考”阶段不动了。
后来我把它的运行日志翻出来，逐行去对“感知、推理、行动、观察”这几步，才发现问题全出在执行循环的失控上。修完循环逻辑之后，任务成功率直接翻了差不多一倍。
这就是我今天想聊的主题：Hermes Agent Loop，也就是 AI Agent 的核心执行循环。不管你是自己写过一个 agent，还是用 LangChain、LlamaIndex、AutoGPT 这类框架，又或者只是好奇“Agent 怎么自主跑完一个任务”，你都要先理解一个最基本的问题：Agent 的本质就是一个无限循环的“感知—思考—行动—观察”机器，所有花哨能力都是建立在这个循环之上的。
这篇文章我打算从四个面去拆：先讲 Agent Loop 的底层结构，为什么它长这样；再拆核心组件，把规划、工具调用、记忆、反思这些关键环节逐个说透，配上参数计算和取舍逻辑；第三段我会用具体的执行链路去演示一个循环是怎么完整跑完的，每一步背后到底发生了什么，包括 token 消耗怎么算、上下文要怎么控制、工具返回的结果怎么消化；最后给你一份我实际调试中踩过的问题清单，以及排查思路。
内容适合的人群，我分三类：一是已经在用现成 Agent 框架但觉得不托底、想搞明白背后逻辑的开发者和产品经理；二是准备从零手写 Agent、希望避开常见坑的技术人；三是想深入理解 Agent 执行机制，方便后面做评测、调优、甚至面试用的研究型读者。
先说好，这篇不是什么学术论文，我讲的和讨论的都是工程落地的经验。我会把复杂概念用生活化的类比拆开揉碎讲清楚，也会把可以在项目里直接抄的代码骨架、配置要点给你列出来。你照着做，至少能把你的 Agent 从“偶尔抽风”提升到“基本可控”。
2. Agent Loop 为什么是“循环”，不是“流程线”
很多新手理解 Agent 执行任务，脑子里画的是一个流水线：先收到任务、然后调用一个接口、再调用另一个接口、最后返回结果。这种线性模型在简单场景下够用，一旦任务变得开放、工具变多、目标变复杂，它会立刻崩掉。原因很简单：真实世界的任务不会按你预设的顺序出现。你可能要查 5 个数据源才能确认一个事实；可能在过程中发现原方案走不通、需要临时换一条路；甚至任务本身都是模糊的，得先拆解成子问题才能继续。
所以 Agent 的执行模型天然是一个循环：Agent 不断读取当前状态（感知），决定下一步干什么（思考），执行一个具体动作（行动），然后看结果变成什么样（观察），再根据新状态进入下一轮。用做饭来类比，流水线是“照着菜谱把备菜、切菜、下锅、装盘依次做完”，这是脚本；循环则是“在厨房里一边做、一边看火候、一边尝味道，缺盐加盐，糊了重来”，这是 Agent。
Hermes Agent Loop 的完整结构，我用大白话描述一下就是：用户或者外部系统把一个目标和约束丢给 Agent，Agent 进入展开循环（展开循环的英文可以理解为 expanded loop），每一轮都是“思考-调用-观察”的迭代，直到满足结束条件，才把最终结果还给用户。
loop 感知当前状态 基于状态做推理与决策 执行动作（调用工具 / 生成内容 / 修正方案） 接收观察结果 更新上下文 判断是否达到终止条件 若未终止，继续新一轮 end这样设计的第一个理由是兜底不确定性。提前把每一步的决策点留成动态的，遇到异常路径时，Agent 可以自己调整策略，而不是整个链路断裂。第二个理由是容错。每一轮循环都是一次局部校验的机会——工具调用失败、返回格式不对、模型输出越界，都能在下一次循环里被“看到”并修正。第三个理由是可观测性。因为每一步都落在循环里，你可以打日志、埋点、做超时熔断，整个运行过程是透明可审计的，出问题能定位到具体是哪一轮。
但这些好处不是白来的。循环结构带来一个绕不开的头号问题：上下文会不断膨胀。每一轮观察结果、中间推理都要写进上下文里，轮数一多，Token 消耗会像雪球一样滚起来，而且超出模型上下文窗口之后，老信息被截断，Agent 会彻底“失忆”。这也是为什么真实项目里，Agent Loop 不能裸奔，必须搭配记忆管理和上下文压缩机制。后面我第三大章会专门讲这个问题。
另外还有一个常见误解：Agent Loop 里面“思考”是不是越多越好？我的经验是恰恰相反。太多轮无意义的“自我对话”只会烧 token、拖慢响应，而且会让模型在长链路中出现逻辑漂移。真正好的循环设计，是靠 3 个关键机制把“思考”约束在任务边界内：终止条件、最大轮次、工具调用的副作用控制。
3. 核心组件逐个拆：规划、工具调用、记忆与反思机制
3.1 规划：把大目标拆成可执行的小步
Agent 拿到一个目标之后，第一件事不是立刻调工具，而是把目标分解成一系列可执行的子任务。这就是规划（planning）模块。
规划在实现上通常有两种策略：
- 一次性规划（Plan-then-Execute）：Agent 在开始执行前，把整个任务拆成步骤清单，再按清单逐步执行。优点是结构清晰、可控性好；缺点是任务中途一旦出现意外情况，整个计划可能作废，需要全部重来。适合流程明确、变化少的场景。
- 动态规划（ReAct 风格）：不预设完整计划，而是走一步看一步，每一轮循环根据当前状态决定下一步。优点是灵活、能应对不确定路径；缺点是容易陷入无头苍蝇式的乱撞，需要额外的约束来控制轮次。
两套方案我都试过，没有一个放之四海皆准的选择。我的做法是混合式：先让 Agent 做一次粗粒度的初步计划（只分阶段，不写死细节），进入执行循环后，每一轮再根据观察结果动态微调。说白了就是“大目标用计划锁住，小步骤让它自己发挥”。
规划环节还有一坑：Agent 很容易把太多步骤塞进一次推理里。比如让它“研究一下某行业的市场规模”，它可能先列 10 个步骤，其中一半根本不需要执行。解决方法是给规划模块加一个步骤预算（step budget），限制最多生成多少个步骤。我一般在 prompt 里直接写：
你需要将任务拆解为不超过 4 个核心步骤，每个步骤必须围绕最终任务展开，禁止添加与任务无关的过程性步骤。经过实测，这个约束能把无意义耗时的轮次平均降低了差不多 30%。这里的逻辑是：限定步骤个数，本质上是在强迫模型去分辨“必要的因果链”和“表演式的过程”。很多 Agent 慢，不是任务真的难，是它自己给自己加戏。
3.2 工具调用：Agent 的“手脚”
工具调用是 Agent 能不能落地的关键。没有工具，Agent 只能是一个擅长生成漂亮话的空谈家；有了工具，它才能真正干活。在具体实现里，工具层要解决三个核心问题：工具怎么描述、怎么选择参数、怎么容错。
先说工具描述。绝大多数实现用的是“结构化工具描述”，即给每个工具写一份 JSON 格式的开元信息，包含名字、功能描述、参数 schema、返回值格式。模型根据这些描述来决定什么时候调用什么工具。这里有个细节极易被忽略：工具描述里字段的措辞，直接影响模型选工具的准确率。我踩过这样的坑：一个叫“search_web”的工具，描述只写了“搜索网页”，模型经常在需要查天气的时候去调用它；后来我把描述改成“通过搜索引擎获取实时信息，适合查询新闻、天气、热门事件”，准确率立刻上来了。工具描述的语义越贴近业务场景，模型选得越准。
再说参数选择。框架层面通常用 function calling 机制，让模型输出一个结构化的调用指令，其中包括工具名和参数。你需要注意参数类型的校验。用 JSON Schema 做参数校验是基本操作，但更关键的是 enum 枚举字段。例如有一个工具send_email(recipient, priority)，其中priority只接受high/normal/low三个值，如果你的 schema 没给枚举，模型可能会输出urgent或者重要，工具直接抛异常。
最后是容错。我的原则是“让 Agent 自己学会用别的路”，也就是在工具调用失败时，不要把错误直接丢给模型就完事，而是把错误信息构造为一次“观察结果”重新喂进去，同时给一句提示：如果重试 2 次仍然失败，请换一个方案。这个做法实际执行下来效果很好，Agent 会从“死磕同一个工具”变成“自动绕路”。
3.3 记忆：短期上下文与长期记忆的配合
记忆机制决定了 Agent 能不能有序地利用信息。我简单把它分两层：
- 短期记忆：就是框架里的上下文窗口。它保存当前任务的所有中间状态、工具返回结果、推理历史。短期记忆是 Agent 当前会话里的“工作台”，只保留最新信息。缺点前面说了，会膨胀，需要压缩。
- 长期记忆：跨会话持久化的信息存储，通常是向量数据库（存储知识）和结构化数据库（存储事实）。比如用户偏好、历史任务的结果、领域知识，都可以存到长期记忆里。Agent 在循环开跑前，先做一次“记忆召回”，把与当前任务相关的长期记忆灌入上下文，再开始执行。
记忆这块最常出现的问题是：短期记忆爆掉后，模型会开始“胡言乱语”。表现得很典型：它还能回答问题，但已经想不起来自己一开始要干嘛了，甚至开始编造工具返回结果。这里分享一个我惯用的上下文压缩策略，按重要度分级：
- 必须保留：初始目标、任务约束、用户输入原文、未完成的关键中间结论。
- 可压缩：已被利用过的中间推理、重复性执行的工具结果。
- 可丢弃：低价值的思考过程、失败的尝试记录（只保留其错误摘要）。
我通常在代码里对短期记忆做滑动窗口处理，核心思路是：保留最近 N 轮的完整内容，更早的轮次则用摘要替换（summary-based compression），每一轮都把上轮摘要+新内容作为有效上下文。这样可以把上下文长度缩减到原来的一半左右，模型的执行稳定性反而更好了。
3.4 反思机制：让 Agent 自己给自己挑毛病
反思（reflection）是我认为一个成熟 Agent 和玩具 Agent 最明显的分水岭。反思机制允许 Agent 在完成一个阶段之后，回头审视自己的执行过程，判断结果是否真的对，而不是“看起来差不多就完了”。
最简单的反思实现就是加一个步骤：在 Agent 输出最终答案之前，强制它回答下列问题：
请根据执行记录审视你的最终结论： 1. 你是否真的调用了必要的工具来获得关键数据，还是凭已有知识做了猜测？ 2. 你的回答是否回答了用户的原始问题？请把原始问题再复述一遍然后逐一核对。 3. 执行过程中是否有异常（如工具失败、数据矛盾、信息缺失）被你忽略？ 4. 如果发现了问题，请修正你的结论，然后输出最终答案。这段 prompt 最直接的收益是减少“幻觉输出”。模型在生成答案时往往会走捷径，直接用训练记忆里的知识填充，不靠工具去核实。反思机制相当于在出口再设一道检查岗，逼着模型自己把漏掉的关键证据抓回来。
我在 Hermes Loop 里通常把反思放在两个地方：一是任务中途的里程碑反思，每完成一个子任务，快速检查一下已完成部分与总目标是否一致，避免偏航；二是最终输出前的结果反思，确认答案的完整性和可回溯性。第二个更关键，因为它直接影响用户拿到的结果质量。
反思当然也有成本，平均会增加 10% 到 20% 的 token 开销和一小段延迟。我的经验是：对于低风险任务（比如写个简报、生成个草稿），反思可以简化甚至跳过；对于高风险任务（比如自动扣款、生成法律文本、操作生产数据库），反思环节不能省。
3.5 终止条件：循环不是永动机
Agent Loop 有一个所有入门者都容易忽略的关键问题：怎么停下来。没有清晰的终止条件，Agent 就会变成一台空转的发动机，烧 token 烧到让你怀疑人生。
我在工程实践中把终止条件定成四类，按优先级排序：
| 序号 | 终止条件类型 | 说明 | 兜底措施 |
|---|---|---|---|
| 1 | 目标达成 | 子任务全部完成、结果通过校验 | 结果输出并结束循环 |
| 2 | 早期终止 | 检测到结果已可满足需求，不必继续扩充 | 提前收尾，打印“目标已达成” |
| 3 | 异常终止 | 重试次数超过阈值、工具连续失败计数达到上限 | 输出失败摘要，结束循环 |
| 4 | 最大轮次硬限制 | 达到设定的 max_iterations | 强制踩刹车，返回当前进度 + 建议 |
我强烈建议你给 Agent 设置 max_iterations 参数，宁小勿大。初期我不设这个参数，结果线上跑了一个案例，它因为缺失关键信息，在一个死胡同里绕了 30 多轮才停下来，几分钟就烧掉了大几十万 token，成本炸裂。从那以后我不论用的是什么框架，都强制设硬限制：
max_iterations = 12 for step in range(max_iterations): ... if done: break数值本身怎么定？一个粗参考的预算公式：max_iterations ≈ 子任务数 × 每子任务平均工具调用数 × 2（重试系数） + 5（缓冲）。比如任务拆了 4 个子任务，每个平均调 2 个工具，那么 422+5=21，实际可以取 15~20 之间；如果任务本身简单，直接定 5~8 就够了。设太大会烧钱，设太小完不成任务，这个参数得多跑几次才能找到你的业务模型的最佳值，不要指望一次调到完美。
4. 实操过程：一个完整 Hermes Agent Loop 的执行链路拆解
前面讲了组件的原理，这一章我带你走一遍完整流程。我拿一个简单的“天气+穿衣建议”任务做例子，不涉及任何敏感或高风险操作，纯粹展示循环的每一轮在内部到底发生了什么。
任务输入：用户说：“帮我查一下明天北京天气怎么样，并给出穿什么衣服的建议。”
系统里配了 3 个工具：get_weather(city, date)、get_holiday(city, date)、get_city_guide(city)。模型走 Hermes Loop，循环结构如下。
4.1 第 0 轮：任务接收与规划
Agent 刚开始运行时，系统把它初始化到一个空的上下文窗口，里面只有：
- system prompt（角色设定、工具描述、循环规则）
- 用户目标
- 相关的长期记忆召回结果（比如如果系统存了“北京这位用户在春天容易花粉过敏”之类的偏好）
然后 Agent 做规划。此时模型输出的内心推理（如果是可见的）可能是：
用户想了解明天北京的天气并得到穿衣建议。我需要先获取天气数据，然后根据天气情况生成穿衣建议。这是一次简单的两步任务，不需要额外拆解。这时 Agent 决定第一轮动作是调用get_weather工具，参数填入{"city": "北京", "date": "明天"}。请注意，在这一步 Agent 没有直接输出穿衣建议，而是选择了先调工具，这就是循环和普通生成式 AI 回复的区别——它会为了搞到真实数据先去“动手”。
4.2 第 1 轮：工具执行与观察
系统收到模型的工具调用指令，执行get_weather("北京", "明天")，返回：
{ "status": "success", "data": { "city": "北京", "date": "2025-06-15", "weather": "晴", "temperature_min": 22, "temperature_max": 31, "humidity": "40%", "wind": "西南风3级" } }执行结果返回之后，系统把这段结果作为“观察”追加到上下文里，同时更新循环的轮次计数，再交给模型进行下一轮推理。到这里第一轮循环算走完了，完整链路就是：推理计划 -> 执行工具 -> 观察结果 -> 进入下一轮。
4.3 第 2 轮：判断信息充分性，生成答案
新的一轮里，模型看到工具返回的天气数据。它开始判断：有了温度、湿度、风力，已经足够回答用户问题了，不需要再调其他工具。于是它生成一段自然语言回答：
明天北京天气晴，最高31℃，最低22℃，西南风3级，湿度40%。建议穿短袖或薄长袖，早晚可以加一件薄外套；紫外线可能较强，注意防晒。这时系统需要做“退出条件判断”：模型给出了最终回答，而且没有继续调用工具的请求，循环走到了终止条件 1（目标达成），于是 Agent 把这段回答包装为最终结果返回给用户。
整个过程一共是 2 轮循环：一轮调工具，一轮输出答案。看起来很简单，但这里有三处细节决定了它能否顺畅跑完全程。
第一处：模型输出格式一致性。模型在生成时可能输出普通文本，也可能输出结构化调用指令。框架必须明确区分这两种输出，用一个可解析的格式约束（比如强制 JSON 输出，包含type: "tool_call"或type: "final_answer"）来分流。我在实现里会做格式校验，一旦解析失败就回到当前轮次重新生成，并且把“解析失败”作为观察结果反馈给模型，让它自行修正。
第二处：工具返回结果过大。真实场景中，工具返回的结果往往远比武器十行 JSON 复杂。比如一次数据库查询可能返回几千行，直接丢进上下文很容易爆窗口。我的策略是预先定义工具的“输出裁剪规则”，比如只保留前 50 行数据，并附上“共 1234 行，展示前 50 行，如需查看更多可调用 next_page 工具”的说明。Agent 如果真的需要更多数据，会自己在下一轮选择翻页。这个设计既保住了上下文，又没有剥夺 Agent 获取完整信息的能力。
第三处：工具调用频率限制。有些 Agent 会在同样一个工具上反复调用，获取完全相同的参数、完全相同的返回结果。我加了一个“同工具同参数指纹查重”，如果模型连续多轮发同一个请求，我就直接复用上一次的返回结果，不再真实执行工具。这既省了外部 API 配额，又防止内部循环。
4.4 多轮任务的路径漂移示例
再举一个复杂一点的例子：用户让 Agent “整理一份关于某行业的投资简报，覆盖市场规模、竞争格局、政策风险三个章节”。这个任务至少涉及 5 次以上工具调用，而且没有固定顺序，Agent 可能先查市场规模，再查竞争格局，中途发现某数据有矛盾，又折回去重新查。
我现在演示一下漂移是怎么发生的：Agent 前两轮已经查好了市场规模数据和竞争格局数据，第三轮它查政策风险，查完发现政策数据里提到的一个规定和市场数据里的某个假设矛盾。于是在第四轮，Agent 不是直接进入“写简报”环节，而是返回到第二步，重新查找相关政策原文来确认矛盾点。这种“折返跳转”就是动态规划的体现，如果当初用的是固定流程线，遇到这种内部矛盾，你只能强制任务失败。
能从矛盾中发现并主动返回修正，靠的就是两条机制：
- 上下文中保留了前几轮的原始数据和推理，模型在后续推理时能够感知到“前后不一致”。
- 循环允许 Agent 在同一轮次后“重新规划”下一步，不被预设顺序捆绑。
所以你还应该关注 Agent Loop 里的一个重要细节：每一步的“动作”不一定总是向外调工具，也可以是“内部推理修正”。在 Hermes Loop 里，我给模型的输出类型里加了一个特殊动作叫update_plan，用于让 Agent 主动调整计划，并把自己调整的原因写出来。这样一方面能提升任务成功率，另一方面让日志可读性更强。
5. 执行中的上下文管理、Token 成本与性能实测
很多人把 Agent 写“活”了之后，第一个撞上的墙就是 Token 开销失控。你从日志看轮次不多，但费用高得吓人。这就要聊上下文管理了，因为上下文大小才是决定 Token 成本的第一因素。
5.1 Token 消耗的数学账
先算一笔账。假设你的系统 prompt 固定是 2000 token，任务每轮推理大约生成 500 token，每轮接收的工具结果平均 800 token。那么跑 10 轮循环的总 Token 消耗不是简单的加法，而是每一轮都重新把“历史所有内容”发给模型：
如果采用全量上下文不压缩的方案，第 10 轮时的上下文约等于：
系统prompt + 会话历史(前9轮的所有推理与观察) + 当前轮新内容越往后，每轮的输入都越来越长，10 轮之后总消耗轻轻松松破 5 万 token。
如果用摘要压缩方案：第 5 轮开始，把第 1~4 轮的完整对话压缩成 300 token 的摘要，以后每轮的历史只带摘要，不带原始数据。同样 10 轮，总消耗可以降到原来的 40% 到 60%。当然，压缩方案有精度损失，模型可能会丢掉一些早期的事实细节，所以要在任务开始时就分清楚哪些内容全程保留，哪些可以压缩。
5.2 长任务中的关键字段保护
长任务与短任务在上下文管理上有本质区别。短任务可以粗暴“保留最近 N 轮”，但长任务（比如 30 轮以上的任务）里，用户需求中可能包含一个非常关键的信息（比如“预算不许超过 5000 元”），这个信息出现在第 2 轮，到第 25 轮时已经被滚动掉了。结果 Agent 在最后制定方案时，做出了一个 8000 元的方案，整个任务失败。
我在 Hermes Loop 里做了一个叫pinned_context的机制。启动循环时，用一个小模型或者规则从用户输入里提取“关键约束字段”，把它们单独放在一个固定区域，全程不参与滑动窗口淘汰。你可以看到这就像在会议室的白板角落里用马克笔写下“预算 5000，不得超支”，无论会议室里后面的讨论多乱多长，这个数字永远钉在那儿。这个机制简单有效，强烈建议在你自己的循环里也实现一个。
具体代码骨架是这样的：
class PinnedContext: def __init__(self, max_entries=8): self.entries = [] self.max_entries = max_entries def add(self, key, value, source_round): self.entries.append({"key": key, "value": value, "source_round": source_round}) def get_pinned_text(self): return "【关键约束，全程保留】" + "；".join( f"{e['key']}: {e['value']}" for e in self.entries )至于怎么提取关键约束，最简单的方法是直接让模型在开始阶段回读一遍用户输入，输出结构化结果：
请提取用户需求中的关键约束，包括：明确数值、禁区（不能做什么）、必须包含的要素。如果没有，输出“无”。5.3 并发与重试里容易踩的性能坑
在线系统里，Agent 循环常常是并发跑的。十个 Agent 任务同时执行，共享一套工具接口，这时有两个隐患：
第一，外部 API 限流。工具调用超速会被限流，表现为“连续失败”。我加了工具级令牌桶限流，让每个 Agent 任务间的工具调用间隔可控，而不仅仅是系统级限流。两者效果差异很大：系统级限流是“一刀切，超过就拒绝”；令牌桶限流是“平滑排队，慢一点但稳定”。
第二，重试风暴。Agent 在工具失败后会重试，多个 Agent 同时重试，瞬间流量雪崩。我给重试加了指数退避：第一次失败等 1 秒，第二次等 2 秒，第三次等 4 秒，最多到 8 秒封顶。这套逻辑在实践中非常管用，虽然不是新技术，但在 Agent 循环里尤其重要，因为 Agent 不像普通请求那样只有一次机会，它会在循环里反复触发同一个工具。
性能实测数据我挑一个你们参考：同一个“行业研究报告”任务，跑 15 轮循环，未压缩上下文方案耗时约 90 秒，Token 消耗约 8 万；用摘要压缩 + pinned_context 方案后，耗时降到 55 秒，Token 消耗约 3.5 万。效果差异主要来自每轮发送的 token 少了，模型推理负担轻了，生成速度自然也变快。这里必须加一句，具体数值跟模型、工具结果大小高度相关，不要直接套结论，但压缩带来的收益方向是一致的。
6. 实操中的常见问题与排查技巧实录
写代码时理论再懂，遇到实际问题照样抓瞎。这一章我把自己在调试 Hermes Loop 时遇到的典型问题整理成表，每条都是踩坑换来的，你对照着排查，能省不少时间。
| 现象 | 根本原因 | 排查步骤 | 解决手法 |
|---|---|---|---|
| Agent 重复调用同一个工具，答非所问 | 上下文里工具结果被压缩丢弃，模型“忘了”自己查过 | 查看日志里最近几轮的 prompt 拼接，检查工具结果是否被压缩 | 工具结果进 pinned_context，或调整压缩策略 |
| 任务没完成就提前输出答案 | 模型的“终止条件”判断过强，在信息不足时过早收敛 | 看这一轮模型输出里有没有 tool_call，没有的话可能是它直接生成了 final_answer | 在 system prompt 里强调“只有确认所有信息齐备后才能输出最终答案”，并降低最终答案生成的优先级 |
| 循环虽少，但 Token 消耗极高 | 工具返回的超大 payload 原封不动进上下文 | 检查工具响应是否做了裁剪或分页处理 | 给工具输出加 max_length / top_k 裁剪，必要时改用分页查询 |
| 任务执行到一半，模型逻辑开始混乱 | 上下文窗口接近上限，早期信息被挤出 | 观察模型的 prompt 拼接长度与截断位置 | 做摘要压缩，或调大上下文窗口，或拆分子任务 |
| 模型输出 JSON 解析失败，循环卡住 | 输出格式约束不严格，模型生成了自然语言穿插 JSON | 检查解析器的容错率，是否能解析 markdown 代码块包裹的 JSON | 在 prompt 里严格定义输出格式，并在解析失败后回灌错误信息让模型自行修正 |
| Agent 工具调用时参数类型错误 | 工具的 JSON Schema 描述不够完整，尤其是 enum 和 format | 查看模型生成的参数，比对 schema 定义 | 完善 schema，增加 enum 约束，必要时在工具描述里写上示例参数 |
6.1 日志里的“信号词”：怎么看出一轮循环是否健康
调试循环最重要的一件事，就是学会读日志。我给 Hermes Loop 的每一轮循环都输出固定的日志字段：round、thinking、action、observation、context_size、cost。在读日志的时候，我关注三个信号：
第一，thinking 的长度。正常的 thinking 应该是在做推理和分析，长度适中；如果 thinking 越来越长但 action 迟迟不出现，说明模型在“空转”，也就是无实质进展地绕圈子。这时候要让它加大行动倾向，在 prompt 里直接强调“不要在思考上重复过多”。
第二，action 是否类型丰富。如果 10 轮里 agent 一直在调用同一个检索工具，说明它没有好好利用其他工具，决策依据太单一。这时回看工具描述措辞，并检查工具顺序是否合理。
第三，observation 里是否出现同一个报错多次。如果某个工具反复报同一个错，说明 Agent 在同一个坑里跌倒多次，或者它根本理解不了错误信息。我会检查错误信息是否足够直观，有的工具 return 空值而不是报错，模型误以为“查无结果”，就会反复查。所以我后来把工具健壮性做了一条硬规矩：凡是没有找到数据的情况，必须明确返回“未找到数据”而不是空数组。
6.2 最难调试的 bug：自洽但错误
Agent 调试中，比报错更头疼的是“自洽但错误”——模型输出的答案逻辑自洽、格式漂亮、步骤齐全，但核心结论是错的。这种问题通常会出现在信息缺失或记忆冲突时。比如某个数据源查不到数据，模型就不声不响地用训练记忆里的常识填补，然后自信地输出。
我用来对抗“自洽但错误”的方法有三个：
- 要求答案附带来源：在最终输出格式里，每一个关键结论后面都必须挂上它来自哪个工具的结果字段。一旦有字段无来源，评判程序直接判失败。
- 容忍度评估：建立输出校验层，用一个小模型或规则系统去“挑刺”。它不会重新执行任务，只是检查结论与观察结果之间是否一致。如果答非所问，就把校验失败信息连同结论一起重新喂回循环，让 Agent 自己再想一版。
- 多路径交叉验证：对于高风险任务，同一件事用两种不同的工具去查证（一个查数据库、一个查文档），对比结果是否一致。不一致时触发额外反思轮。
这三种办法都有效，但都有成本。如果任务价值不高，只做一个“要求附来源”就够了；价值高的任务，三种都上。
6.3 循环里的超时与人为干预熔断
Agent 循环没有“应用崩溃”那么明显的异常，它是默默烧钱。所以必须有熔断干预机制。
我设计了一个“人工接管闸门”：当 Agent 连续多轮没有产生对最终目标有贡献的进展（判定规则可以是“最近 5 轮里没有调用过新工具、没有输出有效结论”），就停止自动循环，把当前状态发给人类操作员处理，并提供一键“终止”或“换方向重跑”的选项。这在没有人类参与的全自动 Agent 系统里不现实，但绝大多数业务场景里，有一个“人在环上”的监管点，整体风险会低非常多。
7. 我自己实现的一版轻量 Hermes Loop 骨架
说了这么多理论，干脆把我实际用过的一个轻量实现骨架丢出来。这个骨架不依赖任何重型 Agent 框架，核心就是用一个大模型 + 工具注册表 + 循环控制逻辑来自己拼。很适合想深度理解 Agent 运行原理的朋友复现。
import json from typing import Callable, Dict, List class ToolRegistry: def __init__(self): self.tools: Dict[str, Callable] = {} def register(self, name: str, schema: dict, func: Callable): self.tools[name] = {"schema": schema, "func": func} def execute(self, name: str, args: dict): tool = self.tools.get(name) if tool is None: return {"error": f"tool {name} not found"} try: return {"result": tool["func"](**args)} except Exception as e: return {"error": str(e)} class HermesLoop: def __init__(self, llm, registry: ToolRegistry, max_iterations: int = 12): self.llm = llm self.registry = registry self.max_iterations = max_iterations self.history: List[dict] = [] def _build_messages(self, user_input: str) -> List[dict]: # 这里可以加入摘要压缩逻辑和 pinned_context messages = [{"role": "system", "content": self.system_prompt}] messages.extend(self.history) messages.append({"role": "user", "content": user_input}) return messages def run(self, user_input: str) -> str: for step in range(self.max_iterations): messages = self._build_messages(user_input) response = self.llm(messages) action = self._parse_action(response) if action["type"] == "final_answer": return action["answer"] if action["type"] == "tool_call": observation = self.registry.execute( action["tool_name"], action["args"] ) self.history.append( { "role": "assistant", "content": json.dumps(action, ensure_ascii=False), } ) self.history.append( { "role": "tool", "content": json.dumps(observation, ensure_ascii=False), } ) return "达到最大迭代次数，任务未能完成，请调整任务描述或扩大上限。" def _parse_action(self, response: str) -> dict: # 在实际项目中我会用 JSON Mode 或者 Function Calling， # 这里直接演示一个解析函数，按输出前缀判断 try: data = json.loads(response) if data.get("type") in ("tool_call", "final_answer"): return data except Exception: pass # 回退策略：当作普通文本输出 return {"type": "final_answer", "answer": response}这版骨架做了精简包装，实际项目中你至少还要补上这些：重试策略、摘要压缩、输出校验、日志与埋点。不过这个骨架已经把 Loop 的骨架讲明白了：循环的每一轮，模型都基于“历史 + 新输入”产生一个动作；动作要么是调工具，要么是结束循环。工具的结果追加为新的观察内容，然后进入下一轮。
我把 System Prompt 的设计也分享一份你直接参考。它直接决定了 Agent 的行为稳定度，比任何复杂代码都重要：
你是一个通过调用工具完成任务的智能助手。你的工作逻辑是循环式的： 1. 分析当前状态，决定下一步是否需要调用工具； 2. 如果需要调用工具，请严格按 JSON 格式输出： {"type": "tool_call", "tool_name": "...", "args": {...}} 3. 如果已经获得足够信息，请直接输出最终答案： {"type": "final_answer", "answer": "..."} 规则：禁止在信息不足时输出最终答案；禁止重复调用参数相同的工具；每个工具调用失败后可以重试，但连续失败 2 次必须换方案。这就是整套 Hermes Loop 实现的灵魂，简单、直接、好维护。你把它跑通之后，再去理解 LangChain 那些 Agent 框架会豁然开朗，因为它们本质上做的事和这段代码一模一样，只不过穿了一层更厚的工业级外衣。
8. 收尾：先让循环“看得见”，再让循环“管得住”
如果你只从这篇里带走一句话，我希望是：AI Agent 的能力上限并不取决于模型多聪明，而取决于你对执行循环的控制力。模型再强，循环失控一样会给你输出胡编乱造的东西；模型稍微弱一点，只要循环的每一步都清晰、可观测、有约束，反而能稳定完成任务。
我在自己项目里反复折腾 Hermes Loop 的这段时间，最大的体会是：一开始总想堆更多能力、更多高级机制，最后发现真正让效果质变的，反而是把那些最基本的东西做扎实——读日志、看每一轮的上下文、把终止条件设好、把工具失败兜底想清楚、让 Agent 知道它自己的“依据是什么”。这就像你在团队里带新人，不指望他聪不聪明，而是先让他养成“每一步都知道自己在干嘛”的习惯，后面再谈创造力。
最后再分享一个小技巧：在调试 Agent 循环的时候，把所有轮次的“输入 token 数”和“输出 token 数”打点记录下来，做成一条曲线。你会发现很多诡异的行为——比如突然变笨、突然变慢、开始绕圈——在看曲线的那一刻全都对上号了：基本上都是上下文起了变化，或者某轮输入里出现了一个异常巨大的工具结果。这个习惯帮我在几次“明明什么都没改，效果却变差”的诡异 bug 里，用最短的时间找到了真凶。
后续如果你想在这个骨架之上继续深入，我建议三个方向：一是做记忆模块的深化，把向量召回和摘要压缩真正做好；二是做工具编排的自动发现与冲突解决，让 Agent 面对几十个工具时依然不乱；三是做多 Agent 协作，在循环之上再加一层任务调度。不过这些都是后话，眼下你先把单 Agent 的循环控制捋顺，底子扎实了，后面所有的扩展都是水到渠成的事。
