Hermes Agent Loop拆解：大模型多步任务的稳定执行框架

做 AIAgent 的都知道，执行过程中最让人头疼的不是“模型不够聪明”，而是“模型跑起来了但你不知道它在干嘛”。我最近把一个叫 Hermes Agent Loop 的参考实现翻来覆去拆了一遍，它本质上就是一个很典型的 Agent 迭代执行框架，核心就是把“感知、推理、行动、反思”这四个环节串成一个稳定循环，让大模型不再是单次问答，而是真正能连续处理多步骤任务。这篇文章我想把这套 Loop 从输入到输出、从模块到代码、从故障到优化完整拆开讲，适合正在做 Agent 编排、想把 ReAct 或者 Plan-and-Execute 落地成工程实现的朋友，也适合那些被“Agent 跑飞了”“上下文爆了”折腾过的人。

1. 整体执行链：一次完整的 Hermes Loop 是怎么走完的

先别急着看代码。理解 Hermes Agent Loop 最有效的方式，是把一次完整的任务当成一条流水线来看：任务进来，经过解析，进入循环，循环内部做多轮决策，最后在某个条件满足时退出。这个链条看起来简单，但每一个环节都有大量细节决定成败。

1.1 输入解析与目标分解：一切从任务开始

Loop 并不是直接从第一个模型调用开始的，前面还藏着一个容易被忽略的阶段：输入解析与目标分解。原始任务进来之后，框架先要做三件事：把自然语言任务拆成机器可执行的目标结构、识别约束条件、生成初始执行计划。

比如说用户丢进来一句“帮我查一下最近三个月某产品的用户反馈，并总结成问题清单”。如果直接把这句话扔进循环，模型很可能第一轮就不知道怎么下手。Hermes Loop 的做法是先让规划模块生成一个目标树：

• 主目标：整理近三个月该产品的用户反馈并输出问题清单
• 子目标 1：确定“最近三个月”的时间范围和数据来源
• 子目标 2：拉取用户反馈数据，按渠道聚合
• 子目标 3：对反馈做分类和问题提取
• 子目标 4：生成最终报告

这一步的目的很明确：给后面的循环一个“导航图”。没有这一步，Agent 每一轮都要自己重新理解任务，既浪费 token，又容易在不同意图之间摇摆。

实际工程里，这个阶段还会顺带做一些校验：任务是否包含可执行指令、是否缺少必要参数、权限是否满足、是否需要向用户追问。把这些前置判断放在 Loop 外面而不是循环里面，能明显降低循环内部的分支复杂度。我见过不少团队把“追问澄清”也塞进主循环，结果 Agent 在“确认意向”和“执行动作”之间反复横跳，循环轮次暴涨。

1.2 循环的五段链路：观察、推理、行动、结果回流、再判定

进入循环之后，Hermes Agent Loop 按五段链路反复运转。我把这五段拆开讲，因为它们各自承担的角色完全不同。

第一段是观察。Agent 从环境中采集当前状态，包括前一动作的执行结果、外部数据源的新数据、记忆系统里最近更新的信息。这一段经常被新手跳过，但他们很快会发现，没有这一段，模型就只能依赖自身参数记忆，无法感知真实世界的变化。

第二段是推理。模型把观察到的信息放进上下文，结合当前目标进行思考。这里的“思考”不是聊天式的感想，而是结构化推理：当前进展如何、距离目标还差什么、下一步做什么、选哪个工具。Hermes Loop 会要求推理结果以特定格式输出，比如 JSON 块包含thought和plan字段，确保后续动作生成有据可依。

第三段是行动。根据推理结果调用具体工具，可能是搜索、代码执行、数据库查询、HTTP 请求、文件读写等。这段要特别注意：动作生成必须带上完整参数，而且参数格式要能被外部工具直接消费，不能指望工具端去猜。

第四段是结果回流。工具执行完毕后，返回值会写回上下文，同时被记入记忆模块。回流的数据要做归一化处理，比如截断过长结果、提取摘要、标记来源和置信度，避免后续推理被原始噪声淹没。

第五段是再判定。决策模块检查当前状态是否已经达成目标，或者是否达到退出条件。如果未完成，就带着新观察回到第一段；如果完成或超出限制，就生成最终输出并退出循环。

这五段合起来，才是完整的 Hermes Loop。你可以把它类比成一个人做饭的流程：看了一眼冰箱（观察），决定做番茄炒蛋（推理），打开冰箱拿番茄（行动），发现番茄坏了（结果回流），换方案改成鸡蛋炒饭（再判定），然后继续循环。Agent 和人的差别在于，它每跑一轮都有确定性成本，所以循环设计的第一原则不是“让它多跑”，而是“让它每跑一步都有增量价值”。

