尧图网站建设 
Agent Zero 中 notify_user 工具深度解析Agent 如何向用户发送带优先级的实时通知【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读notify_user是 Agent Zero AI 框架中一个职责单一但功能关键的 Agent 工具它允许运行中的 Agent 在不结束当前任务循环break_loopFalse的前提下向用户推送一条「带外out-of-band」通知。本文以 tools/notify_user.py.dox.md 为骨架结合 tools/notify_user.py 实现、helpers/notification.py 通知管理器、prompts/agent.system.tool.notify_user.md 工具指令以及相关 API 与测试完整讲解它的参数契约、类型/优先级体系、运行流程、底层实现与 WebUI 联动方式。读完本文你将掌握如何调用、校验、扩展与验证这一通知通道并理解它与helpers.tool.Tool/Response框架的集成契约。一、工具定位与设计意图1.1 职责边界out-of-band 通知根据 DOX 文档tools/notify_user.py.dox.md的定义notify_user模块的职责是Own thenotify_user.pyagent tool — This module sends a user-facing notification from the agent.翻译成工程语言就是Agent 主动向用户发出可见通知。它的关键设计点是「不打断主线任务」——工具执行完毕后返回的Response中break_loopFalse因此 Agent 会继续执行当前的思考-行动循环而通知本身则通过独立通道送达用户界面。1.2 适用场景从 prompts/agent.system.tool.notify_user.md 的指令看它的推荐用法包括后台任务进行中的进度提示progress类型需要用户注意的告警warning/error类型任务完成的成功提示success类型通用备忘/提示info类型 普通优先级。同时指令明确约束了使用边界「use for progress or alerts, not as the final answer」——通知不能替代最终答复最终答复应使用response工具。1.3 与项目其他模块的关系从源码依赖看NotifyUserTool只依赖三个区域agent获取AgentContext、helpers.notification通知枚举与管理器、helpers.toolTool基类与Response。这种扁平目录结构下notify_user.py与其 DOX 文件notify_user.py.dox.md保持同步维护DOX 文档明确要求「Keep this file-level DOX profile synchronized withnotify_user.py」。二、调用契约参数、类型与优先级2.1 参数总览notify_user的调用参数在 prompts/agent.system.tool.notify_user.md 中被正式化并在 tools/notify_user.py 中实现notify_user args: message, optional title, detail, type, priority, timeout对应 tools/notify_user.py 中execute()的参数解析逻辑参数类型默认值说明messagestr空必填通知正文为空则返回错误「Message is required」titlestr空通知标题detailstr空详细内容在NotificationItem中作为可展开的 HTML 内容typestrinfo通知类型见 2.2prioritystr/int20HIGH优先级见 2.3timeoutstr/int30通知展示时长秒Agent 发出的通知使用更长的展示时间注意工具默认的priority是NotificationPriority.HIGH值为 20、timeout是 30 秒源码注释解释了原因「by default, agents should notify with high priority」「agents notifications should have longer timeouts」——Agent 主动推送的通知往往需要用户立即注意到因此默认采用高优先级与较长驻留时间。2.2 NotificationType五种通知类型类型枚举定义在 helpers/notification.pyclass NotificationType(Enum): INFO info SUCCESS success WARNING warning ERROR error PROGRESS progress工具指令中的语义约定prompts/agent.system.tool.notify_user.mdinfo普通备忘/提示普通提示应使用type: infopriority: 10success仅用于已完成任务的成功消息不可当作通用备注使用warning/error告警与错误progress进行中的任务进度提示。在execute()中字符串类型的type会被强制转换为NotificationType枚举若传入非法值如type: critical会抛出ValueError工具捕获后返回Response(messagefInvalid notification type: {notification_type}, break_loopFalse)——错误信息直接回传模型便于 Agent 自我纠错后重试。2.3 NotificationPriority两级优先级class NotificationPriority(Enum): NORMAL 10 HIGH 20工具指令中明确给模型写出数值语义「priority values:20high urgency,10normal urgency; omit for high」见 prompts/agent.system.tool.notify_user.md。也就是说省略priority即等于高优先级只有普通提示才需要显式传priority: 10。非法优先级同样会被校验并返回Invalid notification priority错误。2.4 参数校验顺序从 tools/notify_user.py 源码可以看到严格的校验顺序校验type是否合法NotificationType(notification_type)校验priority是否合法NotificationPriority(priority)校验message是否为空。任一校验失败都会以break_loopFalse的Response返回不会中断 Agent 主循环也不会创建任何通知——这保证了失败的调用是可恢复的而非破坏性的。三、运行流程从工具调用到通知落库3.1 完整调用链一次notify_user调用的完整链路如下Agent 模型按工具指令构造tool_name: notify_user的调用携带message、title、detail、type、priority、timeout参数框架实例化NotifyUserTool继承 helpers/tool.py 中的Tool抽象基类调用await tool.execute(**kwargs)execute()解析并校验参数后调用AgentContext.get_notification_manager().add_notification(...)写入通知返回Response(messageself.agent.read_prompt(fw.notify_user.notification_sent.md), break_loopFalse)其中message读取自 prompts/fw.notify_user.notification_sent.md内容为 The notification has been sent to the user.框架层的Tool.after_execution()将工具结果写入对话历史hist_add_tool_resultAgent 继续执行后续任务。3.2 NotificationManager 的全局单例AgentContext.get_notification_manager()是一个类级惰性单例见 agent.pyclassmethod def get_notification_manager(cls): if cls._notification_manager is None: from helpers.notification import NotificationManager cls._notification_manager NotificationManager() return cls._notification_managerNotificationManagerhelpers/notification.py内部维护notifications: list[NotificationItem]——通知列表updates: list[int]——增量更新序号队列供 WebUI 轮询/推送差异guid——每次clear_all()都会更换的版本标识max_notifications——容量上限默认 100 条超出时通过_enforce_limit()淘汰最旧通知并重排序号。3.3 add_notification创建与更新add_notificationhelpers/notification.py的行为有两个分支新通知构造NotificationItem并追加到列表记录updates随后_enforce_limit()控制容量更新已有通知当传入id且列表中存在相同id的通知时会原地更新其type、priority、title、message、detail、timestamp、display_time、group并将read重置为False——这是 WebUI 端同一条通知持续刷新进度能力的底层支撑比如progress类型通知反复推送同id即可原地更新而不是堆积多条。无论新建还是更新最后都会调用mark_dirty_all(reasonnotification.NotificationManager.add_notification)来自 helpers/state_monitor_integration.py把变更同步给状态监视器保证多端 UI 感知到通知状态变化。NotificationItemhelpers/notification.py)是一个 dataclass__post_init__中自动生成uuid4形式的id并保证type字段始终是NotificationType枚举其output()方法把通知序列化为 WebUI 可消费的字典含no、id、type、priority、title、message、detail、timestamp、display_time、read、group。四、面向开发者的扩展与集成4.1 非工具场景send_notification 静态方法除 Agent 工具外系统其他模块也可通过NotificationManager.send_notification(...)静态方法直接发通知helpers/notification.py。仓库内实际调用点包括api/projects.py项目相关事件通知helpers/settings.py设置变更通知helpers/plugins.py插件生命周期通知extensions/python/user_message_ui/_10_update_check.py更新检查通知。这一设计让「通知」成为系统级能力无论是 Agent 工具、API 端点还是后台扩展都能复用同一条通知管道。4.2 HTTP API 侧创建、历史与已读WebUI 通过三个 API 端点与通知系统交互创建api/notification_create.py 的NotificationCreate接收type、priority、message、title、detail、display_time、group、id其中display_time默认 3 秒、负数或非数字回退到 3 秒与工具不同该 API 端点的priority默认是NotificationPriority.NORMAL普通因为人工创建的通知不需要默认高优先级历史api/notifications_history.py 通过output_all()返回全部通知、当前guid与数量供历史弹窗使用已读api/notifications_mark_read.py 支持按notification_ids批量标记已读mark_read_by_ids或mark_all: true一键全读mark_all_read。4.3 前端消费与通知分组NotificationItem中的group字段用于关联通知分组detail字段可承载 HTML 可展开内容。WebUI 侧通过guid识别通知列表版本、通过updates增量序列做差异化渲染避免整表刷新。这些字段与工具参数一一对应开发者可以直接通过notify_user传入detailHTML来展示富文本细节。五、验证与测试如何确保契约不被破坏DOX 文档tools/notify_user.py.dox.md明确要求工具参数、输出形态、break_loop行为、干预处理、提示指令或副作用一旦变更必须同步更新 DOX 并运行相关测试。与notify_user直接相关的验证集中在 tests/test_tool_action_contracts.pytest_notify_user_prompt_documents_numeric_priority_values第 797 行起直接读取 prompts/agent.system.tool.notify_user.md断言提示词中写明了「priority values:20high urgency,10normal urgency」——这是工具提示词与底层枚举数值契约一致性的回归测试防止模型提示与实际实现脱节同一测试文件还验证了工具提示词禁止「顶层 multi 批量工具」等框架约定test_tool_prompts_prevent_top_level_multi_tool确保notify_user这类工具按单一工具契约暴露。该测试文件采用「stub 化依赖 asyncio.run直驱」的方式验证工具行为是了解本项目工具层测试写法的良好范例。六、常见问题与注意事项message 必填调用时若省略message工具返回Message is required且不产生任何通知。title、detail均可省略。type/priority 大小写与合法性type必须是五种枚举值之一info/success/warning/error/progresspriority必须可转换为10或20。非法值返回明确错误信息Agent 可据此修正重试。不要用通知代替最终答复工具指令明确要求通知仅用于进度或告警任务收尾应使用response工具给出最终答案。success 类型要克制success只用于已完成任务的成功消息通用备注请用infopriority: 10。容量上限通知管理器默认最多保留 100 条超出会淘汰最旧记录如需长期保留通知内容应依赖历史 API 或其他持久化方案而非让通知堆积。七、总结notify_user是 Agent Zero 中Agent → 用户带外通信的标准化通道其设计体现了三个关键工程决策通知与主循环解耦break_loopFalse、参数契约显式化枚举校验 数值优先级提示词、系统级复用同一个NotificationManager同时服务 Agent 工具、HTTP API 与后台扩展。通过 tools/notify_user.py、helpers/notification.py、prompts/agent.system.tool.notify_user.md 与 tests/test_tool_action_contracts.py 的相互印证可以完整还原这条通知管道的实现全貌——对于希望在 Agent Zero 中实现进度上报、告警推送或任务完成提示的开发者而言notify_user是最直接、最受框架约束保护的入口。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero 中 notify_user 工具深度解析：Agent 如何向用户发送带优先级的实时通知
Agent Zero 中 notify_user 工具深度解析Agent 如何向用户发送带优先级的实时通知【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读notify_user是 Agent Zero AI 框架中一个职责单一但功能关键的 Agent 工具它允许运行中的 Agent 在不结束当前任务循环break_loopFalse的前提下向用户推送一条「带外out-of-band」通知。本文以 tools/notify_user.py.dox.md 为骨架结合 tools/notify_user.py 实现、helpers/notification.py 通知管理器、prompts/agent.system.tool.notify_user.md 工具指令以及相关 API 与测试完整讲解它的参数契约、类型/优先级体系、运行流程、底层实现与 WebUI 联动方式。读完本文你将掌握如何调用、校验、扩展与验证这一通知通道并理解它与helpers.tool.Tool/Response框架的集成契约。一、工具定位与设计意图1.1 职责边界out-of-band 通知根据 DOX 文档tools/notify_user.py.dox.md的定义notify_user模块的职责是Own thenotify_user.pyagent tool — This module sends a user-facing notification from the agent.翻译成工程语言就是Agent 主动向用户发出可见通知。它的关键设计点是「不打断主线任务」——工具执行完毕后返回的Response中break_loopFalse因此 Agent 会继续执行当前的思考-行动循环而通知本身则通过独立通道送达用户界面。1.2 适用场景从 prompts/agent.system.tool.notify_user.md 的指令看它的推荐用法包括后台任务进行中的进度提示progress类型需要用户注意的告警warning/error类型任务完成的成功提示success类型通用备忘/提示info类型 普通优先级。同时指令明确约束了使用边界「use for progress or alerts, not as the final answer」——通知不能替代最终答复最终答复应使用response工具。1.3 与项目其他模块的关系从源码依赖看NotifyUserTool只依赖三个区域agent获取AgentContext、helpers.notification通知枚举与管理器、helpers.toolTool基类与Response。这种扁平目录结构下notify_user.py与其 DOX 文件notify_user.py.dox.md保持同步维护DOX 文档明确要求「Keep this file-level DOX profile synchronized withnotify_user.py」。二、调用契约参数、类型与优先级2.1 参数总览notify_user的调用参数在 prompts/agent.system.tool.notify_user.md 中被正式化并在 tools/notify_user.py 中实现notify_user args: message, optional title, detail, type, priority, timeout对应 tools/notify_user.py 中execute()的参数解析逻辑参数类型默认值说明messagestr空必填通知正文为空则返回错误「Message is required」titlestr空通知标题detailstr空详细内容在NotificationItem中作为可展开的 HTML 内容typestrinfo通知类型见 2.2prioritystr/int20HIGH优先级见 2.3timeoutstr/int30通知展示时长秒Agent 发出的通知使用更长的展示时间注意工具默认的priority是NotificationPriority.HIGH值为 20、timeout是 30 秒源码注释解释了原因「by default, agents should notify with high priority」「agents notifications should have longer timeouts」——Agent 主动推送的通知往往需要用户立即注意到因此默认采用高优先级与较长驻留时间。2.2 NotificationType五种通知类型类型枚举定义在 helpers/notification.pyclass NotificationType(Enum): INFO info SUCCESS success WARNING warning ERROR error PROGRESS progress工具指令中的语义约定prompts/agent.system.tool.notify_user.mdinfo普通备忘/提示普通提示应使用type: infopriority: 10success仅用于已完成任务的成功消息不可当作通用备注使用warning/error告警与错误progress进行中的任务进度提示。在execute()中字符串类型的type会被强制转换为NotificationType枚举若传入非法值如type: critical会抛出ValueError工具捕获后返回Response(messagefInvalid notification type: {notification_type}, break_loopFalse)——错误信息直接回传模型便于 Agent 自我纠错后重试。2.3 NotificationPriority两级优先级class NotificationPriority(Enum): NORMAL 10 HIGH 20工具指令中明确给模型写出数值语义「priority values:20high urgency,10normal urgency; omit for high」见 prompts/agent.system.tool.notify_user.md。也就是说省略priority即等于高优先级只有普通提示才需要显式传priority: 10。非法优先级同样会被校验并返回Invalid notification priority错误。2.4 参数校验顺序从 tools/notify_user.py 源码可以看到严格的校验顺序校验type是否合法NotificationType(notification_type)校验priority是否合法NotificationPriority(priority)校验message是否为空。任一校验失败都会以break_loopFalse的Response返回不会中断 Agent 主循环也不会创建任何通知——这保证了失败的调用是可恢复的而非破坏性的。三、运行流程从工具调用到通知落库3.1 完整调用链一次notify_user调用的完整链路如下Agent 模型按工具指令构造tool_name: notify_user的调用携带message、title、detail、type、priority、timeout参数框架实例化NotifyUserTool继承 helpers/tool.py 中的Tool抽象基类调用await tool.execute(**kwargs)execute()解析并校验参数后调用AgentContext.get_notification_manager().add_notification(...)写入通知返回Response(messageself.agent.read_prompt(fw.notify_user.notification_sent.md), break_loopFalse)其中message读取自 prompts/fw.notify_user.notification_sent.md内容为 The notification has been sent to the user.框架层的Tool.after_execution()将工具结果写入对话历史hist_add_tool_resultAgent 继续执行后续任务。3.2 NotificationManager 的全局单例AgentContext.get_notification_manager()是一个类级惰性单例见 agent.pyclassmethod def get_notification_manager(cls): if cls._notification_manager is None: from helpers.notification import NotificationManager cls._notification_manager NotificationManager() return cls._notification_managerNotificationManagerhelpers/notification.py内部维护notifications: list[NotificationItem]——通知列表updates: list[int]——增量更新序号队列供 WebUI 轮询/推送差异guid——每次clear_all()都会更换的版本标识max_notifications——容量上限默认 100 条超出时通过_enforce_limit()淘汰最旧通知并重排序号。3.3 add_notification创建与更新add_notificationhelpers/notification.py的行为有两个分支新通知构造NotificationItem并追加到列表记录updates随后_enforce_limit()控制容量更新已有通知当传入id且列表中存在相同id的通知时会原地更新其type、priority、title、message、detail、timestamp、display_time、group并将read重置为False——这是 WebUI 端同一条通知持续刷新进度能力的底层支撑比如progress类型通知反复推送同id即可原地更新而不是堆积多条。无论新建还是更新最后都会调用mark_dirty_all(reasonnotification.NotificationManager.add_notification)来自 helpers/state_monitor_integration.py把变更同步给状态监视器保证多端 UI 感知到通知状态变化。NotificationItemhelpers/notification.py)是一个 dataclass__post_init__中自动生成uuid4形式的id并保证type字段始终是NotificationType枚举其output()方法把通知序列化为 WebUI 可消费的字典含no、id、type、priority、title、message、detail、timestamp、display_time、read、group。四、面向开发者的扩展与集成4.1 非工具场景send_notification 静态方法除 Agent 工具外系统其他模块也可通过NotificationManager.send_notification(...)静态方法直接发通知helpers/notification.py。仓库内实际调用点包括api/projects.py项目相关事件通知helpers/settings.py设置变更通知helpers/plugins.py插件生命周期通知extensions/python/user_message_ui/_10_update_check.py更新检查通知。这一设计让「通知」成为系统级能力无论是 Agent 工具、API 端点还是后台扩展都能复用同一条通知管道。4.2 HTTP API 侧创建、历史与已读WebUI 通过三个 API 端点与通知系统交互创建api/notification_create.py 的NotificationCreate接收type、priority、message、title、detail、display_time、group、id其中display_time默认 3 秒、负数或非数字回退到 3 秒与工具不同该 API 端点的priority默认是NotificationPriority.NORMAL普通因为人工创建的通知不需要默认高优先级历史api/notifications_history.py 通过output_all()返回全部通知、当前guid与数量供历史弹窗使用已读api/notifications_mark_read.py 支持按notification_ids批量标记已读mark_read_by_ids或mark_all: true一键全读mark_all_read。4.3 前端消费与通知分组NotificationItem中的group字段用于关联通知分组detail字段可承载 HTML 可展开内容。WebUI 侧通过guid识别通知列表版本、通过updates增量序列做差异化渲染避免整表刷新。这些字段与工具参数一一对应开发者可以直接通过notify_user传入detailHTML来展示富文本细节。五、验证与测试如何确保契约不被破坏DOX 文档tools/notify_user.py.dox.md明确要求工具参数、输出形态、break_loop行为、干预处理、提示指令或副作用一旦变更必须同步更新 DOX 并运行相关测试。与notify_user直接相关的验证集中在 tests/test_tool_action_contracts.pytest_notify_user_prompt_documents_numeric_priority_values第 797 行起直接读取 prompts/agent.system.tool.notify_user.md断言提示词中写明了「priority values:20high urgency,10normal urgency」——这是工具提示词与底层枚举数值契约一致性的回归测试防止模型提示与实际实现脱节同一测试文件还验证了工具提示词禁止「顶层 multi 批量工具」等框架约定test_tool_prompts_prevent_top_level_multi_tool确保notify_user这类工具按单一工具契约暴露。该测试文件采用「stub 化依赖 asyncio.run直驱」的方式验证工具行为是了解本项目工具层测试写法的良好范例。六、常见问题与注意事项message 必填调用时若省略message工具返回Message is required且不产生任何通知。title、detail均可省略。type/priority 大小写与合法性type必须是五种枚举值之一info/success/warning/error/progresspriority必须可转换为10或20。非法值返回明确错误信息Agent 可据此修正重试。不要用通知代替最终答复工具指令明确要求通知仅用于进度或告警任务收尾应使用response工具给出最终答案。success 类型要克制success只用于已完成任务的成功消息通用备注请用infopriority: 10。容量上限通知管理器默认最多保留 100 条超出会淘汰最旧记录如需长期保留通知内容应依赖历史 API 或其他持久化方案而非让通知堆积。七、总结notify_user是 Agent Zero 中Agent → 用户带外通信的标准化通道其设计体现了三个关键工程决策通知与主循环解耦break_loopFalse、参数契约显式化枚举校验 数值优先级提示词、系统级复用同一个NotificationManager同时服务 Agent 工具、HTTP API 与后台扩展。通过 tools/notify_user.py、helpers/notification.py、prompts/agent.system.tool.notify_user.md 与 tests/test_tool_action_contracts.py 的相互印证可以完整还原这条通知管道的实现全貌——对于希望在 Agent Zero 中实现进度上报、告警推送或任务完成提示的开发者而言notify_user是最直接、最受框架约束保护的入口。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考