Agent Zero 重复消息防护机制解析fw.msg_repeat.md 与不可用响应循环检测【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读在 Agent Zero 的自主执行循环中模型偶尔会陷入“原地打转”连续输出与上一条完全相同的消息或工具调用既不推进任务也不返回结果。为了打破这种死循环并控制 API 成本框架在主循环内置了重复响应检测并通过 prompts/fw.msg_repeat.md 这一提示词文件向模型发出警告。本文将以该文件为线索结合 agent.py 主循环、防循环扩展与配套测试完整拆解 Agent Zero 检测、警告、计数直至终止“不可用响应”的整套机制并说明如何通过max_consecutive_unusable_responses配置项进行调优。一、fw.msg_repeat.md 是什么打开 prompts/fw.msg_repeat.md全文只有一句话You have sent the same message again. You have to do something else!它属于框架的fw.*framework提示词族是 Agent Zero 在检测到助手模型重复发送相同消息时注入对话历史中的一段警告文案。它与两个姊妹提示词协同工作prompts/fw.msg_misformat.mdYou have misformatted your message. Follow system prompt instructions on JSON message formatting precisely.用于消息格式不符合约定的场景prompts/fw.msg_unusable_response_limit.mdAgent stopped after {{limit}} consecutive unusable model responses to prevent further API charges. Send a new message to try again.用于连续无效响应达到上限、Agent 被强制停止的场景。这三份文件共同定义了 Agent Zero 对“不可用响应unusable response”的处置策略先警告、再计数、最后止损。二、触发时机主循环中的重复响应检测fw.msg_repeat.md的注入点位于 Agent 主执行循环 agent.py。在模型返回响应后框架会执行一次关键比对if ( self.loop_data.last_response agent_response ): # if assistant_response is the same as last message in history, let him know # Append the assistants response to the history log_item self.loop_data.params_temporary.get(log_item_generating) assistant_message self.hist_add_ai_response( agent_response, idlog_item.id if log_item else , llm_resultllm_result, ) self._remember_llm_result_state(llm_result, assistant_message) # Append warning message to the history warning_msg self.read_prompt(fw.msg_repeat.md) wmsg self.hist_add_warning(messagewarning_msg) PrintStyle(font_colororange, paddingTrue).print(warning_msg) self.context.log.log(typewarning, contentwarning_msg, idwmsg.id)这段代码说明三件事判定条件loop_data.last_response agent_response即本次模型输出与对话历史中最后一条助手消息完全相同。注意该比对发生在工具调用处理之前因此“重复”既包括重复的纯文本响应也包括重复的 JSON 工具调用消息。处置动作重复响应仍会作为助手消息追加进历史hist_add_ai_response随后立刻把警告文本写入历史hist_add_warning让模型在下一轮能看到这条提示。可见性警告以橙色字体打印到终端PrintStyle(font_colororange)并写入上下文日志self.context.log.log(typewarning, ...)便于开发者观察循环发生的位置与频率。这里read_prompt(fw.msg_repeat.md)是框架统一的提示词读取入口支持按 agent profile 覆盖同名文件——这正是 Tiny Local 等子 profile 能够定制恢复指令的原因详见第七节。三、历史注入hist_add_warning 与扩展钩子hist_add_warning将警告以特殊类型追加到会话历史确保模型在下一次推理时能看到“你重复了”的信号。更关键的是它挂接了名为hist_add_warning/end的扩展事件为防循环检测提供了天然切入点。对应的扩展实现位于 extensions/python/_functions/agent/Agent/hist_add_warning/end/_90_stop_unusable_response_loop.py。该文件定义了StopUnusableResponseLoop扩展类其execute方法专门识别两类警告消息if message not in { self.agent.read_prompt(fw.msg_misformat.md), self.agent.read_prompt(fw.msg_repeat.md), }: return也就是说只有当历史中新增的警告是“格式错误”或“重复消息”时扩展才会启动计数逻辑其他类型的历史写入不会干扰状态。由于扩展通过hist_add_warning/end事件在每次警告注入后触发它与主循环的重复检测形成了天然串联检测 → 注入警告 → 扩展计数。四、状态机连续不可用响应的计数与止损扩展的计数逻辑围绕一个持久化状态键_unusable_response_failures展开存放在loop_data.params_persistent跨迭代持久参数中迭代绑定记录iteration与count。若本次迭代与上次记录的迭代相同直接返回避免同一轮重复计数。连续性判定若当前迭代号恰为上次迭代号 1则计数累加否则视为中断计数重置为 1。这保证了只有“连续”的不可用响应才会计入上限。达到上限当count limit时读取fw.msg_unusable_response_limit.md模板中的{{limit}}会被实际上限值替换写入 warning 日志并抛出HandledException中止当前执行循环stop_message self.agent.read_prompt(fw.msg_unusable_response_limit.md, limitlimit) self.agent.context.log.log(typewarning, contentstop_message) data[exception] HandledException(stop_message)HandledException定义于 helpers/errors.py是框架内部“已处理异常”会在不产生堆栈噪声的情况下优雅地终止本轮 Agent 执行避免继续产生 API 调用费用。用户只需发送一条新消息即可重新开始。五、配置项max_consecutive_unusable_responses连续不可用响应的上限由设置项max_consecutive_unusable_responses控制其在 helpers/settings.py 中的定义与约束如下默认值get_default_value(max_consecutive_unusable_responses, 5)即默认连续 5 次无效响应后停止helpers/settings.py最小值钳制normalize_settings中执行max(1, copy[max_consecutive_unusable_responses])helpers/settings.py即设置 0 或负数也会被归一化为至少 1确保防护始终有效类型声明settings 模型中将该字段声明为inthelpers/settings.py。该配置在 WebUI 中可直接调整设置面板组件 webui/components/settings/agent/agent.html 通过x-model.number$store.settings.settings.max_consecutive_unusable_responses将其绑定为数字输入框。调大该值适合容忍模型偶发抖动、更注重任务连续性的场景调小则更激进地止损适合对成本敏感或对稳定性要求高的场景。六、测试验证行为契约有据可查这套机制并非孤立的运行时行为而是有完整测试保障的公开契约。tests/test_unusable_response_loop.py 覆盖了三条核心断言达到上限即停止模拟连续 3 次不可用响应max_consecutive_unusable_responses3第三次时扩展正确抛出HandledException计数为 3并记录stopped at 3的 warning 日志非连续响应重置窗口中间穿插一次结构化正常消息后计数重置为 1不会误触上限默认值与 UI 绑定默认上限为 5normalize_settings将 0 归一化为 1且 WebUI 的 agent 设置面板确实绑定了该字段fw.msg_unusable_response_limit.md文案中包含 “after 3 consecutive” 的模板说明。此外tests/test_default_prompt_budget.py 专门校验 Tiny Local profile 的提示词预算确认其定制的fw.msg_repeat.md中包含 “Your repeated JSON was recorded, but it did not execute another tool.” 与 “replace it with the next real tool call” 等恢复指令防止子 profile 的提示词膨胀导致默认提示预算超限。这说明框架对提示词文件同样存在预算管控。七、Profile 定制Tiny Local 的扩展版警告默认的fw.msg_repeat.md只有一句话而 Tiny Local本地小模型 profile提供了更详细的恢复指导位于 agents/tiny-local/prompts/fw.msg_repeat.md。其核心内容面向 JSON 工具调用协议要求模型在重复被拒后不再发送相同的 JSON 对象若工作未完成调用下一个真实工具若上一条response未完成任务替换为下一步工具调用若文件写入/补丁已成功改为读取文件或报告观察结果若命令已执行检查其输出或运行下一个不同命令仅当确实无其他动作可做时才用response简要说明阻塞点最终只输出一个包含tool_name与tool_args的 JSON 对象不带任何散文或 markdown。根据 agents/tiny-local/AGENTS.md 的约定该文件“拥有”Tiny Local 在框架拒绝重复助手消息时的 profile 专属恢复指令。这展示了 Agent Zero 提示词体系的分层设计同一逻辑信号fw.msg_repeat.md在不同模型 profile 下可注入不同强度的引导普通模型收到简短警告能力较弱的小模型则获得逐步恢复清单。八、机制全貌小结将上述环节串联起来Agent Zero 的重复消息防护是一条完整的闭环主循环检测 (agent.py: last_response agent_response) ↓ 注入 fw.msg_repeat.md 警告 (hist_add_warning, 橙色打印 warning 日志) ↓ 扩展事件 hist_add_warning/end 触发计数 (_90_stop_unusable_response_loop.py) ↓ 连续计数达到 max_consecutive_unusable_responses (默认 5, 最小 1) ↓ 注入 fw.msg_unusable_response_limit.md 并抛出 HandledException 停止执行 ↓ 用户发送新消息后重新开始这套机制的价值在于它以极小的提示词文件为枢纽串联了主循环状态比对、扩展事件系统、持久化迭代状态、设置归一化与 WebUI 配置最终以优雅异常终止本轮执行防止模型重复输出同一条消息造成 API 费用空转。对于希望深入理解 Agent Zero 自恢复与自防护能力的开发者agent.py、_90_stop_unusable_response_loop.py、helpers/settings.py 与 tests/test_unusable_response_loop.py 四份文件构成了最直接的阅读路径。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考