Agent Zero 用户无响应处理协议解析 fw.msg_timeout 框架消息与自动续跑机制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读在 Agent Zero AI 框架的自主运行循环中用户不可能始终在线回复每一条中间消息因此框架内置了一套「用户无响应timeout」处理协议。本文以框架消息 prompts/fw.msg_timeout.md 为切入点逐条解读这套协议的行为约定与标准 JSON 响应格式并结合 agent.py、helpers/files.py 等核心源码剖析框架消息framework message的加载、占位符渲染与 JSON 模板处理机制以及 nudge、wait 等相邻功能如何构成完整的等待-唤醒-续跑闭环。读完本文你将掌握 Agent Zero 中框架消息的设计哲学、task_done 工具的正确用法以及如何在自定义 Agent Profile 中覆写这类行为提示。一、fw.msg_timeout 是什么框架消息在 Agent Zero 中的角色Agent Zero 的prompts/目录下存放着大量fw.*.md文件如fw.msg_repeat.md、fw.msg_misformat.md、fw.msg_unusable_response_limit.md、fw.msg_truncated.md、fw.msg_summary.md、fw.user_message.md等。这些文件统称为框架消息framework messages它们是框架自身在特定运行时事件发生时注入到 Agent 对话历史或系统提示中的标准指令模板用于引导 Agent 以统一、可预期的行为响应各类边界情况。fw.msg_timeout.md正是其中之一它描述的场景是Agent 向用户发送了一条消息或发起了需要用户确认的交互但用户在预期时间内没有响应。此时框架将这条消息内容注入对话告知 Agent 应当如何处理等待落空的局面避免 Agent 陷入死等或空转。全文仅有 17 行属于高度凝练的行为协议# User is not responding to your message. If you have a task in progress, continue on your own. If you dont have a task, use the task_done tool with text argument. # Example ~~~json { thoughts: [ Theres no more work for me, I will ask for another task, ], headline: Completing task and requesting next assignment, tool_name: task_done, tool_args: { text: I have no more work, please tell me if you need anything., } } ~~~从源码结构看这类提示文件由 Agent 的 read_prompt 方法 读取作为框架与 LLM 之间的带外约定其设计意图是把用户缺席视为正常运行时状态而不是异常——Agent 应当自主决策、继续推进而不是挂起等待。二、协议逐条解读两条规则与一个前提2.1 前提用户不再响应消息开头User is not responding to your message.是触发前提的声明向 Agent 明确当前状态上一条发往用户的消息没有得到回应。在 Agent Zero 中用户与 Agent 的交互可以来自多种渠道——终端输入、WebUI、nudge API、连接器插件 等——而框架消息所约定的行为对所有渠道一致。2.2 规则一有任务在身继续自主执行If you have a task in progress, continue on your own.是这条协议的第一优先规则。Agent Zero 的定位是自主运行的 Agent 框架其主循环见 agent.py 中monologue循环设计为尽可能无人值守地推进任务。因此当用户未响应时如果 Agent 手头仍有未完成的子任务、未执行完的工具调用序列或明确的待办目标它应当继续执行而不是停下来等待这与框架中 nudge 的语义互补——nudge 用于用户主动唤醒而 timeout 消息用于用户缺席时自主续跑。2.3 规则二无任务在身用 task_done 收尾If you dont have a task, use the task_done tool with text argument.是第二优先规则也是本协议的关键动作指令task_done是一个收尾型工具用于声明当前没有更多工作可做并请求新的任务分配它必须携带text 参数用以说明当前状态例如我没有更多工作如需帮助请告诉我与 response 工具break_loopTrue结束主循环并把消息交付给用户不同task_done 的语义是面向任务队列的完结——Agent 主动让出执行权等待下一个任务输入。这两条规则构成一个完备的分支有活干活没活交差保证 Agent 在用户缺席的任何时刻都能落在确定的状态机节点上。三、标准响应格式JSON 消息模板的实战示例协议附带一个完整的示例展示了 Agent 在收到该框架消息后应当输出的标准 JSON 响应。该格式与 Agent Zero 全框架统一的thoughts / headline / tool_name / tool_args四段式工具调用契约一致可对照 prompts/agent.system.tools_vision.md 中vision_load工具的示例验证同一结构{ thoughts: [ Theres no more work for me, I will ask for another task, ], headline: Completing task and requesting next assignment, tool_name: task_done, tool_args: { text: I have no more work, please tell me if you need anything., } }字段含义与实战要点字段含义本场景写法建议thoughts内部推理过程数组可多条说明无剩余工作、主动请求新任务的推理headline面向日志/UI 的一句话摘要如 Completing task and requesting next assignmenttool_name要调用的工具名本场景固定为task_donetool_args工具参数必须包含text字符串参数需要说明的是task_done是框架消息层约定暴露的收尾动作名其语义与框架中break_loop机制工具返回Response(break_loopTrue)后结束当前消息循环见 tools/response.py同属终止当前执行的范畴但前者强调请求下一任务后者强调把最终答复交付用户。四、源码级解析框架消息是如何被加载与渲染的要理解fw.msg_timeout.md如何真正生效需要追查它的加载链路。核心入口是 agent.py 的read_prompt方法extension.extensible def read_prompt(self, file: str, **kwargs) - str: dirs subagents.get_paths(self, prompts) prompt files.read_prompt_file(file, _directoriesdirs, _agentself, **kwargs) if files.is_full_json_template(prompt): prompt files.remove_code_fences(prompt) return prompt要点有三可扩展extensibleread_prompt带有extension.extensible装饰器意味着插件体系可以在读取前后注入处理逻辑框架消息的行为可以被插件定制目录解析通过 subagents.get_paths 得到当前 Agent 的 prompts 搜索目录列表包含内置prompts/与 Agent Profile 的prompts/再由 helpers/files.py 的 read_prompt_file 完成文件查找与读取——这允许 Profile 用同名文件覆写核心框架消息JSON 模板识别若文件整体是一个 JSON 模板is_full_json_template读取后会剥离代码围栏remove_code_fences使模板可以被直接解析。在 read_prompt_file 内部还依次完成了占位符替换replace_placeholders_text将{{variable}}替换为 kwargs 传入值、条件求值evaluate_text_conditions以及include 指令处理process_includes支持§§include(file)复用其他模板片段。这意味着fw.msg_timeout.md这类消息模板天然支持参数化——例如类似 fw.wait_complete.md 中Wait complete. Reached {{target_time}}.的动态注入方式。由此可以推断fw.msg_timeout.md若在未来需要携带更多上下文如等待时长、剩余子任务列表框架无需改动代码只需在模板中新增{{placeholder}}并在调用处传参即可这正是框架消息机制的扩展性设计。五、超时场景的完整生态nudge、wait 与 interventionfw.msg_timeout.md并非孤立存在它与 Agent Zero 中一系列等待与唤醒机制共同构成闭环5.1 nudge用户主动唤醒 Agent当 Agent 因等待用户而暂停时用户可通过多种途径唤醒它后端 API api/nudge.py 调用context.nudge()集成命令/nudge见 helpers/integration_commands.py 中的_handle_nudge连接器插件端点 plugins/_a0_connector/api/v1/nudge.py。其核心实现位于 agent.py 的 nudge 方法extension.extensible def nudge(self): self.kill_process() self.paused False self.task self.communicate(UserMessage(self.agent0.read_prompt(fw.msg_nudge.md))) return self.task它先终止旧进程、解除暂停再向 Agent 注入 fw.msg_nudge.md内容为{system_message: Nudged - continue}从而让 Agent 继续。nudge 与 fw.msg_timeout 的方向正好相反nudge 是用户回来了继续干timeout 消息是用户没回来自己看着办。5.2 wait 工具与 managed_wait受管理的等待wait 工具 允许 Agent 主动暂停直到指定时长或时间戳支持seconds/minutes/hours/days/until参数对应工具说明见 prompts/agent.system.tool.wait.md。其底层 managed_wait 在等待循环中周期性调用agent.handle_intervention()以响应暂停/干预并会在干预导致等待中断时自动延长目标时间保证实际等待时长不缩水。等待结束后Agent 收到 fw.wait_complete.mdWait complete. Reached {{target_time}}.通知继续执行。这条链路说明Agent Zero 中的等用户是有管理、可打断、可恢复的而fw.msg_timeout.md处理的正是等不到用户的最终落点。5.3 intervention 与 paused执行循环的中断机制Agent 的执行循环中大量调用 handle_intervention它检查self.intervention字段当用户消息到达且进程存活时communicate 方法消息会以广播形式写入当前 Agent 及其上级 Agent 的intervention随后通过InterventionException打断正在进行的 LLM 调用与工具执行。等待用户与用户缺席正是围绕这套中断机制的两侧行为。六、相邻框架消息速览timeout 在框架消息家族中的定位将fw.msg_timeout.md与其同族消息对比可以更清晰地定位它在框架运行策略中的角色框架消息触发场景核心指令fw.msg_timeout.md用户未响应消息有任务继续无任务用task_done请求新任务fw.msg_nudge.md用户主动唤醒暂停的 AgentNudged - continue恢复执行fw.msg_repeat.mdAgent 输出了与历史完全相同的响应You have sent the same message again. You have to do something else!fw.msg_misformat.mdAgent 消息不符合 JSON 格式规范严格按系统提示的 JSON 消息格式重发fw.msg_unusable_response_limit.md连续 N 次不可用响应触达上限停止以防止继续产生 API 费用等待新消息重试fw.msg_truncated.md长文本超出阈值用{{length}} CHARACTERS REMOVED TO SAVE SPACE占位符截断配合 helpers/messages.py 的 truncate_textfw.msg_summary.md上下文压缩以 JSON 形式输出messages_summary配合 helpers/history.py 的compress_attentionfw.notify_user.notification_sent.mdnotify_user 工具成功发送通知告知 Agent 通知已送达用户工具实现见 tools/notify_user.py可以看出fw.msg_timeout属于运行时状态提示类框架消息与fw.msg_nudge配对出现一个管唤醒续跑一个管缺席自治共同保证 Agent 在异步人机协作中永不僵死。七、实践指南如何观察与定制这套行为7.1 观察触发路径fw.msg_timeout.md所在的 prompts/ 目录是框架消息的权威来源当前仓库的搜索结果显示该文件目前由框架运行时按需注入fw.*前缀消息统一通过 read_prompt / parse_prompt 加载。开发者可在自己的集成中于等待用户回复的超时分支里注入该消息内容从而让 Agent 遵循有任务继续、无任务 task_done的协议。7.2 在自定义 Agent Profile 中覆写根据 agents/AGENTS.md 的说明每个 Agent Profile如 agents/default、agents/developer 等拥有自己的prompts/目录且 Profile 内的同名提示文件会按目录搜索顺序优先于核心 prompts 被加载这与read_prompt_file的目录列表机制一致。因此若希望某个 Profile 对用户无响应采取不同的措辞或补充额外约束例如继续执行前先汇报当前进度只需在对应 Profile 的prompts/下放置一个同名fw.msg_timeout.md即可无需改动核心代码。参考 agents/_example 了解 Profile 的标准目录布局。7.3 注意点task_done的text参数是必填的示例中给出的文案I have no more work, please tell me if you need anything.可直接复用或按需改写响应必须保持标准的四段式 JSON 结构否则会触发 fw.msg_misformat.md 所描述的格式纠错流程本文所涉行为均为框架消息层面的协议约定具体触发时机取决于上层调用方CLI、WebUI、连接器如何检测用户超时仓库中可参考 helpers/timed_input.py 的timeout_input基于inputimeout实现带超时的输入理解 CLI 场景下的超时来源。结语fw.msg_timeout.md虽不足 20 行却是 Agent Zero 自主运行哲学的一个缩影框架不要求用户全程在线而是通过约定的框架消息把用户缺席转化为 Agent 的确定性决策分支——有任务则自主续跑无任务则通过 task_done 主动让位。理解它也就理解了 Agent Zero 框架消息机制模板化、可覆写、可参数化、可扩展的基本运转方式以及它在整个等待-唤醒-续跑生态中的位置。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/15 18:35:55 · 阅读 1.2k Agent Zero 用户无响应处理协议：解析 fw.msg_timeout 框架消息与自动续跑机制
Agent Zero 用户无响应处理协议解析 fw.msg_timeout 框架消息与自动续跑机制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读在 Agent Zero AI 框架的自主运行循环中用户不可能始终在线回复每一条中间消息因此框架内置了一套「用户无响应timeout」处理协议。本文以框架消息 prompts/fw.msg_timeout.md 为切入点逐条解读这套协议的行为约定与标准 JSON 响应格式并结合 agent.py、helpers/files.py 等核心源码剖析框架消息framework message的加载、占位符渲染与 JSON 模板处理机制以及 nudge、wait 等相邻功能如何构成完整的等待-唤醒-续跑闭环。读完本文你将掌握 Agent Zero 中框架消息的设计哲学、task_done 工具的正确用法以及如何在自定义 Agent Profile 中覆写这类行为提示。一、fw.msg_timeout 是什么框架消息在 Agent Zero 中的角色Agent Zero 的prompts/目录下存放着大量fw.*.md文件如fw.msg_repeat.md、fw.msg_misformat.md、fw.msg_unusable_response_limit.md、fw.msg_truncated.md、fw.msg_summary.md、fw.user_message.md等。这些文件统称为框架消息framework messages它们是框架自身在特定运行时事件发生时注入到 Agent 对话历史或系统提示中的标准指令模板用于引导 Agent 以统一、可预期的行为响应各类边界情况。fw.msg_timeout.md正是其中之一它描述的场景是Agent 向用户发送了一条消息或发起了需要用户确认的交互但用户在预期时间内没有响应。此时框架将这条消息内容注入对话告知 Agent 应当如何处理等待落空的局面避免 Agent 陷入死等或空转。全文仅有 17 行属于高度凝练的行为协议# User is not responding to your message. If you have a task in progress, continue on your own. If you dont have a task, use the task_done tool with text argument. # Example ~~~json { thoughts: [ Theres no more work for me, I will ask for another task, ], headline: Completing task and requesting next assignment, tool_name: task_done, tool_args: { text: I have no more work, please tell me if you need anything., } } ~~~从源码结构看这类提示文件由 Agent 的 read_prompt 方法 读取作为框架与 LLM 之间的带外约定其设计意图是把用户缺席视为正常运行时状态而不是异常——Agent 应当自主决策、继续推进而不是挂起等待。二、协议逐条解读两条规则与一个前提2.1 前提用户不再响应消息开头User is not responding to your message.是触发前提的声明向 Agent 明确当前状态上一条发往用户的消息没有得到回应。在 Agent Zero 中用户与 Agent 的交互可以来自多种渠道——终端输入、WebUI、nudge API、连接器插件 等——而框架消息所约定的行为对所有渠道一致。2.2 规则一有任务在身继续自主执行If you have a task in progress, continue on your own.是这条协议的第一优先规则。Agent Zero 的定位是自主运行的 Agent 框架其主循环见 agent.py 中monologue循环设计为尽可能无人值守地推进任务。因此当用户未响应时如果 Agent 手头仍有未完成的子任务、未执行完的工具调用序列或明确的待办目标它应当继续执行而不是停下来等待这与框架中 nudge 的语义互补——nudge 用于用户主动唤醒而 timeout 消息用于用户缺席时自主续跑。2.3 规则二无任务在身用 task_done 收尾If you dont have a task, use the task_done tool with text argument.是第二优先规则也是本协议的关键动作指令task_done是一个收尾型工具用于声明当前没有更多工作可做并请求新的任务分配它必须携带text 参数用以说明当前状态例如我没有更多工作如需帮助请告诉我与 response 工具break_loopTrue结束主循环并把消息交付给用户不同task_done 的语义是面向任务队列的完结——Agent 主动让出执行权等待下一个任务输入。这两条规则构成一个完备的分支有活干活没活交差保证 Agent 在用户缺席的任何时刻都能落在确定的状态机节点上。三、标准响应格式JSON 消息模板的实战示例协议附带一个完整的示例展示了 Agent 在收到该框架消息后应当输出的标准 JSON 响应。该格式与 Agent Zero 全框架统一的thoughts / headline / tool_name / tool_args四段式工具调用契约一致可对照 prompts/agent.system.tools_vision.md 中vision_load工具的示例验证同一结构{ thoughts: [ Theres no more work for me, I will ask for another task, ], headline: Completing task and requesting next assignment, tool_name: task_done, tool_args: { text: I have no more work, please tell me if you need anything., } }字段含义与实战要点字段含义本场景写法建议thoughts内部推理过程数组可多条说明无剩余工作、主动请求新任务的推理headline面向日志/UI 的一句话摘要如 Completing task and requesting next assignmenttool_name要调用的工具名本场景固定为task_donetool_args工具参数必须包含text字符串参数需要说明的是task_done是框架消息层约定暴露的收尾动作名其语义与框架中break_loop机制工具返回Response(break_loopTrue)后结束当前消息循环见 tools/response.py同属终止当前执行的范畴但前者强调请求下一任务后者强调把最终答复交付用户。四、源码级解析框架消息是如何被加载与渲染的要理解fw.msg_timeout.md如何真正生效需要追查它的加载链路。核心入口是 agent.py 的read_prompt方法extension.extensible def read_prompt(self, file: str, **kwargs) - str: dirs subagents.get_paths(self, prompts) prompt files.read_prompt_file(file, _directoriesdirs, _agentself, **kwargs) if files.is_full_json_template(prompt): prompt files.remove_code_fences(prompt) return prompt要点有三可扩展extensibleread_prompt带有extension.extensible装饰器意味着插件体系可以在读取前后注入处理逻辑框架消息的行为可以被插件定制目录解析通过 subagents.get_paths 得到当前 Agent 的 prompts 搜索目录列表包含内置prompts/与 Agent Profile 的prompts/再由 helpers/files.py 的 read_prompt_file 完成文件查找与读取——这允许 Profile 用同名文件覆写核心框架消息JSON 模板识别若文件整体是一个 JSON 模板is_full_json_template读取后会剥离代码围栏remove_code_fences使模板可以被直接解析。在 read_prompt_file 内部还依次完成了占位符替换replace_placeholders_text将{{variable}}替换为 kwargs 传入值、条件求值evaluate_text_conditions以及include 指令处理process_includes支持§§include(file)复用其他模板片段。这意味着fw.msg_timeout.md这类消息模板天然支持参数化——例如类似 fw.wait_complete.md 中Wait complete. Reached {{target_time}}.的动态注入方式。由此可以推断fw.msg_timeout.md若在未来需要携带更多上下文如等待时长、剩余子任务列表框架无需改动代码只需在模板中新增{{placeholder}}并在调用处传参即可这正是框架消息机制的扩展性设计。五、超时场景的完整生态nudge、wait 与 interventionfw.msg_timeout.md并非孤立存在它与 Agent Zero 中一系列等待与唤醒机制共同构成闭环5.1 nudge用户主动唤醒 Agent当 Agent 因等待用户而暂停时用户可通过多种途径唤醒它后端 API api/nudge.py 调用context.nudge()集成命令/nudge见 helpers/integration_commands.py 中的_handle_nudge连接器插件端点 plugins/_a0_connector/api/v1/nudge.py。其核心实现位于 agent.py 的 nudge 方法extension.extensible def nudge(self): self.kill_process() self.paused False self.task self.communicate(UserMessage(self.agent0.read_prompt(fw.msg_nudge.md))) return self.task它先终止旧进程、解除暂停再向 Agent 注入 fw.msg_nudge.md内容为{system_message: Nudged - continue}从而让 Agent 继续。nudge 与 fw.msg_timeout 的方向正好相反nudge 是用户回来了继续干timeout 消息是用户没回来自己看着办。5.2 wait 工具与 managed_wait受管理的等待wait 工具 允许 Agent 主动暂停直到指定时长或时间戳支持seconds/minutes/hours/days/until参数对应工具说明见 prompts/agent.system.tool.wait.md。其底层 managed_wait 在等待循环中周期性调用agent.handle_intervention()以响应暂停/干预并会在干预导致等待中断时自动延长目标时间保证实际等待时长不缩水。等待结束后Agent 收到 fw.wait_complete.mdWait complete. Reached {{target_time}}.通知继续执行。这条链路说明Agent Zero 中的等用户是有管理、可打断、可恢复的而fw.msg_timeout.md处理的正是等不到用户的最终落点。5.3 intervention 与 paused执行循环的中断机制Agent 的执行循环中大量调用 handle_intervention它检查self.intervention字段当用户消息到达且进程存活时communicate 方法消息会以广播形式写入当前 Agent 及其上级 Agent 的intervention随后通过InterventionException打断正在进行的 LLM 调用与工具执行。等待用户与用户缺席正是围绕这套中断机制的两侧行为。六、相邻框架消息速览timeout 在框架消息家族中的定位将fw.msg_timeout.md与其同族消息对比可以更清晰地定位它在框架运行策略中的角色框架消息触发场景核心指令fw.msg_timeout.md用户未响应消息有任务继续无任务用task_done请求新任务fw.msg_nudge.md用户主动唤醒暂停的 AgentNudged - continue恢复执行fw.msg_repeat.mdAgent 输出了与历史完全相同的响应You have sent the same message again. You have to do something else!fw.msg_misformat.mdAgent 消息不符合 JSON 格式规范严格按系统提示的 JSON 消息格式重发fw.msg_unusable_response_limit.md连续 N 次不可用响应触达上限停止以防止继续产生 API 费用等待新消息重试fw.msg_truncated.md长文本超出阈值用{{length}} CHARACTERS REMOVED TO SAVE SPACE占位符截断配合 helpers/messages.py 的 truncate_textfw.msg_summary.md上下文压缩以 JSON 形式输出messages_summary配合 helpers/history.py 的compress_attentionfw.notify_user.notification_sent.mdnotify_user 工具成功发送通知告知 Agent 通知已送达用户工具实现见 tools/notify_user.py可以看出fw.msg_timeout属于运行时状态提示类框架消息与fw.msg_nudge配对出现一个管唤醒续跑一个管缺席自治共同保证 Agent 在异步人机协作中永不僵死。七、实践指南如何观察与定制这套行为7.1 观察触发路径fw.msg_timeout.md所在的 prompts/ 目录是框架消息的权威来源当前仓库的搜索结果显示该文件目前由框架运行时按需注入fw.*前缀消息统一通过 read_prompt / parse_prompt 加载。开发者可在自己的集成中于等待用户回复的超时分支里注入该消息内容从而让 Agent 遵循有任务继续、无任务 task_done的协议。7.2 在自定义 Agent Profile 中覆写根据 agents/AGENTS.md 的说明每个 Agent Profile如 agents/default、agents/developer 等拥有自己的prompts/目录且 Profile 内的同名提示文件会按目录搜索顺序优先于核心 prompts 被加载这与read_prompt_file的目录列表机制一致。因此若希望某个 Profile 对用户无响应采取不同的措辞或补充额外约束例如继续执行前先汇报当前进度只需在对应 Profile 的prompts/下放置一个同名fw.msg_timeout.md即可无需改动核心代码。参考 agents/_example 了解 Profile 的标准目录布局。7.3 注意点task_done的text参数是必填的示例中给出的文案I have no more work, please tell me if you need anything.可直接复用或按需改写响应必须保持标准的四段式 JSON 结构否则会触发 fw.msg_misformat.md 所描述的格式纠错流程本文所涉行为均为框架消息层面的协议约定具体触发时机取决于上层调用方CLI、WebUI、连接器如何检测用户超时仓库中可参考 helpers/timed_input.py 的timeout_input基于inputimeout实现带超时的输入理解 CLI 场景下的超时来源。结语fw.msg_timeout.md虽不足 20 行却是 Agent Zero 自主运行哲学的一个缩影框架不要求用户全程在线而是通过约定的框架消息把用户缺席转化为 Agent 的确定性决策分支——有任务则自主续跑无任务则通过 task_done 主动让位。理解它也就理解了 Agent Zero 框架消息机制模板化、可覆写、可参数化、可扩展的基本运转方式以及它在整个等待-唤醒-续跑生态中的位置。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考