Agent Zero message_loop_start 扩展点深度解析消息循环迭代计数与生命周期状态管理【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读message_loop_start是 Agent Zero AI framework 中负责消息循环每次迭代开始时的后端生命周期扩展点。它运行在 Agent 主循环monologue → message loop的每一轮迭代起点承担迭代计数器维护与后续循环起始状态装配的职责。读完本文你将掌握该扩展点的调用时机与代码位置、内置IterationNo扩展的计数实现与读取 API、扩展文件命名排序规则与覆盖机制以及如何基于此扩展点编写自己的循环级钩子。一、扩展点定位一次 monologue 里的循环骨架在 Agent Zero 中Agent 处理用户消息的核心入口是Agent.monologue()agent.py。每次 monologue 会进入一个内层while True消息循环循环每转一圈就代表一次模型调用回合iteration# agent.py简化自 monologue 主循环 while True: self.context.streaming_agent self # 标记当前流式输出者 self.loop_data.iteration 1 # 迭代计数自增 self.loop_data.params_temporary {} # 清空临时参数 last_response_stream_full # call message_loop_start extensions await extension.call_extensions_async( message_loop_start, self, loop_dataself.loop_data ) await self.handle_intervention() # 处理干预消息 ...从源码结构可以看到 LoopData 中iteration字段初始为-1循环每次迭代先 1随后立即调用message_loop_start扩展点。因此执行时机每轮消息循环迭代的最开头iteration自增之后、handle_intervention之前执行频率随消息循环迭代反复触发多轮工具调用、多轮回复都会触发而monologue_start只在新一轮 monologue 开始时触发一次传入参数loop_dataLoopData 实例携带iteration、system、user_message、history_output、protocol_temporary、extras_persistent等字段以及 Agent 自身实例。作为对比monologue_start扩展点位于外层循环agent.py负责 monologue 起始设置message_loop_end扩展点位于每轮迭代的收尾如历史组织与持久化。message_loop_start正好处于两者之间——每一轮迭代的起跑线。二、内置实现IterationNo迭代计数扩展扩展点目录 extensions/python/message_loop_start/ 内唯一的 Python 实现是_10_iteration_no.py其完整代码如下from helpers.extension import Extension from agent import Agent, LoopData DATA_NAME_ITER_NO iteration_no class IterationNo(Extension): async def execute(self, loop_data: LoopData LoopData(), **kwargs): if not self.agent: return # total iteration number no self.agent.get_data(DATA_NAME_ITER_NO) or 0 self.agent.set_data(DATA_NAME_ITER_NO, no 1) def get_iter_no(agent: Agent) - int: return agent.get_data(DATA_NAME_ITER_NO) or 0其工作逻辑非常简洁防御性判空if not self.agent: return。根据 skills/a0-development/references/extensions.md 的说明self.agent在启动或非 Agent 钩子场景下可能为None因此扩展必须自行兜底读取-自增-写回通过agent.get_data(iteration_no)读取当前值不存在时按0处理加 1 后通过agent.set_data(iteration_no, no 1)写回。数据存储在 Agent 的data字典中agent.py 中get_data/set_data的实现导出读取辅助函数get_iter_no(agent)供其他模块随时查询当前总迭代次数。注意与 LoopData.iteration 的区别LoopData.iteration是当次 monologue 内的回合计数monologue 结束即归零重建而iteration_no存放在 Agent 数据层是一个跨 monologue 持续累加的全局回合号。两者配合可分别表达本轮对话进行到第几回合与该 Agent 累计处理了多少回合。计数的确定性与作用域约束AGENTS.md 的 Local Contracts 明确了三条硬性约定正是IterationNo设计的直接体现保持每轮计数确定性、且作用域限定在当前激活的上下文active context内iteration_no存在 Agent 自身的data字典中天然随 Agent 上下文存在不会跨 Agent 串扰不得重置 monologue 级钩子monologue-level hooks所拥有的状态monologue_start系的扩展负责 monologue 起点装配message_loop_start不应清空它们写入的状态二者职责边界清晰循环起始状态变更需与日志logging、流式输出streaming与进程链process-chain行为协调这也是 Work Guidance 中特别强调的——在迭代最前端改动状态会影响整个后续 LLM 调用、流式回调与process_chain_end等收尾逻辑。三、调用链与扩展机制从装饰器到钩子分发message_loop_start的触发走的是 Agent Zero 统一的后端扩展分发链路helpers/extension.py入口agent.py中extension.call_extensions_async(message_loop_start, self, loop_dataself.loop_data)类发现call_extensions_async→_get_extension_classes(extension_point, agent, ...)通过subagents.get_paths(agent, extensions/python, extension_point)在所有 Agent 路径下寻找extensions/python/message_loop_start/目录helpers/extension.py类加载_get_extensions(folder)用modules.load_classes_from_folder加载目录下所有继承自Extension的类helpers/extension.py去重与排序_get_extension_classes按模块文件名去重首个出现的文件名优先实现覆盖机制再按文件名排序helpers/extension.py执行call_extensions_async实例化每个扩展类并await cls(agentagent).execute(**kwargs)同步/异步由返回类型判定helpers/extension.py。文件名排序规则扩展文件按文件名含数字前缀字典序执行_10_iteration_no.py中_10_前缀使其排在较前位置——迭代计数先自增后续扩展即可读取到本轮正确的计数值排序由 helpers/extension.py 中sorted(unique.values(), keylambda cls: _get_file_from_module(cls.__module__))保证数字前缀建议留出间隔如_10_、_20_、_45_、_50_方便未来扩展插入中间这一约定同样记录在 skills/a0-development/references/extensions.md 的 Ordering And Overrides 一节。扩展点的多来源布局同一个扩展点目录可以出现在多个位置发现时按路径优先级合并位置用途extensions/python/message_loop_start/框架内置扩展如_10_iteration_no.pyplugins/plugin/extensions/python/message_loop_start/插件捆绑的扩展usr/plugins/plugin/extensions/python/message_loop_start/用户安装插件的扩展usr/extensions/python/message_loop_start/独立用户扩展长期功能建议封装为插件同名文件按搜索优先级首个出现者生效从而支持框架级/插件级/用户级的覆盖。四、实战示例插件如何挂接 message_loop_start除内置的IterationNo外仓库中的 Telegram 集成插件提供了第二个真实用例plugins/_telegram_integration/extensions/python/message_loop_start/_45_telegram_draft_start.py。from agent import LoopData from helpers.extension import Extension from plugins._telegram_integration.helpers.constants import CTX_TG_BOT class TelegramDraftStart(Extension): async def execute(self, loop_data: LoopData LoopData(), **kwargs): if not self.agent or self.agent.number ! 0: return context self.agent.context if not context.data.get(CTX_TG_BOT): return from plugins._telegram_integration.helpers import draft_stream, heartbeat await draft_stream.start(context) await heartbeat.start(context)该示例展示了几个值得借鉴的写法作用域收窄self.agent.number ! 0限定仅主 AgentA0生效context.data.get(CTX_TG_BOT)进一步判断是否处于 Telegram 会话上下文延迟导入在execute内部才import插件辅助模块符合 extensions/python/AGENTS.md 中扩展模块应保持轻量导入import-light因为很多钩子运行在热路径上的约定每轮启动外围服务在每轮迭代开始时启动 Telegram 草稿流与心跳与 plugins/_telegram_integration/README.md 中初始化 Telegram 响应流式输出的描述一致。五、与相邻扩展点的协同关系message_loop_start处于 monologue 内循环的最前端理解它与相邻扩展点的时序关系才能正确设计状态读写扩展点触发时机职责示例monologue_start每轮 monologue 开始一次核心 monologue 起始装配extensions/python/monologue_start/AGENTS.mdmessage_loop_start每次消息循环迭代开始多次迭代计数、循环起始状态本文主题before_main_llm_call每次主模型调用前模型调用前行为agent.pymessage_loop_prompts_before/after提示词构造前后提示词协议装配、工作目录 extras、当前时间、已加载技能注入如 extensions/python/message_loop_prompts_after/_60_include_current_datetime.pymessage_loop_end每次迭代收尾历史组织与后台压缩extensions/python/message_loop_end/_10_organize_history.py、聊天持久化_90_save_chat.py从 agent.py 的主循环代码可确认完整顺序iteration 1→message_loop_start→handle_intervention→prepare_prompt→before_main_llm_call→ 流式 LLM 调用reasoning_stream_chunk/response_stream_chunk→ 迭代收尾。若你的扩展需要在提示词组装前为loop_data注入状态message_loop_start就是正确的位置而_90_save_chat.py之类的持久化逻辑则必须等待迭代结束才执行。六、验证与测试指引AGENTS.md 的 Verification 要求是改动后对多轮对话进行冒烟测试smoke-test multi-turn conversations。原因在于该扩展点涉及迭代计数与状态装配多轮工具调用/多轮回复场景下最容易暴露计数错乱、状态残留或与 monologue 级钩子冲突等问题。仓库测试目录 tests/ 中包含大量生命周期相关测试如 test_chat_compaction.py、test_history_compression_wait.py验证历史组织与持久化行为时可参考。验证要点归纳多轮对话连续多轮用户消息确认iteration_no跨 monologue 持续累加、不归零多工具回合单轮 monologue 内多次工具调用确认LoopData.iteration逐回合自增、message_loop_start每回合都触发状态边界确认扩展写入的状态不会破坏monologue_start装配的数据也不会被message_loop_end的清理由逻辑误删扩展排序新增扩展时保持数字前缀间隔确认执行顺序符合预期。结语message_loop_start虽小却是 Agent Zero 消息循环生命周期中最靠前的钩子之一内置的IterationNo用它完成了跨对话的迭代计数Telegram 插件用它驱动每轮的外围服务启动。理解它的触发时机、数据作用域与排序覆盖规则是在 Agent Zero 中编写健壮、可预测的后端扩展的必修课。所有相关证据均可在 extensions/python/message_loop_start/、helpers/extension.py 与 agent.py 中直接查阅。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero message_loop_start 扩展点深度解析：消息循环迭代计数与生命周期状态管理
Agent Zero message_loop_start 扩展点深度解析消息循环迭代计数与生命周期状态管理【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读message_loop_start是 Agent Zero AI framework 中负责消息循环每次迭代开始时的后端生命周期扩展点。它运行在 Agent 主循环monologue → message loop的每一轮迭代起点承担迭代计数器维护与后续循环起始状态装配的职责。读完本文你将掌握该扩展点的调用时机与代码位置、内置IterationNo扩展的计数实现与读取 API、扩展文件命名排序规则与覆盖机制以及如何基于此扩展点编写自己的循环级钩子。一、扩展点定位一次 monologue 里的循环骨架在 Agent Zero 中Agent 处理用户消息的核心入口是Agent.monologue()agent.py。每次 monologue 会进入一个内层while True消息循环循环每转一圈就代表一次模型调用回合iteration# agent.py简化自 monologue 主循环 while True: self.context.streaming_agent self # 标记当前流式输出者 self.loop_data.iteration 1 # 迭代计数自增 self.loop_data.params_temporary {} # 清空临时参数 last_response_stream_full # call message_loop_start extensions await extension.call_extensions_async( message_loop_start, self, loop_dataself.loop_data ) await self.handle_intervention() # 处理干预消息 ...从源码结构可以看到 LoopData 中iteration字段初始为-1循环每次迭代先 1随后立即调用message_loop_start扩展点。因此执行时机每轮消息循环迭代的最开头iteration自增之后、handle_intervention之前执行频率随消息循环迭代反复触发多轮工具调用、多轮回复都会触发而monologue_start只在新一轮 monologue 开始时触发一次传入参数loop_dataLoopData 实例携带iteration、system、user_message、history_output、protocol_temporary、extras_persistent等字段以及 Agent 自身实例。作为对比monologue_start扩展点位于外层循环agent.py负责 monologue 起始设置message_loop_end扩展点位于每轮迭代的收尾如历史组织与持久化。message_loop_start正好处于两者之间——每一轮迭代的起跑线。二、内置实现IterationNo迭代计数扩展扩展点目录 extensions/python/message_loop_start/ 内唯一的 Python 实现是_10_iteration_no.py其完整代码如下from helpers.extension import Extension from agent import Agent, LoopData DATA_NAME_ITER_NO iteration_no class IterationNo(Extension): async def execute(self, loop_data: LoopData LoopData(), **kwargs): if not self.agent: return # total iteration number no self.agent.get_data(DATA_NAME_ITER_NO) or 0 self.agent.set_data(DATA_NAME_ITER_NO, no 1) def get_iter_no(agent: Agent) - int: return agent.get_data(DATA_NAME_ITER_NO) or 0其工作逻辑非常简洁防御性判空if not self.agent: return。根据 skills/a0-development/references/extensions.md 的说明self.agent在启动或非 Agent 钩子场景下可能为None因此扩展必须自行兜底读取-自增-写回通过agent.get_data(iteration_no)读取当前值不存在时按0处理加 1 后通过agent.set_data(iteration_no, no 1)写回。数据存储在 Agent 的data字典中agent.py 中get_data/set_data的实现导出读取辅助函数get_iter_no(agent)供其他模块随时查询当前总迭代次数。注意与 LoopData.iteration 的区别LoopData.iteration是当次 monologue 内的回合计数monologue 结束即归零重建而iteration_no存放在 Agent 数据层是一个跨 monologue 持续累加的全局回合号。两者配合可分别表达本轮对话进行到第几回合与该 Agent 累计处理了多少回合。计数的确定性与作用域约束AGENTS.md 的 Local Contracts 明确了三条硬性约定正是IterationNo设计的直接体现保持每轮计数确定性、且作用域限定在当前激活的上下文active context内iteration_no存在 Agent 自身的data字典中天然随 Agent 上下文存在不会跨 Agent 串扰不得重置 monologue 级钩子monologue-level hooks所拥有的状态monologue_start系的扩展负责 monologue 起点装配message_loop_start不应清空它们写入的状态二者职责边界清晰循环起始状态变更需与日志logging、流式输出streaming与进程链process-chain行为协调这也是 Work Guidance 中特别强调的——在迭代最前端改动状态会影响整个后续 LLM 调用、流式回调与process_chain_end等收尾逻辑。三、调用链与扩展机制从装饰器到钩子分发message_loop_start的触发走的是 Agent Zero 统一的后端扩展分发链路helpers/extension.py入口agent.py中extension.call_extensions_async(message_loop_start, self, loop_dataself.loop_data)类发现call_extensions_async→_get_extension_classes(extension_point, agent, ...)通过subagents.get_paths(agent, extensions/python, extension_point)在所有 Agent 路径下寻找extensions/python/message_loop_start/目录helpers/extension.py类加载_get_extensions(folder)用modules.load_classes_from_folder加载目录下所有继承自Extension的类helpers/extension.py去重与排序_get_extension_classes按模块文件名去重首个出现的文件名优先实现覆盖机制再按文件名排序helpers/extension.py执行call_extensions_async实例化每个扩展类并await cls(agentagent).execute(**kwargs)同步/异步由返回类型判定helpers/extension.py。文件名排序规则扩展文件按文件名含数字前缀字典序执行_10_iteration_no.py中_10_前缀使其排在较前位置——迭代计数先自增后续扩展即可读取到本轮正确的计数值排序由 helpers/extension.py 中sorted(unique.values(), keylambda cls: _get_file_from_module(cls.__module__))保证数字前缀建议留出间隔如_10_、_20_、_45_、_50_方便未来扩展插入中间这一约定同样记录在 skills/a0-development/references/extensions.md 的 Ordering And Overrides 一节。扩展点的多来源布局同一个扩展点目录可以出现在多个位置发现时按路径优先级合并位置用途extensions/python/message_loop_start/框架内置扩展如_10_iteration_no.pyplugins/plugin/extensions/python/message_loop_start/插件捆绑的扩展usr/plugins/plugin/extensions/python/message_loop_start/用户安装插件的扩展usr/extensions/python/message_loop_start/独立用户扩展长期功能建议封装为插件同名文件按搜索优先级首个出现者生效从而支持框架级/插件级/用户级的覆盖。四、实战示例插件如何挂接 message_loop_start除内置的IterationNo外仓库中的 Telegram 集成插件提供了第二个真实用例plugins/_telegram_integration/extensions/python/message_loop_start/_45_telegram_draft_start.py。from agent import LoopData from helpers.extension import Extension from plugins._telegram_integration.helpers.constants import CTX_TG_BOT class TelegramDraftStart(Extension): async def execute(self, loop_data: LoopData LoopData(), **kwargs): if not self.agent or self.agent.number ! 0: return context self.agent.context if not context.data.get(CTX_TG_BOT): return from plugins._telegram_integration.helpers import draft_stream, heartbeat await draft_stream.start(context) await heartbeat.start(context)该示例展示了几个值得借鉴的写法作用域收窄self.agent.number ! 0限定仅主 AgentA0生效context.data.get(CTX_TG_BOT)进一步判断是否处于 Telegram 会话上下文延迟导入在execute内部才import插件辅助模块符合 extensions/python/AGENTS.md 中扩展模块应保持轻量导入import-light因为很多钩子运行在热路径上的约定每轮启动外围服务在每轮迭代开始时启动 Telegram 草稿流与心跳与 plugins/_telegram_integration/README.md 中初始化 Telegram 响应流式输出的描述一致。五、与相邻扩展点的协同关系message_loop_start处于 monologue 内循环的最前端理解它与相邻扩展点的时序关系才能正确设计状态读写扩展点触发时机职责示例monologue_start每轮 monologue 开始一次核心 monologue 起始装配extensions/python/monologue_start/AGENTS.mdmessage_loop_start每次消息循环迭代开始多次迭代计数、循环起始状态本文主题before_main_llm_call每次主模型调用前模型调用前行为agent.pymessage_loop_prompts_before/after提示词构造前后提示词协议装配、工作目录 extras、当前时间、已加载技能注入如 extensions/python/message_loop_prompts_after/_60_include_current_datetime.pymessage_loop_end每次迭代收尾历史组织与后台压缩extensions/python/message_loop_end/_10_organize_history.py、聊天持久化_90_save_chat.py从 agent.py 的主循环代码可确认完整顺序iteration 1→message_loop_start→handle_intervention→prepare_prompt→before_main_llm_call→ 流式 LLM 调用reasoning_stream_chunk/response_stream_chunk→ 迭代收尾。若你的扩展需要在提示词组装前为loop_data注入状态message_loop_start就是正确的位置而_90_save_chat.py之类的持久化逻辑则必须等待迭代结束才执行。六、验证与测试指引AGENTS.md 的 Verification 要求是改动后对多轮对话进行冒烟测试smoke-test multi-turn conversations。原因在于该扩展点涉及迭代计数与状态装配多轮工具调用/多轮回复场景下最容易暴露计数错乱、状态残留或与 monologue 级钩子冲突等问题。仓库测试目录 tests/ 中包含大量生命周期相关测试如 test_chat_compaction.py、test_history_compression_wait.py验证历史组织与持久化行为时可参考。验证要点归纳多轮对话连续多轮用户消息确认iteration_no跨 monologue 持续累加、不归零多工具回合单轮 monologue 内多次工具调用确认LoopData.iteration逐回合自增、message_loop_start每回合都触发状态边界确认扩展写入的状态不会破坏monologue_start装配的数据也不会被message_loop_end的清理由逻辑误删扩展排序新增扩展时保持数字前缀间隔确认执行顺序符合预期。结语message_loop_start虽小却是 Agent Zero 消息循环生命周期中最靠前的钩子之一内置的IterationNo用它完成了跨对话的迭代计数Telegram 插件用它驱动每轮的外围服务启动。理解它的触发时机、数据作用域与排序覆盖规则是在 Agent Zero 中编写健壮、可预测的后端扩展的必修课。所有相关证据均可在 extensions/python/message_loop_start/、helpers/extension.py 与 agent.py 中直接查阅。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考