2. 核心模块拆解：让 Loop 真正转起来的组件

把 Loop 比作发动机的话，光有循环节流阀还不够，还得有规划器、记忆、工具调度、终止判断这些核心部件协同工作。模块之间职责清晰，循环才能稳定。下面逐个拆。

2.1 规划器：动态调整的执行路线图

规划器并非只在任务开始时执行一次。静态规划的最大问题在于：环境会变，工具结果会不符合预期，前一步的假设很快失效。Hermes Loop 采用动态规划机制：初始计划生成后，每一轮推理都会检查计划是否需要修订。

实际实现里，规划器通常维护一个执行队列。队列元素包含目标名称、预期产出、依赖关系、完成状态。某一轮发现某个子目标无法达成时，规划器不是死磕原计划，而是把该子目标标记为失败，重新分配替代路径。比如前面说的“番茄坏了”场景，规划器会立即把“取番茄”任务标记为受阻，把“用鸡蛋替代”加入队列。

有一个参数很关键：重规划触发的频率阈值。过低会导致 Agent 频繁改计划、原地打转；过高则会让它抱着错误方向硬跑。我们的经验是，只有当连续两轮执行结果都不满足预期，或者明确收到外部错误信号时，才触发重规划。单轮结果不好不一定代表计划错误，可能只是偶发的工具波动。

2.2 记忆系统：短期上下文与长期存储的配合

记忆是 Agent Loop 最容易出问题的地方。Hermes Agent Loop 把记忆分成两层：短期上下文和长期存储。

短期上下文是每次模型调用时直接拼进 prompt 的内容，包括当前轮次的观察、最近的行动轨迹、目标描述。它的优点是模型访问准确、无需检索；缺点是长度有限，拼接越多 token 成本越贵，还容易让模型注意力涣散。

长期存储则负责跨轮次保存信息，包括历史状态、关键结论、偏好设定、外部知识片段。它在每轮推理之前做一次检索，把和当前目标相关的记忆取出来注入上下文。

这里有一个反直觉的经验：把“全部历史”塞进上下文一定会坏事。模型在长上下文里经常丢失早期关键信息，出现所谓的“中间遗忘”现象。所以 Hermes Loop 在每轮结束时会做一轮记忆压缩：把本轮最重要的结论抽成结构化摘要，旧细节删除或降权。这样短期上下文始终保持在一个可管理的规模，长期存储则持续累积高价值信息。

2.3 工具调用与参数生成

工具调用这块，我用四个字概括：格式先行。Hermes Agent Loop 要求所有工具定义采用统一的函数描述格式，包括工具名、入参 schema、返回值规范和错误码。模型生成的不是自由文本命令，而是在工具 schema 约束下生成结构化的调用参数。

这个设计解决了一个核心痛点：LLM 是概率模型，直接输出自然语言命令很容易漏参数。比如说调用一个搜索工具，模型可能只给了 query 字段，漏了 time_range。但如果把工具定义成 JSON Schema，并在 prompt 里给出字段约束和示例，模型生成参数的准确率会显著提升。

我的建议是，每个工具调用都要过一个参数校验层，不通过就返回“参数缺失”或“参数类型错误”，让 Agent 自行修正。不要指望模型一次生成完全正确的参数，而是要把错误回流给模型，让它在下一次推理中学会修正。这比在代码里硬解析模型输出要稳得多。

还有一个细节：工具结果要统一包装。无论底层工具返回的是 JSON、Markdown 还是纯文本，Hermes Loop 都会在回流前封装成一个标准化 Result 对象，包含状态、数据、长度、错误信息。这样能保证后续推理模块看到的永远是结构一致的数据，不会因为某个工具返回格式诡异而崩掉整个 Loop。

2.4 反思与终止条件

反思机制不是让 Agent“反思人生”，而是让它对最近一轮的执行结果做自我校验：行动是否真的完成了目标？结果是否可信？是否存在更好的路径？Hermes Loop 把反思结果作为下一轮推理的输入之一，帮助模型纠正自己的错误。

但反思机制有个双刃剑效应：过度反思会让 Agent 陷入自我怀疑，反复修改已经正确的计划。所以我们一般要求反思模块输出明确的“继续/停止/转向”结论，而不是开放式的“我觉得可能还有问题”。任何没有具体指向的反思，都应该被视为噪声处理。

终止条件则是 Loop 的刹车片。绝对不能只依赖 LLM 的自我判断。Hermes Agent Loop 在工程实现上强制设置三重终止保险：目标完成检测、最大轮次限制、停滞检测。停滞检测专门处理那种模型每轮都输出差不多内容、但一直不退出循环的情况，它通过比较最近几轮状态向量是否有效变化来判定。关于这部分参数怎么设，我放到后面实操部分详细说。

