尧图网站建设 
Agent Zero wait 工具深度解析让 AI Agent 学会「等一等」的正确姿势【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 为自主 Agent 提供了一套内置工具集其中wait工具负责让 Agent 在任务执行过程中暂停到指定时长或指定时间点。本文基于 prompts/agent.system.tool.wait.md 的官方工具指令结合 tools/wait.py、helpers/wait.py 的源码实现完整讲解wait工具的 5 个参数、两种等待模式、底层执行机制与干预处理流程帮助你理解并正确驱动 Agent 完成时间敏感型任务。工具定位什么时候该用 waitAgent Zero 是自主运行的多步骤 AI 框架其 Agent 在一个思考—调用工具—接收结果的循环中持续推进任务。绝大多数场景下Agent 应该连续执行但存在两类任务天然需要时间暂停轮询与探测类任务等待文件生成、等待服务端口就绪、等待外部 API 数据到达需要隔一段时间后再检查定时与调度类任务任务要求在某个具体时刻如明早 8 点触发动作。官方工具指令prompts/agent.system.tool.wait.md对wait的定位描述非常克制pause until a duration or timestamp use only when waiting is actually part of the task即只有在等待本身就是任务必要环节时才使用 wait。Agent 不应把 wait 当作无意义的拖延手段也不应代替任务调度器Agent Zero 中定时任务由scheduler工具负责可参考 tools/scheduler.py。这一约束写进了工具提示词是 Agent 行为规范的一部分。wait 工具参数详解wait接受两类参数二者互斥要么指定持续时间seconds/minutes/hours/days中的任意组合要么指定绝对时间点until。指令原文如下args: any ofseconds,minutes,hours,days, oruntiliso timestamp参数类型含义示例secondsint等待秒数seconds: 30minutesint等待分钟数minutes: 5hoursint等待小时数hours: 1daysint等待天数days: 2untilstring绝对时间点ISO 时间戳until: 2026-09-14T08:00:00组合语义seconds、minutes、hours、days可以同时传入最终等待时长是它们的累加源码中通过datetime.timedelta(days..., hours..., minutes..., seconds...)统一求和见 tools/wait.py。例如同时传hours: 2与minutes: 30实际等待 2 小时 30 分。两种模式的判定逻辑源码以is_duration_wait not bool(until_timestamp_str)区分模式——只要until非空即为时间点模式否则为时长模式tools/wait.py。参数校验与错误处理wait在真正开始等待前会做两道校验参数不合法时不会空转而是立即返回错误消息break_loopFalseAgent 可据此调整策略后重试时长必须为正wait_duration.total_seconds() 0时返回Wait duration must be positive.tools/wait.py时间点不能在过去target_time now时返回Target time ... is in the past.tools/wait.py。until解析失败非法格式时抛出ValueError同样以错误消息返回等待不启动tools/wait.py。until 时间戳的解析规则until支持灵活的时间戳书写由 helpers/localization.py 的localtime_str_to_utc_dt负责解析规则如下带时区偏移优先用datetime.fromisoformat解析如2026-09-14T08:00:0008:00Z后缀等价于00:00UTC代码会先做replace(Z, 00:00)再解析不带时区视为用户本地时间按 Agent Zero 配置的用户时区DEFAULT_USER_TIMEZONEIANA 时区名进行本地化localize_naive_datetime再换算成 UTC 内部存储宽松格式兜底解析失败时依次尝试%Y-%m-%d %H:%M:%S、%Y-%m-%d %H:%M、%Y-%m-%d三种格式T会被替换为空格。这意味着 Agent 可以写出until: 2026-09-14 08:00:00这样更自然的本地时间框架会自动按用户时区解释并在内部统一换算。等待期间显示给用户的时间、等待完成提示中的时间也都会通过serialize_datetime转回用户本地时区展示helpers/localization.py保证前后端时间语义一致。底层实现从 execute 到 managed_waitwait工具的实现类是WaitTool继承自helpers.tool.Tool入口为async def execute(self, **kwargs) - Responsetools/wait.py。完整的调用链如下Agent 调用 wait 工具 └─ WaitTool.execute() ├─ self.agent.handle_intervention() # 等待前检查暂停/干预 ├─ 解析参数构造 target_time ├─ 校验正时长 / 未来时间点 / 合法格式 ├─ PrintStyle.info 输出 Waiting until ... └─ managed_wait(agent, target_time, ...) # 循环等待循环体 ├─ agent.handle_intervention() # 每个循环周期再次检查干预 ├─ 时长模式下补偿干预造成的偏移 ├─ log.update 实时刷新剩余时间 └─ asyncio.sleep(≤1s)核心等待循环真正的时间循环在 helpers/wait.py 的managed_wait中实现它比一次性 sleep复杂得多关键设计有四点循环节拍 ≤ 1 秒每次asyncio.sleep(min(1.0, remaining_seconds))即无论等待多长都以不超过 1 秒的粒度醒一次用于刷新进度、响应干预实时剩余时间通过format_remaining_time把剩余秒数格式化为人类可读文本如2d 3h 5m 10s remaining见 helpers/wait.py并调用log.update(heading...)实时更新 WebUI 中的进度日志干预感知每个周期先调用agent.handle_intervention()用户暂停/中断 Agent 时等待会被感知并响应时长模式的时间补偿时长模式下如果干预导致本轮暂停超过 1.5 秒sleep 周期target_time会相应顺延target_time pause_duration保证等待 5 分钟在扣除干预时间后依然足额——这是 helpers/wait.py 中一个易被忽视但很严谨的细节。日志与 UI 呈现WaitTool实现了两个日志相关方法tools/wait.pyget_log_object()在等待开始时写入一条typeprogress的进度日志heading 为icon://timer Wait: Waiting...并把本次参数kvpsself.args一并记录方便回溯get_heading(text, done)等待中显示剩余时间如icon://timer Wait: 4m 30s remaining完成时切换为icon://timer Wait: Done icon://done_all。等待结束后工具读取 prompts/fw.wait_complete.md 模板内容为Wait complete. Reached {{target_time}}.把目标时间注入后作为工具结果返回给 Agent并更新日志 heading 为完成状态。实际使用Agent 视角的调用示例示例一时长等待等待文件就绪场景Agent 刚触发一个后台构建/下载任务需要等待 30 秒后再检查产物文件是否存在。{ tool: wait, tool_args: { seconds: 30 } }示例二组合时长场景等待外部服务完成数据处理需要 1 小时 15 分。{ tool: wait, tool_args: { hours: 1, minutes: 15 } }示例三绝对时间点等待场景任务需在用户所在时区明天上午 8 点准时执行。until不带时区时按 Agent 配置的用户时区解释。{ tool: wait, tool_args: { until: 2026-09-14T08:00:00 } }示例四跨时区绝对时间场景明确指定 UTC 时间用Z后缀或00:00偏移{ tool: wait, tool_args: { until: 2026-09-14T00:00:00Z } }与并行工具的协作在 Agent Zero 中wait常与parallel工具配合多个等待型任务可通过 tools/parallel.py 并发执行。测试 tests/test_parallel_tool.py 中构造了FakeWaitTool其get_log_object与真实WaitTool保持一致typeprogress、headingicon://timer Wait: Waiting...说明等待进度日志的契约在并行场景下同样成立——并行等待时每个 wait 任务都会独立写入自己的进度日志。工具开发规范与干预契约wait的实现遵循了 Agent Zero 工具开发的核心约定见 tools/AGENTS.md继承与契约工具必须继承helpers.tool.Tool并实现async def execute(...)返回helpers.tool.Response(message..., break_loop...)干预流长时间运行或外部可见的操作必须await self.agent.handle_intervention()wait在等待前和每个循环周期都执行了该调用日志简洁可持久化工具输出保持精简、模型可读、适合写入历史Wait complete. Reached ...即为此设计文档同步每个工具模块须有同名.dox.md文件维护职责、参数、副作用与验证说明tools/wait.py.dox.md 即wait工具的 DOX 档案其中明确记录了WaitTool的类结构、运行时契约break_loop行为、干预处理、提示词契约与观测到的依赖面asyncio、datetime、helpers.localization、helpers.wait等。总结与最佳实践综合官方工具指令与源码实现使用wait工具应把握以下要点克制使用只在等待是任务必要环节时调用定时类长期任务优先考虑scheduler工具而非用超长wait硬等善用组合持续时间参数可叠加days/hours/minutes/seconds混用即可精确表达任意时长理解时区语义until建议携带时区偏移或Z后缀以避免歧义不带时区时框架按用户配置时区解释展示时也会换算回本地时区等待可干预、可观测等待期间用户可暂停/中断WebUI 日志会实时刷新剩余时间Agent 应依据返回的Wait complete. Reached 时间结果继续后续任务错误即反馈参数非法非正时长、过去时间点、非法时间戳时工具立即返回错误消息Agent 可修正参数后重试而不会空转浪费。wait虽小却是 Agent Zero 时间语义闭环中不可或缺的一环它连接了工具调用—人工干预—时间感知—任务续行全流程让自主 Agent 在真实世界中能够从容应对那些需要等一等的任务。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero wait 工具深度解析：让 AI Agent 学会「等一等」的正确姿势
Agent Zero wait 工具深度解析让 AI Agent 学会「等一等」的正确姿势【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 为自主 Agent 提供了一套内置工具集其中wait工具负责让 Agent 在任务执行过程中暂停到指定时长或指定时间点。本文基于 prompts/agent.system.tool.wait.md 的官方工具指令结合 tools/wait.py、helpers/wait.py 的源码实现完整讲解wait工具的 5 个参数、两种等待模式、底层执行机制与干预处理流程帮助你理解并正确驱动 Agent 完成时间敏感型任务。工具定位什么时候该用 waitAgent Zero 是自主运行的多步骤 AI 框架其 Agent 在一个思考—调用工具—接收结果的循环中持续推进任务。绝大多数场景下Agent 应该连续执行但存在两类任务天然需要时间暂停轮询与探测类任务等待文件生成、等待服务端口就绪、等待外部 API 数据到达需要隔一段时间后再检查定时与调度类任务任务要求在某个具体时刻如明早 8 点触发动作。官方工具指令prompts/agent.system.tool.wait.md对wait的定位描述非常克制pause until a duration or timestamp use only when waiting is actually part of the task即只有在等待本身就是任务必要环节时才使用 wait。Agent 不应把 wait 当作无意义的拖延手段也不应代替任务调度器Agent Zero 中定时任务由scheduler工具负责可参考 tools/scheduler.py。这一约束写进了工具提示词是 Agent 行为规范的一部分。wait 工具参数详解wait接受两类参数二者互斥要么指定持续时间seconds/minutes/hours/days中的任意组合要么指定绝对时间点until。指令原文如下args: any ofseconds,minutes,hours,days, oruntiliso timestamp参数类型含义示例secondsint等待秒数seconds: 30minutesint等待分钟数minutes: 5hoursint等待小时数hours: 1daysint等待天数days: 2untilstring绝对时间点ISO 时间戳until: 2026-09-14T08:00:00组合语义seconds、minutes、hours、days可以同时传入最终等待时长是它们的累加源码中通过datetime.timedelta(days..., hours..., minutes..., seconds...)统一求和见 tools/wait.py。例如同时传hours: 2与minutes: 30实际等待 2 小时 30 分。两种模式的判定逻辑源码以is_duration_wait not bool(until_timestamp_str)区分模式——只要until非空即为时间点模式否则为时长模式tools/wait.py。参数校验与错误处理wait在真正开始等待前会做两道校验参数不合法时不会空转而是立即返回错误消息break_loopFalseAgent 可据此调整策略后重试时长必须为正wait_duration.total_seconds() 0时返回Wait duration must be positive.tools/wait.py时间点不能在过去target_time now时返回Target time ... is in the past.tools/wait.py。until解析失败非法格式时抛出ValueError同样以错误消息返回等待不启动tools/wait.py。until 时间戳的解析规则until支持灵活的时间戳书写由 helpers/localization.py 的localtime_str_to_utc_dt负责解析规则如下带时区偏移优先用datetime.fromisoformat解析如2026-09-14T08:00:0008:00Z后缀等价于00:00UTC代码会先做replace(Z, 00:00)再解析不带时区视为用户本地时间按 Agent Zero 配置的用户时区DEFAULT_USER_TIMEZONEIANA 时区名进行本地化localize_naive_datetime再换算成 UTC 内部存储宽松格式兜底解析失败时依次尝试%Y-%m-%d %H:%M:%S、%Y-%m-%d %H:%M、%Y-%m-%d三种格式T会被替换为空格。这意味着 Agent 可以写出until: 2026-09-14 08:00:00这样更自然的本地时间框架会自动按用户时区解释并在内部统一换算。等待期间显示给用户的时间、等待完成提示中的时间也都会通过serialize_datetime转回用户本地时区展示helpers/localization.py保证前后端时间语义一致。底层实现从 execute 到 managed_waitwait工具的实现类是WaitTool继承自helpers.tool.Tool入口为async def execute(self, **kwargs) - Responsetools/wait.py。完整的调用链如下Agent 调用 wait 工具 └─ WaitTool.execute() ├─ self.agent.handle_intervention() # 等待前检查暂停/干预 ├─ 解析参数构造 target_time ├─ 校验正时长 / 未来时间点 / 合法格式 ├─ PrintStyle.info 输出 Waiting until ... └─ managed_wait(agent, target_time, ...) # 循环等待循环体 ├─ agent.handle_intervention() # 每个循环周期再次检查干预 ├─ 时长模式下补偿干预造成的偏移 ├─ log.update 实时刷新剩余时间 └─ asyncio.sleep(≤1s)核心等待循环真正的时间循环在 helpers/wait.py 的managed_wait中实现它比一次性 sleep复杂得多关键设计有四点循环节拍 ≤ 1 秒每次asyncio.sleep(min(1.0, remaining_seconds))即无论等待多长都以不超过 1 秒的粒度醒一次用于刷新进度、响应干预实时剩余时间通过format_remaining_time把剩余秒数格式化为人类可读文本如2d 3h 5m 10s remaining见 helpers/wait.py并调用log.update(heading...)实时更新 WebUI 中的进度日志干预感知每个周期先调用agent.handle_intervention()用户暂停/中断 Agent 时等待会被感知并响应时长模式的时间补偿时长模式下如果干预导致本轮暂停超过 1.5 秒sleep 周期target_time会相应顺延target_time pause_duration保证等待 5 分钟在扣除干预时间后依然足额——这是 helpers/wait.py 中一个易被忽视但很严谨的细节。日志与 UI 呈现WaitTool实现了两个日志相关方法tools/wait.pyget_log_object()在等待开始时写入一条typeprogress的进度日志heading 为icon://timer Wait: Waiting...并把本次参数kvpsself.args一并记录方便回溯get_heading(text, done)等待中显示剩余时间如icon://timer Wait: 4m 30s remaining完成时切换为icon://timer Wait: Done icon://done_all。等待结束后工具读取 prompts/fw.wait_complete.md 模板内容为Wait complete. Reached {{target_time}}.把目标时间注入后作为工具结果返回给 Agent并更新日志 heading 为完成状态。实际使用Agent 视角的调用示例示例一时长等待等待文件就绪场景Agent 刚触发一个后台构建/下载任务需要等待 30 秒后再检查产物文件是否存在。{ tool: wait, tool_args: { seconds: 30 } }示例二组合时长场景等待外部服务完成数据处理需要 1 小时 15 分。{ tool: wait, tool_args: { hours: 1, minutes: 15 } }示例三绝对时间点等待场景任务需在用户所在时区明天上午 8 点准时执行。until不带时区时按 Agent 配置的用户时区解释。{ tool: wait, tool_args: { until: 2026-09-14T08:00:00 } }示例四跨时区绝对时间场景明确指定 UTC 时间用Z后缀或00:00偏移{ tool: wait, tool_args: { until: 2026-09-14T00:00:00Z } }与并行工具的协作在 Agent Zero 中wait常与parallel工具配合多个等待型任务可通过 tools/parallel.py 并发执行。测试 tests/test_parallel_tool.py 中构造了FakeWaitTool其get_log_object与真实WaitTool保持一致typeprogress、headingicon://timer Wait: Waiting...说明等待进度日志的契约在并行场景下同样成立——并行等待时每个 wait 任务都会独立写入自己的进度日志。工具开发规范与干预契约wait的实现遵循了 Agent Zero 工具开发的核心约定见 tools/AGENTS.md继承与契约工具必须继承helpers.tool.Tool并实现async def execute(...)返回helpers.tool.Response(message..., break_loop...)干预流长时间运行或外部可见的操作必须await self.agent.handle_intervention()wait在等待前和每个循环周期都执行了该调用日志简洁可持久化工具输出保持精简、模型可读、适合写入历史Wait complete. Reached ...即为此设计文档同步每个工具模块须有同名.dox.md文件维护职责、参数、副作用与验证说明tools/wait.py.dox.md 即wait工具的 DOX 档案其中明确记录了WaitTool的类结构、运行时契约break_loop行为、干预处理、提示词契约与观测到的依赖面asyncio、datetime、helpers.localization、helpers.wait等。总结与最佳实践综合官方工具指令与源码实现使用wait工具应把握以下要点克制使用只在等待是任务必要环节时调用定时类长期任务优先考虑scheduler工具而非用超长wait硬等善用组合持续时间参数可叠加days/hours/minutes/seconds混用即可精确表达任意时长理解时区语义until建议携带时区偏移或Z后缀以避免歧义不带时区时框架按用户配置时区解释展示时也会换算回本地时区等待可干预、可观测等待期间用户可暂停/中断WebUI 日志会实时刷新剩余时间Agent 应依据返回的Wait complete. Reached 时间结果继续后续任务错误即反馈参数非法非正时长、过去时间点、非法时间戳时工具立即返回错误消息Agent 可修正参数后重试而不会空转浪费。wait虽小却是 Agent Zero 时间语义闭环中不可或缺的一环它连接了工具调用—人工干预—时间感知—任务续行全流程让自主 Agent 在真实世界中能够从容应对那些需要等一等的任务。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考