Agent Zero 工具系统开发契约与 DOX 文档规范以 tools/AGENTS.md 为纲解读工具实现、响应契约与验证流程【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读本文以 Agent Zero 仓库中 tools/AGENTS.md 为骨架系统讲解框架内置 Agent 工具Tool模块的归属边界、开发契约、输出/中断语义与文件级 DOX 文档规范。读者将掌握如何编写符合框架要求的Tool子类、正确返回Response、处理干预intervention与敏感信息并通过*.py.dox.md文件维护工具文档的长期同步——这些能力是扩展 Agent Zero 或为插件编写专属工具时的必备基础。一、工具目录的所有权与职责边界tools/目录是 Agent Zero 框架内置 Agent 工具core agent tool的唯一归属地。根据 tools/AGENTS.md 的定义目录职责拥有可供 Agent Zero agents 使用的核心工具实现并保持工具执行契约execution contracts、进度日志progress logging、干预处理intervention handling与工具结果格式化tool-result formatting的稳定。发现机制该目录下的工具模块由框架自动发现模块内部必须定义Tool子类。基类归属共享的工具基类与响应契约位于 helpers/tool.py不属于tools/目录本身。插件工具归属插件专属的工具应放在对应插件的tools/目录中而不是塞进框架根tools/。从当前仓库实际布局看tools/下共有约 20 个工具模块每个模块都遵循同名.py 同名.py.dox.md的成对组织方式例如 tools/notify_user.py 与 tools/notify_user.py.dox.md、tools/scheduler.py 与 tools/scheduler.py.dox.md。这种代码与文档同目录扁平共存的结构正是该目录被定义为file-documented DOX profile的直接体现。二、工具开发契约Tool 基类、execute 与 Response2.1 基类契约tools/AGENTS.md明确了两条硬性契约工具必须继承自helpers.tool.Tool必须实现async def execute(...)。查看 helpers/tool.py 的源码可以看到契约的完整形态dataclass class Response: message: str break_loop: bool additional: dict[str, Any] | None None class Tool: def __init__(self, agent, name, method, args, message, loop_data, **kwargs): self.agent agent self.name name self.method method self.args args self.loop_data loop_data self.message message self.progress abstractmethod async def execute(self, **kwargs) - Response: passTool构造函数接收 Agent 实例、工具名、方法名action、参数、消息与循环数据execute是每个工具必须实现的抽象异步方法其返回值类型必须是Response。2.2 返回值语义Response.message与break_loop所有工具执行完毕后必须返回 helpers/tool.py 中定义的Responsemessage返回给 Agent 的文本结果会写入消息历史after_execution中通过hist_add_tool_result记录。break_loop布尔值决定 Agent 主循环是否中断。True表示终止当前循环如 tools/response.py 在收到合法回复文本时返回break_loopTrueFalse表示继续循环绝大多数工具如此。以 tools/response.py 为例它从参数中查找text或message找到非空字符串即返回Response(message..., break_loopTrue)否则抛出RepairableException明确要求response tool requires a non-empty top-level text or message string argument。2.3 生命周期钩子基类还提供了三个可覆写的生命周期钩子helpers/tool.pybefore_execution打印Using tool日志、创建日志对象并逐参数输出nice_key将snake_case参数名转为易读标题。after_execution将工具结果清洗后写入历史、打印响应并更新日志。set_progress/add_progress通过tool_output_update扩展点向 WebUI 推送实时进度。tools/parallel.py的ParallelTool通过覆写before_execution置空self.log与after_execution只写历史、不产生额外日志来适配并行执行场景tools/response.py的ResponseTool则覆写after_execution以避免把回复内容重复写入历史并利用loop_data.params_temporary[log_item_response]标记消息完成状态。这些覆写示例展示了契约的灵活边界。三、本地契约细则干预、脱敏与非破坏性tools/AGENTS.md的 Local Contracts 部分对行为边界提出了四项要求每一项都能在源码中找到对应实现。3.1 干预处理intervention当工具是长时间运行或结果需要尊重暂停/干预流程时使用await self.agent.handle_intervention(...)。典型实现见 tools/search_engine.py搜索完成后调用await self.agent.handle_intervention(searxng_result)将搜索结果交给干预流程若 Agent 处于暂停状态则等待恢复。同样tools/wait.py 在计算等待时长之前先调用handle_intervention()确保等待工具尊重暂停语义。3.2 敏感信息脱敏在记录、返回或存储工具输出前必须对 secrets 进行清理或掩码。基类after_execution使用sanitize_string来自 helpers/strings.py清洗响应文本后再写入历史与日志helpers/tool.py。这与 prompts/agent.system.secrets.md 中关于密钥处理的提示约束共同构成日志不落敏感信息的完整防线。3.3 非破坏性约束除非工具契约明确说明该行为否则不得执行破坏性的文件系统或网络操作。即破坏性能力删除、覆盖、对外网络副作用必须显式写进工具的参数契约与 DOX 文档由调用方Agent / prompt 指令明确授权后才能执行而不是在工具内部隐式顺手完成。3.4 契约与实现的对应关系为便于核对下表汇总了当前仓库中典型工具与其契约要点的对应关系实现文件均在tools/下工具模块核心职责Response/break_loop 行为关键依赖notify_user.py向用户发送通知break_loopFalse校验type/priority/messagehelpers/notification.pyresponse.py产出最终回复并结束循环命中text/message时break_loopTruehelpers/errors.pyparallel.py并行启动/等待/取消子工具调用break_loopFalse支持wait、timeout、job_idshelpers/parallel_tools.pywait.py按时长或绝对时间等待break_loopFalse校验时间戳与时长helpers/wait.py、helpers/localization.pyscheduler.py创建/查询/更新/运行定时任务同上下文运行任务时break_loopTrue其余为Falsehelpers/task_scheduler.pysearch_engine.py通过 SearXNG 搜索并返回前 10 条结果break_loopFalse先过干预流程helpers/searxng.pyunknown.py未识别工具时生成纠错提示break_loopFalse附带可用工具列表extensions/python/system_prompt/_11_tools_prompt.py四、DOX 文件规范每个工具的配套文档义务tools/AGENTS.md用较大篇幅定义了本目录特有的 DOX 规范成对约束目录中每个直接*.py工具模块必须存在同名*.py.dox.md文件命名方式为在完整 Python 文件名后追加.dox.md。文档职责*.py.dox.md负责记录工具目的purpose、参数/概念arguments/concepts、输出与break_loop行为、副作用side effects、重要辅助依赖、prompt 契约注意事项与验证指引。同步义务工具模块新增、删除、重命名或行为变更时必须在同一次变更中同步更新其*.py.dox.md工具删除或重命名后不得遗留过期 DOX。以 tools/notify_user.py.dox.md 为例其结构完整覆盖了上述义务Purpose发送面向用户的通知、OwnershipNotifyUserTool及其execute方法、Runtime ContractsTool子类 Response返回、Key ConceptsAgentContext.get_notification_manager.add_notification、NotificationType、NotificationPriority、self.agent.read_prompt等被调用依赖、Work Guidance 与 Verification指向 tests/test_tool_action_contracts.py。4.1 为什么需要行为与文档同改从源码可以推断其设计动机tools/是扁平目录工具参数契约既被execute读取如notify_user读取message/title/detail/type/priority/timeout见 tools/notify_user.py又被 prompt 工具指令与 WebUI 引用。若仅改代码不改 DOX工具的真实参数与文档描述将脱节进而误导 Agent 的调用决策和下游开发者的理解。DOX 文件因此承担了权威契约快照的角色。五、工作指引简洁输出、复用 helpers、同步 Prompttools/AGENTS.md的 Work Guidance 给出三条实操准则输出克制工具输出要足够简洁以节省消息历史同时保留可执行的细节。例如search_engine只截取前 10 条结果SEARCH_ENGINE_RESULTS 10见 tools/search_engine.pyscheduler的查询类 action 用json.dumps(..., indent4)输出结构化任务列表。逻辑下沉 helpers可复用的解析、provider、文件系统或网络逻辑放在helpers/。scheduler.py把 cron 校验、时区归一化、任务计划解析等重逻辑全部委托给 helpers/task_scheduler.py自身只保留 action 分发与参数组装是薄工具、厚 helpers的范本。Prompt 同步工具名、参数或行为变更时必须同步更新 prompt 中的工具指令。框架通过 prompts/agent.system.tools.md 向 Agent 注入可用工具清单其中明确要求use ONLY the tools listed below. match names exactly. do NOT invent tool names因此工具改名/增删参数后若不同步 promptAgent 将调用到不存在的工具落入unknown.py的纠错流程。六、验证要求测试驱动与 DOX 覆盖率检查tools/AGENTS.md的 Verification 定义了变更后的验证路径定向工具测试改动工具或 prompt 契约后运行针对性测试。仓库中 tests/test_tool_action_contracts.py 与 tests/test_tool_request_normalization.py 等即覆盖工具参数归一化与行为契约。Prompt/快照测试工具指令或输出结构变化时运行 prompt 相关测试如 tests/test_prompt_protocol.py防止提示词与工具实际行为漂移。DOX 覆盖检查用脚本或 shell 循环验证每个tools/*.py都有匹配的tools/*.py.dox.md。这一步可落成一条简单的检查命令for f in tools/*.py; do [ -f ${f}.dox.md ] || echo MISSING DOX: ${f}.dox.md done该检查确保文件级文档覆盖file-level documentation coverage作为目录级质量门槛持续生效。七、扩展实践如何新增一个符合契约的 Agent 工具综合上述契约新增工具的完整步骤可以归纳为四步与tools/AGENTS.md的规则一一对应实现模块在tools/下创建your_tool.py定义class YourTool(Tool)并实现async def execute(self, **kwargs) - Response读取self.args中的参数返回合法的Response。同步 DOX在同一次变更中创建your_tool.py.dox.md写明 Purpose、Ownership类与方法签名、Runtime Contracts参数、输出、break_loop行为、副作用、Key Concepts被调用的 helpers与 Verification。同步 Prompt若工具暴露给 Agent 使用在对应 prompt 工具指令中登记名称与参数避免 Agent 调用未知工具。验证运行针对性测试与 DOX 覆盖检查若涉及子任务/并行/等待等语义参照 tools/parallel.py 与 tools/wait.py 的handle_intervention用法补齐干预处理。插件场景下将上述文件放入插件自己的tools/目录即可无需触碰框架根tools/这正体现了tools/AGENTS.md中Plugin-specific tools belong in plugintools/directories的边界划分。结语tools/AGENTS.md表面上是一份面向仓库开发者的维护文档实质上浓缩了 Agent Zero 工具系统的全部关键约定从Tool/Response基类契约、干预与脱敏边界到 DOX 配套文档与测试验证闭环。理解这份契约就等于掌握了为 Agent Zero 安全、规范地扩展任何工具能力的完整方法论。进一步研究可沿两条路径深入一是通读 helpers/tool.py 与 helpers/parallel_tools.py 等基座实现二是对照 tools/notify_user.py.dox.md 等 DOX 样板模仿其结构与粒度。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考