3. 从 0 到 1 落地 Hermes Loop：代码实现与关键参数

理论拆完，真正动手才是最刺激的。这里我给出一个比较精简但结构完整的 Hermes Loop 实现骨架，同时把状态机、停止条件、工具调用这些关键代码逐一说明。

3.1 循环骨架与状态机管理

我习惯把 Agent 循环实现成一个显式的状态机，而不是散落的while加if。原因很简单：状态机让每一轮的可观察状态清晰可见，方便日志、追踪、恢复和测试。下面这段是一个可以直接跑的示例：

from dataclasses import dataclass from typing import Any, Optional import json @dataclass class AgentState: task: str step: int status: str # observing / reasoning / acting / reflecting / done context: list[dict] # 每轮观察和结论 final_answer: Optional[str] = None last_error: Optional[str] = None class HermesLoop: def __init__(self, llm, tools, max_steps=6, max_tokens_per_step=1200): self.llm = llm self.tools = {t.name: t for t in tools} self.max_steps = max_steps self.max_tokens_per_step = max_tokens_per_step def run(self, task: str) -> AgentState: state = AgentState(task=task, step=0, status="observing", context=[]) while state.status != "done" and state.step < self.max_steps: state.step += 1 state = self.iterate(state) self.log_round(state) return state def iterate(self, state: AgentState) -> AgentState: # 1. observing：把最近一轮结果写入上下文 state.status = "observing" state.context.append({"round": state.step, "event": "observe", "data": self.current_observation(state)}) # 2. reasoning：让 LLM 输出结构化的推理与计划 state.status = "reasoning" reasoning = self.llm.chat( self.build_prompt(state), max_tokens=self.max_tokens_per_step, response_format={"type": "json_object"} ) thinking = json.loads(reasoning) state.context.append({"round": state.step, "event": "reason", "data": thinking}) # 3. acting：如果规划器认为需要行动 state.status = "acting" if "tool_call" in thinking: result = self.execute_tool(thinking["tool_call"]) state.context.append({"round": state.step, "event": "action_result", "data": result}) # 4. reflecting：自我校验这轮是否有效 state.status = "reflecting" verdict = self.reflect(state) if verdict.get("done"): state.status = "done" state.final_answer = verdict.get("answer", "") return state def execute_tool(self, call: dict) -> Any: tool = self.tools.get(call.get("name")) if not tool: return {"error": "tool_not_found", "message": f"{call.get('name')} is not registered"} try: validated_args = tool.validate(call.get("arguments", {})) return tool.run(**validated_args) except Exception as e: return {"error": "tool_exception", "message": str(e)}

这段代码体现了几个关键取舍。第一，context是显式累加的，每轮观察、推理、行动结果都记录在案，方便回溯和 debug。第二，工具执行被try-except包裹，异常不会让整个 Loop 崩溃，而是回流成错误信息给模型，让模型自行纠偏。第三，循环入口做了最大步数限制，这是硬性保险。

3.2 停止条件、轮次控制与成本预算

停止条件是所有 Agent 项目里最容易被低估的参数组。很多人只设一个max_steps，结果要么任务没完成就退出，要么 Agent 傻跑十几轮烧光预算。Hermes Loop 的工程实现里，我建议按三层来设置。

第一层是目标完成检测。模型每轮反思时输出done和answer字段，认定任务完成。但这里有个坑：模型可能误报完成，把中间结果当成最终答案。所以不能光看done字段，还要配一个完成度评分，比如要求模型同时输出confidence和evidence，只有置信度高于阈值且证据字段非空时才算真的完成。

第二层是停滞检测。比较最近三轮的动作结果，如果三轮之间没有产生有效变化——比如每次都是同一个搜索请求、返回同样的结果——就强制触发退出，并返回“当前进展受阻”的状态给上层调用方。这个检测不需要太复杂，计算一下 action 字符串的相似度即可。

第三层是成本预算。不是所有团队都有明确的 token 监控体系，但 Agent 一旦上生产，token 账单会涨得非常快。我强烈建议在初始化时同时传入max_total_tokens和max_steps，并在每轮结束后累加实际消费 token，超过预算立刻终止。下面这段可以加在iterate里：

def should_stop_by_cost(self, state: AgentState) -> bool: spent = sum(r.get("tokens", 0) for r in state.context if r["event"] == "reason") return spent >= self.total_token_budget

轮次控制还有一个心法：优先用更少的轮次完成任务，而不是让 Agent 尽情探索。每多加一轮，不仅是多一次模型调用，还会增加上下文长度、推理漂移概率和整体延迟。我们在调参时一般遵循“先定最小可用轮次，再逐步放宽”的原则。比如先设max_steps=4，跑一批测试任务看看完成率，如果完成率低于 80%，再提升到 6，同时观察停滞检测的触发率。

