Agent Zero 工具开发指南从 Tool 基类契约到插件化分发与验证【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本指南以 skills/a0-development/references/tools.md 为核心骨架系统讲解 Agent Zero 框架中工具Tool的完整开发契约包括Tool基类与Response返回协议、工具的发现与分发路径、四种存放位置的选择策略、提示词Prompt契约、进度上报与干预流程以及配套 DOX 文档与测试验证规范。读完本文后你将掌握在 Agent Zero 中新增一个自定义工具、将其正确注册为插件工具并为模型编写可用提示词的全部实操方法并理解工具执行生命周期背后的源码原理。工具在 Agent Zero 中的地位在 Agent Zero 中工具是 Agent 与外部世界交互的基本单元模型的每次函数调用都会落到某个具体工具上工具执行结果再写回消息历史构成模型发起调用 → 框架分发 → 工具执行 → 结果回填的闭环。与许多框架将工具写成普通函数不同Agent Zero 为工具定义了严格的类契约所有工具都派生自helpers.tool.Tool基类并实现统一的异步执行接口。这套契约的核心文件Source Anchors如下职责仓库路径工具基类与响应契约helpers/tool.py核心工具目录的 DOX 契约tools/AGENTS.md工具分发路径执行入口agent.py方法式工具的参考实现tools/skills_tool.py示例 profile 工具agents/_example/tools/example_tool.py提示词组织规范prompts/AGENTS.md工具基类契约Tool 与 Response最小可运行工具所有工具都从helpers.tool.Tool派生并实现async def execute(self, **kwargs) - Response。最小实现如下from helpers.tool import Tool, Response class MyTool(Tool): async def execute(self, **kwargs) - Response: return Response(messagedone, break_loopFalse)从源码看Tool是抽象基类execute被abstractmethod装饰见 helpers/tool.py因此任何没有实现execute的子类都无法被实例化这从语言层面保证了工具契约不会被绕过。Response 返回协议Response是一个dataclass见 helpers/tool.py字段含义如下字段含义message作为工具结果追加到消息历史并回显给 Agent 的文本break_loop为True时终止当前消息循环如任务完成停止思考additional可选的附加元数据随工具结果一起写入默认Nonebreak_loop的执行语义可以在分发代码中得到验证在 agent.py 的_execute_tool_request中只有当response.break_loop为真时框架才会清空 pending 状态并直接返回工具消息终止本轮循环。工具实例的注入字段Tool.__init__的签名见 helpers/tool.py表明每个工具实例在构造时都会收到以下上下文agent当前 Agent 实例可访问历史、上下文、配置等name工具名称即模型调用时的tool_namemethod可选的方法名用于方法式工具method-style tool例如skills_tool:load中的loadargs模型传入的参数字典message触发本次工具调用的原始消息loop_data当前消息循环的状态数据。其中method参数是方法式工具的关键skills_tool将多个动作list、search、load、read_file收敛在同一个工具类中通过action/method参数分派见 tools/skills_tool.py这避免为每个动作单独创建一个工具文件。工具发现与分发路径当模型请求调用某个工具时框架按以下链路完成分发MCP 工具优先_execute_tool_request首先尝试从 MCP 配置中查找同名工具见 agent.py若命中则直接使用 MCP 工具本地工具回退未命中 MCP 时调用self.get_tool(...)按 profile 层级搜索文件get_tool通过subagents.get_paths(self, tools, name .py)沿 Agent 的文件夹层级搜索名为tool_name.py的模块见 agent.py找到后用extract_tools.load_classes_from_file加载其中的Tool子类兜底 Unknown若任何路径都找不到则实例化tools.unknown.Unknown作为兜底向 Agent 说明工具不存在。工具执行前后还接入了扩展点与干预点完整执行顺序见 agent.py为handle_intervention() # 执行前检查暂停/干预 tool.before_execution() # 打印调用参数、创建日志对象 extension tool_execute_before # 执行前扩展钩子 response await tool.execute() # 执行工具本体 extension tool_execute_after # 执行后扩展钩子 tool.after_execution(response) # 清理结果写入历史并回显 handle_intervention() # 执行后再次检查 if response.break_loop: return # 终止循环值得注意before_execution会把每个参数通过tool_output_update扩展实时输出到界面并打印彩色日志见 helpers/tool.pyafter_execution则负责把结果文本sanitize_string后写入历史hist_add_tool_result并更新日志对象见 helpers/tool.py。因此工具实现者无需自己处理日志与历史回填。工具的存放位置与选择策略新工具放在哪里直接决定它的作用域与分发优先级。框架按以下位置查找工具优先级从高到低取决于 profile 层级位置用途tools/核心框架工具只承载框架自带行为不建议直接新增plugins/plugin/tools/随插件分发的内置插件工具usr/plugins/plugin/tools/用户级插件工具自定义插件开发的首选位置agents/profile/tools/profile 级局部工具需先验证当前版本的发现机制再依赖示例仓库现状印证了这一划分核心工具如a2a_chat.py、search_engine.py、skills_tool.py等直接位于 tools/ 下而大量能力编辑器、浏览器、邮件、语音等都以插件形式打包在 plugins/ 各目录的tools/子目录中。参考 tools/AGENTS.md 的 Ownership 声明绝大多数新工具应当打包进插件而不是直接塞进根级tools/否则会破坏核心目录只承载框架行为的边界。Prompt 契约让模型学会使用工具仅有 Python 类还不够——模型必须知道工具的存在、JSON 参数形状与使用时机。因此每个工具都需要一个面向 Agent 的提示词片段Prompt Fragment框架按文件名约定自动装载agent.system.tool.tool_name.md。常见放置位置核心工具提示词prompts/agent.system.tool.tool_name.md如 prompts/agent.system.tool.a2a_chat.md插件工具提示词plugins/plugin/prompts/agent.system.tool.tool_name.md用户插件提示词usr/plugins/plugin/prompts/agent.system.tool.tool_name.mdprofile 覆盖提示词agents/profile/prompts/agent.system.tool.tool_name.md。参考仓库中的示例工具agents/_example/tools/example_tool.py 对应提示词 agents/_example/prompts/agent.system.tool.example_tool.md其中明确写道该文件因命名为agent.system.tool.*.md而自动被包含进系统提示词并给出了模型的调用 JSON 示例{ thoughts: [ Lets test the example tool..., ], headline: Testing example tool, tool_name: example_tool, tool_args: { test_input: XYZ, } }prompts/AGENTS.md 进一步给出提示词开发红线不得在模板中放入密钥、真实 API Key 或用户私有数据修改占位符与文件名前必须先阅读渲染路径prompt 变更会改变 Agent 行为编辑应保持窄而有意。变更纪律凡是改动工具名、参数形状、输出行为、安全规则或break_loop语义都必须同步更新对应的提示词片段与测试。这是因为提示词与代码是同一契约的两面只改一边必然造成模型调用与实际实现脱节。进度上报与人工干预对长耗时或需要外部结果的工作流工具实现者应遵循以下规范await self.set_progress(...)通过tool_output_update扩展把进度实时推送到界面同时写入本地self.progress见 helpers/tool.pyself.add_progress(...)仅在本地累积进度文本不触发扩展事件见 helpers/tool.py适用于不希望频繁刷界面的场景暂停/干预对于长运行或依赖外部结果的工作流按 tools/AGENTS.md 的 Local Contracts应在关键节点使用await self.agent.handle_intervention(...)定义见 agent.py让暂停/干预流程生效。分发代码在before_execution前后、execute前后共插入四次干预检查点工具执行期间 Agent 随时可以被安全暂停安全规范工具输出在写入日志或返回前必须脱敏/掩码sanitize 与 mask严禁把密钥、凭据泄露进日志或消息历史。after_execution中对message调用sanitize_string正是这一规范的底层防线。核心工具的 DOX 文档契约Agent Zero 对根级核心工具实施文件级 DOXfile-documented DOX制度规则tools/下的每个直接*.py工具模块必须有同目录下同名追加.dox.md的配套文档即tools/*.py↔tools/*.py.dox.md例如 tools/search_engine.py 对应 tools/search_engine.py.dox.md、tools/a2a_chat.py 对应 tools/a2a_chat.py.dox.mdDOX 文件拥有的内容工具用途、参数/概念、输出与break_loop行为、副作用、重要辅助依赖、提示词契约说明与验证指引见 tools/AGENTS.md Local Contracts同步义务工具模块的新增、删除、改名或行为变更必须与配套 DOX 在同一变更中完成不允许删除/改名后遗留过期 DOX边界插件工具的工具文档属于该插件自己的 docs 或 DOX 契约不应写入根级tools/从而保持核心目录文档的纯粹性。验证与测试工具改动后的验证路径分为四层定向工具测试修改工具或其提示词契约后运行该工具的针对性测试提示词/快照测试当工具指令或输出形状变化时运行 prompt/snapshot 相关测试防止系统提示词预算或渲染结果漂移可参考 tests/test_prompt_protocol.py 等测试DOX 覆盖检查对根级核心工具用脚本或 shell 循环逐一核对每个tools/*.py都有同名.py.dox.md这正是tools/AGENTS.mdVerification 一节要求的标准做法插件级检查若工具属于插件作用域还需按该插件自身 AGENTS.md 执行插件专属检查项。实战从零新增一个插件工具的 Checklist综合上述契约在 Agent Zero 中新增一个自定义插件工具的最小工作流如下在插件目录推荐usr/plugins/plugin/tools/创建my_tool.py定义class MyTool(Tool)并实现async def execute(self, **kwargs) - Response依据执行语义正确设置Response(message..., break_loop...)需要元数据时补充additional在usr/plugins/plugin/prompts/创建agent.system.tool.my_tool.md写明工具名、JSON 参数形状、使用时机与示例调用长流程中使用await self.set_progress(...)上报进度、await self.agent.handle_intervention(...)尊重暂停/干预输出前对敏感信息脱敏为该工具补充插件内的文档DOX 或 docs并运行定向测试、prompt/snapshot 测试与插件专属检查。遵循以上五步即可让一个新的工具能力被框架自动发现、被模型正确调用、被日志系统完整记录并保持与 Agent Zero 核心契约长期兼容。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考