Agent Zero 的 response 工具深度解析从ResponseTool实现到消息循环终止机制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读response是 Agent Zero 框架中承担最终答复职责的核心工具tool当智能体完成一项任务、或当前没有活跃任务时它把最终结果输出给用户并凭借break_loop语义终止消息循环。本文以仓库中的 tools/response.py.dox.md 为骨架结合 tools/response.py 的完整实现、helpers/tool.py 的工具基类契约、helpers/errors.py 的可修复异常体系以及 agent.py 的循环调度逻辑讲清楚该工具的参数契约、执行生命周期、错误自修复机制和测试验证方式。读完你不仅能透彻理解response工具的底层原理还能举一反三地掌握 Agent Zero 全部内置工具的统一实现规范。一、DOX 文档的定位工具职责的持久化契约Agent Zero 的tools/目录采用实现 DOX双文件扁平结构每个*.py文件旁边都伴随一个*.py.dox.md例如 tools/response.py 对应 tools/response.py.dox.md。DOXDocumentation of eXecution文件并非简单注释它记录的是该模块的职责、运行时契约、副作用与验证方式并要求在工具参数、输出结构、break_loop行为、干预intervention处理或 Prompt 指令发生变化时同步更新。针对response工具这份 DOX 文档明确锁定了以下契约职责向用户输出最终或中间阶段的智能体回复实现归属response.py持有运行时实现DOX 文件持有关于该实现的责任、契约、副作用与验证的持久化笔记依赖边界仅依赖helpers.errors与helpers.tool两个导入域变更要求工具参数、输出形状、break_loop行为、干预处理、Prompt 指令或副作用任何一项变化都必须同步更新 DOX。这种实现与契约分离、强制同步的模式让 Agent Zero 的工具在快速迭代中始终保有可审计的接口边界。二、ResponseTool类结构与生命周期钩子2.1 类声明与父类契约helpers/tool.py 定义了所有工具的共同基类Tool其构造签名接收agent、name、method、args、message与loop_data并声明了三个生命周期方法execute(**kwargs)抽象方法执行工具主体逻辑必须返回Responsebefore_execution(**kwargs)执行前钩子默认打印工具名与参数并创建日志对象after_execution(response, **kwargs)执行后钩子默认将结果写入历史hist_add_tool_result并更新日志。ResponseTooltools/response.py#L5正是这三个钩子的具体实现且刻意覆盖了父类的默认行为——尤其是after_execution它选择不写入历史、不输出内容见下文第四节。2.2 核心数据结构Responseexecute的返回值是 helpers/tool.py 中的 dataclassResponsedataclass class Response: message: str break_loop: bool additional: dict[str, Any] | None Nonemessage要交给 Agent 循环处理的文本break_loop是否终止消息循环response工具固定为Trueadditional可选的附加数据例如在responsesAPI 架构下可携带_responses_output_item见 agent.py#L1213-L1217。三、参数契约text优先、message兜底、否则自修复3.1 execute 的完整实现ResponseTool.execute的实现极其精简全部逻辑如下tools/response.py#L7-L14async def execute(self, **kwargs): for key in (text, message): message self.args.get(key) if isinstance(message, str) and message.strip(): return Response(messagemessage, break_loopTrue) raise RepairableException( response tool requires a non-empty top-level text or message string argument )它依次检查两个顶层字符串参数text首选参数。只要它是非空strip()后不为空的字符串就直接作为回复内容message兼容参数。当text缺失或为空白时回退使用失败路径两者都缺失或为空则抛出RepairableException。3.2 RepairableException让 Agent 自己修复参数RepairableException定义在 helpers/errors.py#L83-L86其类注释点明了设计意图An exception type indicating errors that can be surfaced to the LLM for potential self-repair.这是 Agent Zero 错误分层体系RepairableException/InterventionException/HandledException中的关键一环。当response工具因参数不合法而抛出该异常时Agent 主循环agent.py#L1180-L1187会将其转换为历史中的 warning 消息hist_add_warning把错误详情回写给 LLM让模型感知到刚才的工具调用格式有误从而自行修正参数并重试而不是直接崩溃终止任务。可以推断的设计权衡text/message双参数的存在是为了兼容历史 Prompt 输出而必须非空的强校验则防止智能体输出空白回复导致死循环或空内容持久化。四、before / after 钩子日志职责的迁移与收尾4.1 before_execution静默化tools/response.py#L16-L19 中的before_execution只剩一条注释和一个passasync def before_execution(self, **kwargs): # self.log self.agent.context.log.log(typeresponse, heading..., contentself.args.get(text, )) # dont log here anymore, we have the live_response extension now pass这段注释本身即是重要信息日志职责已经从工具内部迁出。早期版本在这里写typeresponse的日志现在改由live_response扩展负责实时响应的展示。这符合 Agent Zero 的扩展extension架构——UI 相关的实时输出统一收敛到扩展层工具本体保持纯净。4.2 after_execution标记日志完成tools/response.py#L21-L26 的after_execution同样不做历史写入与终端输出async def after_execution(self, response, **kwargs): # do not add anything to the history or output if self.loop_data and log_item_response in self.loop_data.params_temporary: log self.loop_data.params_temporary[log_item_response] log.update(finishedTrue) # mark the message as finished其唯一副作用是如果循环数据loop_data.params_temporary中存在log_item_response日志条目则将其标记为finishedTrue用于在 UI 上结束正在生成的状态。注释明确说明不向历史或输出追加任何内容——这正是response作为终端答复工具的语义内容只经break_loop路径返回给上层不再污染消息历史。对比父类 helpers/tool.py#L54-L59 的默认after_execution会hist_add_tool_result并打印结果可以清晰看到ResponseTool有意识地覆盖了这套默认行为。五、break_loopTrue消息循环的终止开关break_loop是Response契约中最具控制力的字段。ResponseTool无论走text还是message分支都固定返回break_loopTrue。Agent 主循环在 agent.py#L1222-L1224 与 agent.py#L1497-L1498 两处分别对应常规工具执行与responses架构路径统一处理if response.break_loop: self._clear_responses_pending_state() return response.message即一旦工具返回break_loopTrue循环立即返回response.message作为本轮的最终结果终止工具调用 → 模型再推理的迭代链条。这也解释了为什么 Prompt 规范要求仅在任务完成或没有活跃任务时才使用该工具。对照参考框架内绝大多数工具如plugins/_browser/tools/browser.py、plugins/_code_execution/tools/code_execution_tool.py、plugins/_document_query/tools/document_query.py都返回break_loopFalse把控制权交还给模型继续推理只有response与示例工具见 agents/_example/tools/response.py才设置break_loopTrue。这一对比恰好勾勒出 Agent Zero 的循环语义工具默认不打断推理仅答复拥有终止权。六、Prompt 指令模型视角的使用规范工具的实现契约之外Agent Zero 还通过 Prompt 模板约束模型的调用行为。prompts/agent.system.tool.response.md 给出了模型视角的完整规范### response: final answer to user ends task processing use only when done or no task active args: text default to balanced, concise answers: informative but tight, not terse and not verbose.核心约束包括语义向用户输出最终答复结束任务处理使用时机仅当任务完成或没有活跃任务时参数text风格基调平衡而简洁——信息量充足但紧凑既不生硬简短也不冗长。并附带标准调用示例JSON{ thoughts: [ ... ], headline: Providing final answer to user, tool_name: response, tool_args: { text: Answer to the user } }此外prompts/agent.system.response_tool_tips.md 补充了一条关键提示对于长篇幅的既有文本不要重新编写而应使用§§include(path)语法直接引用文件内容。这保证了最终答复可读性与上下文窗口的平衡。七、验证与测试如何回归检查该工具DOX 文档明确要求行为变更后需运行针对性测试验证工具与 Prompt 契约无聚焦测试时则做冒烟测试smoke-test agent 执行。文档记录的关联测试包括tests/chunk_parser_test.pytests/rate_limiter_test.pytests/test_browser_agent_regressions.pytests/test_chat_compaction.pytests/test_dirty_json.pytests/test_download_toast_regressions.pytests/test_fasta2a_client.pytests/test_fastmcp_openapi_security.py这些测试大多并非直接单测ResponseTool而是覆盖与response输出链路相邻的契约面——例如break_loop返回的消息如何进入聊天持久化test_chat_compaction、错误参数触发的自修复路径、以及 WebUI 下载/推送等下游消费行为。验证策略的核心思路是通过端到端与相邻模块的回归间接保障response的契约不被破坏。八、源码级全景回顾将以上剖析汇总为一张对照表即可看清response工具在 Agent Zero 中的完整坐标关注点依据结论职责tools/response.py.dox.md输出最终/中间答复拥有终止循环的能力类结构tools/response.py#L5ResponseTool(Tool)实现三个生命周期钩子参数契约tools/response.py#L7-L14text优先、message兜底、均非空否则抛RepairableException返回结构helpers/tool.py#L11-L15Response(message, break_loopTrue, additionalNone)循环终止agent.py#L1222-L1224 / agent.py#L1497-L1498break_loopTrue时返回消息并结束本轮错误自修复helpers/errors.py#L83-L86RepairableException转 warning 回写 LLM日志收尾tools/response.py#L21-L26标记log_item_response为 finished不写历史Prompt 规范prompts/agent.system.tool.response.md仅任务完成时使用参数为text风格平衡简洁长文本技巧prompts/agent.system.response_tool_tips.md用§§include(path)引用既有文件从这份实现中可以看出 Agent Zero 工具设计的三个鲜明特征契约文档化DOX 与实现强制同步、错误可修复化以RepairableException驱动 LLM 自纠错、副作用最小化日志交给扩展层、历史交给上层循环。理解了response也就掌握了阅读 Agent Zero 其余全部内置工具与插件工具如plugins/_a0_connector、plugins/_browser等的统一方法论——它们共享同一套Tool基类、同一套Response契约与同一套 DOX 同步纪律。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero 的 response 工具深度解析：从 `ResponseTool` 实现到消息循环终止机制
Agent Zero 的 response 工具深度解析从ResponseTool实现到消息循环终止机制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读response是 Agent Zero 框架中承担最终答复职责的核心工具tool当智能体完成一项任务、或当前没有活跃任务时它把最终结果输出给用户并凭借break_loop语义终止消息循环。本文以仓库中的 tools/response.py.dox.md 为骨架结合 tools/response.py 的完整实现、helpers/tool.py 的工具基类契约、helpers/errors.py 的可修复异常体系以及 agent.py 的循环调度逻辑讲清楚该工具的参数契约、执行生命周期、错误自修复机制和测试验证方式。读完你不仅能透彻理解response工具的底层原理还能举一反三地掌握 Agent Zero 全部内置工具的统一实现规范。一、DOX 文档的定位工具职责的持久化契约Agent Zero 的tools/目录采用实现 DOX双文件扁平结构每个*.py文件旁边都伴随一个*.py.dox.md例如 tools/response.py 对应 tools/response.py.dox.md。DOXDocumentation of eXecution文件并非简单注释它记录的是该模块的职责、运行时契约、副作用与验证方式并要求在工具参数、输出结构、break_loop行为、干预intervention处理或 Prompt 指令发生变化时同步更新。针对response工具这份 DOX 文档明确锁定了以下契约职责向用户输出最终或中间阶段的智能体回复实现归属response.py持有运行时实现DOX 文件持有关于该实现的责任、契约、副作用与验证的持久化笔记依赖边界仅依赖helpers.errors与helpers.tool两个导入域变更要求工具参数、输出形状、break_loop行为、干预处理、Prompt 指令或副作用任何一项变化都必须同步更新 DOX。这种实现与契约分离、强制同步的模式让 Agent Zero 的工具在快速迭代中始终保有可审计的接口边界。二、ResponseTool类结构与生命周期钩子2.1 类声明与父类契约helpers/tool.py 定义了所有工具的共同基类Tool其构造签名接收agent、name、method、args、message与loop_data并声明了三个生命周期方法execute(**kwargs)抽象方法执行工具主体逻辑必须返回Responsebefore_execution(**kwargs)执行前钩子默认打印工具名与参数并创建日志对象after_execution(response, **kwargs)执行后钩子默认将结果写入历史hist_add_tool_result并更新日志。ResponseTooltools/response.py#L5正是这三个钩子的具体实现且刻意覆盖了父类的默认行为——尤其是after_execution它选择不写入历史、不输出内容见下文第四节。2.2 核心数据结构Responseexecute的返回值是 helpers/tool.py 中的 dataclassResponsedataclass class Response: message: str break_loop: bool additional: dict[str, Any] | None Nonemessage要交给 Agent 循环处理的文本break_loop是否终止消息循环response工具固定为Trueadditional可选的附加数据例如在responsesAPI 架构下可携带_responses_output_item见 agent.py#L1213-L1217。三、参数契约text优先、message兜底、否则自修复3.1 execute 的完整实现ResponseTool.execute的实现极其精简全部逻辑如下tools/response.py#L7-L14async def execute(self, **kwargs): for key in (text, message): message self.args.get(key) if isinstance(message, str) and message.strip(): return Response(messagemessage, break_loopTrue) raise RepairableException( response tool requires a non-empty top-level text or message string argument )它依次检查两个顶层字符串参数text首选参数。只要它是非空strip()后不为空的字符串就直接作为回复内容message兼容参数。当text缺失或为空白时回退使用失败路径两者都缺失或为空则抛出RepairableException。3.2 RepairableException让 Agent 自己修复参数RepairableException定义在 helpers/errors.py#L83-L86其类注释点明了设计意图An exception type indicating errors that can be surfaced to the LLM for potential self-repair.这是 Agent Zero 错误分层体系RepairableException/InterventionException/HandledException中的关键一环。当response工具因参数不合法而抛出该异常时Agent 主循环agent.py#L1180-L1187会将其转换为历史中的 warning 消息hist_add_warning把错误详情回写给 LLM让模型感知到刚才的工具调用格式有误从而自行修正参数并重试而不是直接崩溃终止任务。可以推断的设计权衡text/message双参数的存在是为了兼容历史 Prompt 输出而必须非空的强校验则防止智能体输出空白回复导致死循环或空内容持久化。四、before / after 钩子日志职责的迁移与收尾4.1 before_execution静默化tools/response.py#L16-L19 中的before_execution只剩一条注释和一个passasync def before_execution(self, **kwargs): # self.log self.agent.context.log.log(typeresponse, heading..., contentself.args.get(text, )) # dont log here anymore, we have the live_response extension now pass这段注释本身即是重要信息日志职责已经从工具内部迁出。早期版本在这里写typeresponse的日志现在改由live_response扩展负责实时响应的展示。这符合 Agent Zero 的扩展extension架构——UI 相关的实时输出统一收敛到扩展层工具本体保持纯净。4.2 after_execution标记日志完成tools/response.py#L21-L26 的after_execution同样不做历史写入与终端输出async def after_execution(self, response, **kwargs): # do not add anything to the history or output if self.loop_data and log_item_response in self.loop_data.params_temporary: log self.loop_data.params_temporary[log_item_response] log.update(finishedTrue) # mark the message as finished其唯一副作用是如果循环数据loop_data.params_temporary中存在log_item_response日志条目则将其标记为finishedTrue用于在 UI 上结束正在生成的状态。注释明确说明不向历史或输出追加任何内容——这正是response作为终端答复工具的语义内容只经break_loop路径返回给上层不再污染消息历史。对比父类 helpers/tool.py#L54-L59 的默认after_execution会hist_add_tool_result并打印结果可以清晰看到ResponseTool有意识地覆盖了这套默认行为。五、break_loopTrue消息循环的终止开关break_loop是Response契约中最具控制力的字段。ResponseTool无论走text还是message分支都固定返回break_loopTrue。Agent 主循环在 agent.py#L1222-L1224 与 agent.py#L1497-L1498 两处分别对应常规工具执行与responses架构路径统一处理if response.break_loop: self._clear_responses_pending_state() return response.message即一旦工具返回break_loopTrue循环立即返回response.message作为本轮的最终结果终止工具调用 → 模型再推理的迭代链条。这也解释了为什么 Prompt 规范要求仅在任务完成或没有活跃任务时才使用该工具。对照参考框架内绝大多数工具如plugins/_browser/tools/browser.py、plugins/_code_execution/tools/code_execution_tool.py、plugins/_document_query/tools/document_query.py都返回break_loopFalse把控制权交还给模型继续推理只有response与示例工具见 agents/_example/tools/response.py才设置break_loopTrue。这一对比恰好勾勒出 Agent Zero 的循环语义工具默认不打断推理仅答复拥有终止权。六、Prompt 指令模型视角的使用规范工具的实现契约之外Agent Zero 还通过 Prompt 模板约束模型的调用行为。prompts/agent.system.tool.response.md 给出了模型视角的完整规范### response: final answer to user ends task processing use only when done or no task active args: text default to balanced, concise answers: informative but tight, not terse and not verbose.核心约束包括语义向用户输出最终答复结束任务处理使用时机仅当任务完成或没有活跃任务时参数text风格基调平衡而简洁——信息量充足但紧凑既不生硬简短也不冗长。并附带标准调用示例JSON{ thoughts: [ ... ], headline: Providing final answer to user, tool_name: response, tool_args: { text: Answer to the user } }此外prompts/agent.system.response_tool_tips.md 补充了一条关键提示对于长篇幅的既有文本不要重新编写而应使用§§include(path)语法直接引用文件内容。这保证了最终答复可读性与上下文窗口的平衡。七、验证与测试如何回归检查该工具DOX 文档明确要求行为变更后需运行针对性测试验证工具与 Prompt 契约无聚焦测试时则做冒烟测试smoke-test agent 执行。文档记录的关联测试包括tests/chunk_parser_test.pytests/rate_limiter_test.pytests/test_browser_agent_regressions.pytests/test_chat_compaction.pytests/test_dirty_json.pytests/test_download_toast_regressions.pytests/test_fasta2a_client.pytests/test_fastmcp_openapi_security.py这些测试大多并非直接单测ResponseTool而是覆盖与response输出链路相邻的契约面——例如break_loop返回的消息如何进入聊天持久化test_chat_compaction、错误参数触发的自修复路径、以及 WebUI 下载/推送等下游消费行为。验证策略的核心思路是通过端到端与相邻模块的回归间接保障response的契约不被破坏。八、源码级全景回顾将以上剖析汇总为一张对照表即可看清response工具在 Agent Zero 中的完整坐标关注点依据结论职责tools/response.py.dox.md输出最终/中间答复拥有终止循环的能力类结构tools/response.py#L5ResponseTool(Tool)实现三个生命周期钩子参数契约tools/response.py#L7-L14text优先、message兜底、均非空否则抛RepairableException返回结构helpers/tool.py#L11-L15Response(message, break_loopTrue, additionalNone)循环终止agent.py#L1222-L1224 / agent.py#L1497-L1498break_loopTrue时返回消息并结束本轮错误自修复helpers/errors.py#L83-L86RepairableException转 warning 回写 LLM日志收尾tools/response.py#L21-L26标记log_item_response为 finished不写历史Prompt 规范prompts/agent.system.tool.response.md仅任务完成时使用参数为text风格平衡简洁长文本技巧prompts/agent.system.response_tool_tips.md用§§include(path)引用既有文件从这份实现中可以看出 Agent Zero 工具设计的三个鲜明特征契约文档化DOX 与实现强制同步、错误可修复化以RepairableException驱动 LLM 自纠错、副作用最小化日志交给扩展层、历史交给上层循环。理解了response也就掌握了阅读 Agent Zero 其余全部内置工具与插件工具如plugins/_a0_connector、plugins/_browser等的统一方法论——它们共享同一套Tool基类、同一套Response契约与同一套 DOX 同步纪律。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考