技术方案里还有一个我非常推崇的实践：把每一步的输入输出落成结构化日志，尤其是保存{round, event, data, tokens, latency}这种 JSON 行。这样出了问题才能回放整条决策链，而不是对着空白报错干瞪眼。前面代码里的self.log_round(state)就是这个作用。具体日志字段可以这样设计：

{ "round": 2, "event": "acting", "tool": "http_request", "args": {"url": "https://api.example.com/v1/items", "method": "GET"}, "result_status": "ok", "latency_ms": 832, "tokens": 412 }

4. 现场故障排查与执行链路优化实录

拆完架构、跑通代码，真正等你的是什么？是一堆奇奇怪怪的线上问题。我把这几年做 Agent 执行链踩过的问题整理成一张速查表，再补几个只有在实战中才能体会到的优化经验。

4.1 常见故障速查表

这个表不是凭空列的，每一项都是实际踩过坑后总结出来的。比如第一项“反复执行同一个工具调用”，我刚上手 Agent 项目时几乎天天遇到，模型会把一个失败请求原样重试三四次，每次烧掉几千 token。后来加了动作相似度比较，情况才好转。

4.2 让执行链路更稳的六个经验

经验一：永远让工具结果带状态。工具返回不能只有数据，还要有status、error_code、duration_ms。因为 Agent 在做决策时，需要知道“动作是否成功”，而不仅仅是“返回了什么内容”。一个搜索接口可能返回空列表，但它可能只是因为超时，这时状态字段会帮助模型判断是重试还是换关键词。

经验二：初始计划要轻，动态规划要快。不要让规划器在第一步就生成一个 20 步的超长计划，计划越长越容易在第二三步就作废。初始计划只需要到子目标粒度，后面的路径留给每一轮推理去探索。这样做的好处是模型不用背太多远期计划，短期记忆压力小，执行也更灵活。

经验三：反馈回路要加衰减系数。Agent 在自我反思时会把上一轮的失败结果作为输入，但如果失败结果权重太高，模型会过度悲观，频繁更改方向。我习惯在 prompt 里给反思模块加上一句约束：“仅当连续两轮出现同类型错误时才调整计划”，这能把无谓转向压掉一半以上。

经验四：对工具做幂等保护。特别是涉及写操作的 API，比如发送通知、写数据库、调用支付接口，Agent 一旦重复调用就可能产生重复订单或重复写入。解决方案是在工具层面对相同参数加上幂等键，服务端或者本地拦截重复执行。这个不是 Loop 本身的事，但它决定了 Loop 是否敢把工具调度交给模型。

经验五：在 prompt 里给“不知道”留一条退路。很多循环卡死是因为模型不肯承认自己缺少信息，硬编一个结果出来。我在 Hermes Loop 的 prompt 里明确写了这条规则：“如果你无法获取某个关键信息，请输出request_info动作，而不是猜测。”这让模型在面对不确定信息时有了一个安全的出口，而不是钻牛角尖。

经验六：评估不是看单轮准确性，而是看整条链路的任务完成率。跑 Agent Loop 的时候，评估粒度要从传统模型的“单次回答正确率”转成“任务级完成率”。我平时会准备一组包含 50 条任务的测评集，每条任务都标记正确路径、关键节点、可接受的最终答案形式。然后统计三个指标：任务完成率、平均轮次、平均 token 消耗。这三个指标一起看，才能判断一次 Loop 优化到底是赚是亏。

说一个我最近踩过的例子。有一次为了降低 token 消耗，我把每轮推理的max_tokens从 1500 减到 600，结果平均轮次从 5 涨到 9，总消耗反而增加了 30%。原因很简单：模型在短 token 空间里无法完成有效推理，只能产出低质量中间结论，然后不得不用更多轮次去补救。这个经历给我一个教训：参数优化永远要看全局链路，单点压成本往往适得其反。

在 Hermes Agent Loop 的工程化过程中，我最深的一点体会是：这个架构真正值钱的部分，不是某个特定模型或某个花哨工具，而是它把不确定的 LLM 行为约束在了一个可观测、可控制、可修复的流程框架里。你给模型越多的结构化约束，它越能稳定输出高质量结果；你给它越大的自由发挥空间，就越需要更强的刹车和护栏。所以接下来如果你要自己搭 Agent 执行链，我建议先从最小闭环开始，跑通之后再一层层加规划器、记忆压缩、反思机制、成本控制。每一个模块都拆开做独立测试，再放回整条链路观察变化。这样不管后面遇到什么诡异的线上问题，你至少能定位到是循环里哪一环出了岔子，而不是对着一个黑盒手足无措。