Agent Zero 警告消息模板解析fw.warning.md如何把系统警告注入 Agent 历史上下文【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读本文聚焦 Agent ZeroAI 框架prompts/fw.warning.md 这一系统提示模板文件讲解它如何以结构化 JSON 形式把运行时警告写入 Agent 的消息历史从而让大模型在下一次推理时感知异常并自我纠错。读者将掌握该模板的语法、它与fw.error.md、fw.msg_repeat.md等同类模板的协作关系以及hist_add_warning在 agent.py 中的完整调用链与可扩展机制。一、模板是什么一段只有 5 行的 JSON 契约fw.warning.md是 Agent Zero 仓库prompts/目录下的一个系统提示模板文件全文如下{ system_warning: {{message}} }该模板本身不包含任何自然语言指令而是一个占位符驱动的 JSON 结构。运行期{{message}}会被真实的警告文本替换生成形如下方的完整系统消息{ system_warning: You have sent the same message again. You have to do something else! } 这种「模板 占位符」的设计与同目录下其他系统消息模板保持一致的风格例如 [prompts/fw.error.md](https://link.gitcode.com/i/1832ceedd30770687e8dd035591f6ae1) 使用 system_error: {{error}} 表达错误[prompts/fw.intervention.md](https://link.gitcode.com/i/de74f94e06966bcd2c75886b1a5dbbd6)、[prompts/fw.user_message.md](https://link.gitcode.com/i/a3890ac159bf0473c05bb1781bdaa628) 同样以 JSON 结构承载用户/干预消息。可以推断这类模板的共同目标是让系统级事件以**结构化的机器可读字段**system_warning / system_error进入对话历史方便模型区分「用户输入」与「框架系统消息」。 ## 二、谁在消费它hist_add_warning 的调用链 模板的真正消费点在 [agent.py](https://link.gitcode.com/i/3f61ef3745519a853f4a6e4e8945a96b#L770-L773) 的 Agent.hist_add_warning 方法 python extension.extensible def hist_add_warning(self, message: history.MessageContent, id: str ): content self.parse_prompt(fw.warning.md, messagemessage) return self.hist_add_message(False, contentcontent, idid) 关键细节 1. **parse_prompt 负责渲染**[agent.py](https://link.gitcode.com/i/3f61ef3745519a853f4a6e4e8945a96b#L682-L688)它通过 subagents.get_paths(self, prompts) 解析出当前 Agent含子 Agent 配置的 prompts 搜索目录再交给 helpers/files.py 的 parse_file 完成模板渲染与 {{message}} 替换。 2. **hist_add_message(False, ...) 写入历史**False 表示这是「非 AI 消息」即警告被当作系统侧消息追加进 history与用户消息、工具结果并列。 3. **extension.extensible 可被插件拦截**整个方法通过扩展机制暴露插件可以在 hist_add_warning 前后挂接自定义逻辑详见下文扩展点。 ## 三、触发场景源码中的四处典型调用 从 [agent.py](https://link.gitcode.com/i/3f61ef3745519a853f4a6e4e8945a96b) 与插件源码可以确认hist_add_warning 主要在以下场景被触发 | 场景 | 源码位置 | 警告内容来源 | 目的 | |---|---|---|---| | 模型重复输出同一回复 | [agent.py](https://link.gitcode.com/i/3f61ef3745519a853f4a6e4e8945a96b#L494-L511) | [prompts/fw.msg_repeat.md](https://link.gitcode.com/i/68df6396c7489290d93c44d16c337165)You have sent the same message again. You have to do something else! | 打破死循环要求模型换一种方式行动 | | 工具未找到/初始化失败 | [agent.py](https://link.gitcode.com/i/3f61ef3745519a853f4a6e4e8945a96b#L1176-L1187) 与 [agent.py](https://link.gitcode.com/i/3f61ef3745519a853f4a6e4e8945a96b#L1501-L1509) | 动态拼接的 Tool xxx not found or could not be initialized. | 告知模型调用了不存在的工具 | | 消息格式非法无有效工具请求 | [agent.py](https://link.gitcode.com/i/3f61ef3745519a853f4a6e4e8945a96b#L1510-L1518) | [prompts/fw.msg_misformat.md](https://link.gitcode.com/i/35c9d07a706f1208538f2016f9c9a0c5)You have misformatted your message... | 纠正模型的 JSON 输出格式 | | 插件重试机制注入错误信息 | [plugins/_error_retry/extensions/python/_functions/agent/Agent/handle_exception/end/_80_retry_critical_exception.py](https://link.gitcode.com/i/d10fd62eb9f049490f6c11a2db410990) | 异常处理后的 agent-facing 错误文本 | 让模型在重试前理解失败原因 | 以重复消息场景为例[agent.py](https://link.gitcode.com/i/3f61ef3745519a853f4a6e4e8945a96b#L494-L511) 在发现 self.loop_data.last_response agent_response 时先通过 read_prompt(fw.msg_repeat.md) 取回警告文本再调用 hist_add_warning 将其渲染为 system_warning 消息写入历史同时用橙色字体打印到终端并写入 context.logtypewarning实现「历史上下文、终端、日志」三路同步。测试 [tests/test_unusable_response_loop.py](https://link.gitcode.com/i/07da83d443e9c1b4b5c3ca6c47740e11) 正是围绕这套「不可用响应循环」机制设计的验证用例。 ## 四、为什么用 system_warning 字段对模型的可信信号 从工程角度fw.warning.md 体现了 Agent Zero 的一个设计原则**系统警告必须与用户消息在结构上可区分**。 - 如果直接拼接纯文本模型可能把警告误认为用户指令导致行为偏移 - 使用 system_warning 顶级字段后模型可以从 JSON 结构上识别这是框架级反馈与 fw.user_message.md 产生的用户消息、fw.tool_result 产生的工具结果天然隔离 - 模板渲染后仍保留完整的 JSON 包裹~~~json 代码围栏由 helpers/files.py 的 is_full_json_template 识别[files.py](https://link.gitcode.com/i/e9943626b9e2b5a09257cd0baa3ef134)与 [prompts/fw.msg_timeout.md](https://link.gitcode.com/i/150b886b4c87ad0daf39eb2c8e972b92) 这类「完整可执行 JSON 示例」的模板风格统一。 ## 五、扩展机制如何在自己的插件里注入警告 hist_add_warning 被 extension.extensible 标记意味着扩展/插件框架可以在该方法执行前后介入。仓库已有先例[extensions/python/_functions/agent/Agent/handle_exception/end/_50_handle_repairable_exception.py](https://link.gitcode.com/i/70514f97ee1bda09caa9ecd043736cb6) 在异常处理扩展中直接调用 self.agent.hist_add_warning(msg[message])。因此第三方插件开发者在自己的扩展里也可以复用同一入口把自定义警告写入模型可见的历史而不必关心 fw.warning.md 的渲染细节——只需传入 message 文本即可。 ## 六、注意事项与扩展建议 1. **模板路径随 Agent 可覆盖**parse_prompt 通过 subagents.get_paths(self, prompts) 解析目录不同 Agent 配置如 [agents/agent0/agent.yaml](https://link.gitcode.com/i/4e1c24a4de096ba694af3fc073fa854a) 下的 prompts 目录可以拥有自己的模板覆盖实现按 Agent 定制警告措辞。 2. **警告内容建议简短明确**system_warning 每次注入都会占用上下文 token像 fw.msg_repeat.md 那样一句话点明「你重复了请做点别的」比长篇说明更利于模型快速纠偏。 3. **与错误模板分工**fw.warning.mdsystem_warning用于「可恢复的提示」fw.error.mdsystem_error用于「需要被明确感知的错误」实际编写模板时可按严重程度选择对应字段保持语义清晰。 ## 小结 fw.warning.md 虽然只有寥寥数行却是 Agent Zero 自我纠错机制的重要一环它定义了 system_warning 这个结构化字段由 Agent.hist_add_warning[agent.py](https://link.gitcode.com/i/3f61ef3745519a853f4a6e4e8945a96b#L770-L773)统一渲染并写入历史覆盖重复回复、工具缺失、消息格式错误等运行时异常场景。理解它等于理解了 Agent Zero 如何把「系统反馈」与「用户对话」分层管理也为自定义 Agent 与插件扩展提供了可靠的警告注入入口。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考