Agent Zero /nudge 接口详解强制重置卡住的 Agent 进程并注入“继续”指令的底层机制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文基于 api/nudge.py.dox.md 这份文件级 DOX 契约文档深入讲解 Agent Zero 中POST /nudge端点的完整设计它的请求/响应契约、AgentContext.nudge()的底层语义杀进程 解除暂停 注入fw.msg_nudge.md提示词、前端按钮到 Python 运行时的完整调用链、与/pause、/stop及_a0_connector插件端点的差异以及该目录 DOX 契约所规定的安全与验证规范。读完后你将掌握 Agent Zero “唤醒/重启卡住任务”的整套机制并能在集成开发中正确调用这一端点。1. DOX 契约文档声明了什么api/nudge.py.dox.md 是 Agent Zeroapi/目录下“每个端点一个.py 一个.py.dox.md”扁平布局中的契约档案。它对nudge.py的核心声明包括Purpose职责本文件拥有nudge.pyAPI 端点处理 nudge API 请求并要求该 DOX 档案与实现保持同步因为api/目录是有意保持扁平intentionally flat的Ownership所有权划分api/nudge.py 拥有运行时实现DOX 档案拥有关于“职责、契约、副作用、验证”的持久化笔记。类清单声明了唯一入口Nudge继承自ApiHandler方法签名async process(self, input: dict, request: Request) - dict | ResponseRuntime Contracts运行时契约HTTP handler 必须继承自helpers.api.ApiHandlerWebSocket handler 则继承helpers.ws.WsHandler当请求负载、认证/CSRF 要求、响应结构或路由副作用变化时必须同步更新 DOXKey Concepts关键概念源码中观察到的重要被调用对象为self.use_context、context.nudge、context.log.log、ExceptionWork Guidance协作守则除非端点契约明确变更必须保留认证、CSRF、loopback 与 API-key 检查payload 形状变化时要同步更新前端调用方、插件调用方和测试非 JSON 响应文件、重定向、特定状态码必须使用helpers.api.ResponseVerification验证对变更行为运行端点级或 API/WebSocket 测试“若不存在聚焦测试则对浏览器调用方做冒烟测试”。DOX 中列出由源码搜索观察到的相关测试文件为 tests/test_browser_agent_regressions.py。2. 端点实现Nudge的完整契约实现本体非常短小位于 api/nudge.pyfrom helpers.api import ApiHandler, Request, Response class Nudge(ApiHandler): async def process(self, input: dict, request: Request) - dict | Response: ctxid input.get(ctxid, ) if not ctxid: raise Exception(No context id provided) context self.use_context(ctxid) context.nudge() msg Process reset, agent nudged. context.log.log(typeinfo, contentmsg) return { message: msg, ctxid: context.id, }结合 helpers/api.py 中ApiHandler基类第 33-100 行的通用逻辑可以精确还原该端点的完整 HTTP 契约2.1 路由方法与认证ApiHandler的类属性默认值helpers/api.py决定了/nudge的访问约束get_methods()默认返回[POST]—— 只接受 POST 请求requires_auth()默认True—— 需要登录认证requires_csrf()默认等价于requires_auth()—— 因此该端点受 CSRF 校验保护这与 DOX “Work Guidance”中“保留 CSRF 检查”的要求直接对应requires_loopback()与requires_api_key()默认False即该端点不额外限制仅回环地址访问、也不单独要求 API-keyNudge类未覆写任何类属性。2.2 请求与响应形状请求体JSON{ctxid: 上下文ID}ctxid必填。成功响应由handle_request统一以 200 application/json包裹{ message: Process reset, agent nudged., ctxid: 被操作的上下文ID }缺少ctxid时process抛出Exception(No context id provided)。ApiHandler.handle_requesthelpers/api.py会捕获该异常返回500 状态 text/plain错误文本。这是一个值得注意的契约细节主端点对“参数缺失”选择了通用 500 错误路径而不是 400 —— 这一点与后文_a0_connector的受保护端点形成对照。上下文获取self.use_context(ctxid)委托给helpers.context_utils.use_context见 helpers/api.py其第二个参数create_if_not_exists默认为True。从源码结构看对不存在的ctxid调用/nudge时行为是“按需创建上下文后再对其执行 nudge”也就是说它会启动一条全新的 agent 链 —— 这与_a0_connector版本“找不到上下文就返回 404”的严格语义不同集成时需要注意区分。3.AgentContext.nudge()的运行时语义重置三步曲端点真正的工作由 agent.py 中的AgentContext.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三步语义非常清晰kill_process()kill_process()在 agent.py 中实现为“若存在当前任务则self.task.kill()”即终止正在运行的 agent 任务线程。因此 nudge 不是“在运行中插入消息”而是先杀掉当前进程self.paused False清除暂停标记保证即使上下文处于 paused 状态也能被重新驱动communicate(UserMessage(...))读取提示词文件 prompts/fw.msg_nudge.md 并作为用户消息发送给根 agentagent0。该提示词内容极简{ system_message: Nudged - continue }即向 agent 注入一条“Nudged - continue”被推动 —— 继续的指令让模型基于当前对话历史继续推进任务。再看communicate()的实现agent.py它先解除paused然后判断“当前任务是否仍存活”——存活时把消息作为intervention干预消息沿 agent 层级向上广播给broadcast_level内的各级 agent不存活时nudge 场景正是如此因为进程刚被 kill则调用run_task(self._process_chain, current_agent, msg)启动一条全新的处理链。因此nudge()整体等价于杀旧任务 → 清暂停 → 以“Nudged - continue”为种子消息重启整条 agent 链响应消息Process reset, agent nudged.中的 Process reset 正是对前两步的准确描述。两个extension.extensible装饰器nudge、kill_process、communicate均有说明这些方法都是插件扩展点 —— 从源码结构看第三方插件可以通过扩展机制覆写 nudge 行为这是 Agent Zero 插件化架构的一部分。4. 端点在整个控制体系中的位置Nudge 与 pause/resume/stop 同属“agent 生命周期控制”一族在集成命令处理层 helpers/integration_commands.py 中可以看到它们的并列关系def _handle_pause(context: AgentContext) - str: if not context.is_running(): return No active run is currently running. context.paused True return Agent paused. def _handle_resume(context: AgentContext) - str: context.paused False return Agent resumed. def _handle_nudge(context: AgentContext) - str: context.nudge() return Agent nudged.三者语义边界清晰操作行为进程是否存活对话历史/pause置paused True不打断执行存活保留/stop终止当前运行见 api/stop.py终止保留/nudgekill 进程 解除暂停 注入 “Nudged - continue” 重启 agent 链先杀后重启保留模型基于历史“继续”即 nudge 是“stop 带上下文继续”的组合典型用途是agent 陷入卡死、循环或无响应状态时由用户强制重置并让它继续当前任务。5. 前端调用链按钮 →/nudgeWebUI 侧的调用方是聊天输入区的底部操作栏。webui/components/chat/input/bottom-actions-bar.html 中的按钮触发 Pinia store 方法button typebutton classtext-button idnudges_window click$store.chatInput.nudge()对应逻辑在 webui/components/chat/input/input-store.jsasync nudge() { try { const context globalThis.getContext(); await globalThis.sendJsonData(/nudge, { ctxid: context }); } catch (e) { if (globalThis.toastFetchError) { globalThis.toastFetchError(Error nudging agent, e); } } },即前端把当前聊天上下文 ID 作为ctxidPOST 到/nudge失败时以 toast 提示 Error nudging agent。这正是 DOX “Work Guidance”里“payload 形状变化时同步更新前端调用方”所指的实际调用点之一。6. 对照端点_a0_connector的受保护 nudge插件_a0_connector暴露了一个语义更强化的并行端点 plugins/_a0_connector/api/v1/nudge.pyPOST /api/plugins/_a0_connector/v1/nudge继承自ProtectedConnectorApiHandler必填参数名不同请求体为{context_id: ...}strip 后判空缺失时返回400{error: context_id is required}显式 404通过AgentContext.get(context_id)查找不存在时返回404{error: Context not found}不自动创建上下文成功响应{ ok: true, context_id: id, status: nudged, message: Process reset, agent nudged. }它最终同样调用context.nudge()并写一条 info 日志。对比两个端点可以看到同一核心操作的两种契约风格主端点走通用ApiHandler认证 CSRF异常落到 500连接器端点走受保护处理器细粒度 4xx 错误、context_id命名。外部工具集成如 A2A 场景参见 docs/guides/a2-cli-connector.md时应按各自契约构造请求。7. 验证与测试现状DOX 的 Verification 一节指明对行为变更运行端点级测试“若没有聚焦测试则对浏览器调用方做冒烟测试”并列出的相关测试文件为 tests/test_browser_agent_regressions.py。需要如实说明对该文件的实际检索命中的是与nudge字面相近的浏览器画布变量如nudgedWidth、_nudged_viewport与 nudge 端点无关即当前仓库中POST /nudge并没有独立的聚焦测试端点行为的回归主要依赖 WebUI 手动冒烟验证。这恰好印证了 DOX 中那条验证指引的必要性——后续为该端点补充契约测试参数缺失、上下文缺失、成功路径三条会是一个有价值的改进方向。8. 小结使用与集成要点调用方式登录后POST /nudgeJSON 体{ctxid: 上下文ID}成功返回{message: Process reset, agent nudged., ctxid: ...}缺少ctxid会得到 500 文本错误语义nudge 杀死当前 agent 进程 清除暂停 以 prompts/fw.msg_nudge.md“Nudged - continue”为种子消息重启 agent 链对话历史保留模型被要求继续关键源码端点实现在 api/nudge.py核心逻辑在 agent.py 的AgentContext.nudge()基类契约在 helpers/api.py前端入口在 webui/components/chat/input/input-store.js开发守则按 api/nudge.py.dox.md 的要求任何对 payload、认证/CSRF 或响应结构的改动都必须同步更新 DOX 档案、前端调用方input-store.js、插件调用方_a0_connector版端点与测试并保留既有的认证/CSRF/loopback/API-key 检查。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero /nudge 接口详解：强制重置卡住的 Agent 进程并注入“继续”指令的底层机制
Agent Zero /nudge 接口详解强制重置卡住的 Agent 进程并注入“继续”指令的底层机制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文基于 api/nudge.py.dox.md 这份文件级 DOX 契约文档深入讲解 Agent Zero 中POST /nudge端点的完整设计它的请求/响应契约、AgentContext.nudge()的底层语义杀进程 解除暂停 注入fw.msg_nudge.md提示词、前端按钮到 Python 运行时的完整调用链、与/pause、/stop及_a0_connector插件端点的差异以及该目录 DOX 契约所规定的安全与验证规范。读完后你将掌握 Agent Zero “唤醒/重启卡住任务”的整套机制并能在集成开发中正确调用这一端点。1. DOX 契约文档声明了什么api/nudge.py.dox.md 是 Agent Zeroapi/目录下“每个端点一个.py 一个.py.dox.md”扁平布局中的契约档案。它对nudge.py的核心声明包括Purpose职责本文件拥有nudge.pyAPI 端点处理 nudge API 请求并要求该 DOX 档案与实现保持同步因为api/目录是有意保持扁平intentionally flat的Ownership所有权划分api/nudge.py 拥有运行时实现DOX 档案拥有关于“职责、契约、副作用、验证”的持久化笔记。类清单声明了唯一入口Nudge继承自ApiHandler方法签名async process(self, input: dict, request: Request) - dict | ResponseRuntime Contracts运行时契约HTTP handler 必须继承自helpers.api.ApiHandlerWebSocket handler 则继承helpers.ws.WsHandler当请求负载、认证/CSRF 要求、响应结构或路由副作用变化时必须同步更新 DOXKey Concepts关键概念源码中观察到的重要被调用对象为self.use_context、context.nudge、context.log.log、ExceptionWork Guidance协作守则除非端点契约明确变更必须保留认证、CSRF、loopback 与 API-key 检查payload 形状变化时要同步更新前端调用方、插件调用方和测试非 JSON 响应文件、重定向、特定状态码必须使用helpers.api.ResponseVerification验证对变更行为运行端点级或 API/WebSocket 测试“若不存在聚焦测试则对浏览器调用方做冒烟测试”。DOX 中列出由源码搜索观察到的相关测试文件为 tests/test_browser_agent_regressions.py。2. 端点实现Nudge的完整契约实现本体非常短小位于 api/nudge.pyfrom helpers.api import ApiHandler, Request, Response class Nudge(ApiHandler): async def process(self, input: dict, request: Request) - dict | Response: ctxid input.get(ctxid, ) if not ctxid: raise Exception(No context id provided) context self.use_context(ctxid) context.nudge() msg Process reset, agent nudged. context.log.log(typeinfo, contentmsg) return { message: msg, ctxid: context.id, }结合 helpers/api.py 中ApiHandler基类第 33-100 行的通用逻辑可以精确还原该端点的完整 HTTP 契约2.1 路由方法与认证ApiHandler的类属性默认值helpers/api.py决定了/nudge的访问约束get_methods()默认返回[POST]—— 只接受 POST 请求requires_auth()默认True—— 需要登录认证requires_csrf()默认等价于requires_auth()—— 因此该端点受 CSRF 校验保护这与 DOX “Work Guidance”中“保留 CSRF 检查”的要求直接对应requires_loopback()与requires_api_key()默认False即该端点不额外限制仅回环地址访问、也不单独要求 API-keyNudge类未覆写任何类属性。2.2 请求与响应形状请求体JSON{ctxid: 上下文ID}ctxid必填。成功响应由handle_request统一以 200 application/json包裹{ message: Process reset, agent nudged., ctxid: 被操作的上下文ID }缺少ctxid时process抛出Exception(No context id provided)。ApiHandler.handle_requesthelpers/api.py会捕获该异常返回500 状态 text/plain错误文本。这是一个值得注意的契约细节主端点对“参数缺失”选择了通用 500 错误路径而不是 400 —— 这一点与后文_a0_connector的受保护端点形成对照。上下文获取self.use_context(ctxid)委托给helpers.context_utils.use_context见 helpers/api.py其第二个参数create_if_not_exists默认为True。从源码结构看对不存在的ctxid调用/nudge时行为是“按需创建上下文后再对其执行 nudge”也就是说它会启动一条全新的 agent 链 —— 这与_a0_connector版本“找不到上下文就返回 404”的严格语义不同集成时需要注意区分。3.AgentContext.nudge()的运行时语义重置三步曲端点真正的工作由 agent.py 中的AgentContext.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三步语义非常清晰kill_process()kill_process()在 agent.py 中实现为“若存在当前任务则self.task.kill()”即终止正在运行的 agent 任务线程。因此 nudge 不是“在运行中插入消息”而是先杀掉当前进程self.paused False清除暂停标记保证即使上下文处于 paused 状态也能被重新驱动communicate(UserMessage(...))读取提示词文件 prompts/fw.msg_nudge.md 并作为用户消息发送给根 agentagent0。该提示词内容极简{ system_message: Nudged - continue }即向 agent 注入一条“Nudged - continue”被推动 —— 继续的指令让模型基于当前对话历史继续推进任务。再看communicate()的实现agent.py它先解除paused然后判断“当前任务是否仍存活”——存活时把消息作为intervention干预消息沿 agent 层级向上广播给broadcast_level内的各级 agent不存活时nudge 场景正是如此因为进程刚被 kill则调用run_task(self._process_chain, current_agent, msg)启动一条全新的处理链。因此nudge()整体等价于杀旧任务 → 清暂停 → 以“Nudged - continue”为种子消息重启整条 agent 链响应消息Process reset, agent nudged.中的 Process reset 正是对前两步的准确描述。两个extension.extensible装饰器nudge、kill_process、communicate均有说明这些方法都是插件扩展点 —— 从源码结构看第三方插件可以通过扩展机制覆写 nudge 行为这是 Agent Zero 插件化架构的一部分。4. 端点在整个控制体系中的位置Nudge 与 pause/resume/stop 同属“agent 生命周期控制”一族在集成命令处理层 helpers/integration_commands.py 中可以看到它们的并列关系def _handle_pause(context: AgentContext) - str: if not context.is_running(): return No active run is currently running. context.paused True return Agent paused. def _handle_resume(context: AgentContext) - str: context.paused False return Agent resumed. def _handle_nudge(context: AgentContext) - str: context.nudge() return Agent nudged.三者语义边界清晰操作行为进程是否存活对话历史/pause置paused True不打断执行存活保留/stop终止当前运行见 api/stop.py终止保留/nudgekill 进程 解除暂停 注入 “Nudged - continue” 重启 agent 链先杀后重启保留模型基于历史“继续”即 nudge 是“stop 带上下文继续”的组合典型用途是agent 陷入卡死、循环或无响应状态时由用户强制重置并让它继续当前任务。5. 前端调用链按钮 →/nudgeWebUI 侧的调用方是聊天输入区的底部操作栏。webui/components/chat/input/bottom-actions-bar.html 中的按钮触发 Pinia store 方法button typebutton classtext-button idnudges_window click$store.chatInput.nudge()对应逻辑在 webui/components/chat/input/input-store.jsasync nudge() { try { const context globalThis.getContext(); await globalThis.sendJsonData(/nudge, { ctxid: context }); } catch (e) { if (globalThis.toastFetchError) { globalThis.toastFetchError(Error nudging agent, e); } } },即前端把当前聊天上下文 ID 作为ctxidPOST 到/nudge失败时以 toast 提示 Error nudging agent。这正是 DOX “Work Guidance”里“payload 形状变化时同步更新前端调用方”所指的实际调用点之一。6. 对照端点_a0_connector的受保护 nudge插件_a0_connector暴露了一个语义更强化的并行端点 plugins/_a0_connector/api/v1/nudge.pyPOST /api/plugins/_a0_connector/v1/nudge继承自ProtectedConnectorApiHandler必填参数名不同请求体为{context_id: ...}strip 后判空缺失时返回400{error: context_id is required}显式 404通过AgentContext.get(context_id)查找不存在时返回404{error: Context not found}不自动创建上下文成功响应{ ok: true, context_id: id, status: nudged, message: Process reset, agent nudged. }它最终同样调用context.nudge()并写一条 info 日志。对比两个端点可以看到同一核心操作的两种契约风格主端点走通用ApiHandler认证 CSRF异常落到 500连接器端点走受保护处理器细粒度 4xx 错误、context_id命名。外部工具集成如 A2A 场景参见 docs/guides/a2-cli-connector.md时应按各自契约构造请求。7. 验证与测试现状DOX 的 Verification 一节指明对行为变更运行端点级测试“若没有聚焦测试则对浏览器调用方做冒烟测试”并列出的相关测试文件为 tests/test_browser_agent_regressions.py。需要如实说明对该文件的实际检索命中的是与nudge字面相近的浏览器画布变量如nudgedWidth、_nudged_viewport与 nudge 端点无关即当前仓库中POST /nudge并没有独立的聚焦测试端点行为的回归主要依赖 WebUI 手动冒烟验证。这恰好印证了 DOX 中那条验证指引的必要性——后续为该端点补充契约测试参数缺失、上下文缺失、成功路径三条会是一个有价值的改进方向。8. 小结使用与集成要点调用方式登录后POST /nudgeJSON 体{ctxid: 上下文ID}成功返回{message: Process reset, agent nudged., ctxid: ...}缺少ctxid会得到 500 文本错误语义nudge 杀死当前 agent 进程 清除暂停 以 prompts/fw.msg_nudge.md“Nudged - continue”为种子消息重启 agent 链对话历史保留模型被要求继续关键源码端点实现在 api/nudge.py核心逻辑在 agent.py 的AgentContext.nudge()基类契约在 helpers/api.py前端入口在 webui/components/chat/input/input-store.js开发守则按 api/nudge.py.dox.md 的要求任何对 payload、认证/CSRF 或响应结构的改动都必须同步更新 DOX 档案、前端调用方input-store.js、插件调用方_a0_connector版端点与测试并保留既有的认证/CSRF/loopback/API-key 检查。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考