OmniAgent开发者指南如何为Agent编写自定义工具与扩展从Tool基类到Manifest插件【免费下载链接】OmniAgentAn agent capable of self-evolving and dynamically hardening security项目地址: https://gitcode.com/gh_mirrors/om/OmniAgentOmniAgent是一个开源自进化 Agent 框架让 Agent 随交互持续进化、让安全随使用动态加固。本指南面向新手开发者带你从零开始为 OmniAgent 编写自定义工具Tool与插件扩展Extension先理解Tool基类与ToolResult的返回契约再掌握ToolRegistry注册机制最后学会用plugin.yamlManifest 打包完整插件通过事件订阅与工具钩子深度嵌入 Agent 生命周期。一、先认识工具系统Tool基类与ToolResultOmniAgent 的所有能力读文件、跑命令、搜网页都以工具为单位挂载到 Agent 上。工具系统的入口在 omniagent/tools/base.py核心只有两个概念概念作用关键点Tool抽象基类定义工具的统一接口必须实现execute()与_get_parameters_schema()ToolResult数据类承载执行结果包含success、output、error、metadata四个字段ToolRegistry注册表管理所有已注册工具通过register()/get()/get_schemas()操作只需三步就能写一个合法工具继承Tool在构造函数中调用super().__init__(name..., description...)description会直接展示给 LLM请写清楚什么时候该用这个工具实现execute(params) - ToolResultparams是 LLM 按 Schema 传来的参数字典返回ToolResult(successTrue, output...)即可出错时返回successFalse并带上error信息实现_get_parameters_schema()返回 OpenAI function calling 格式的 JSON Schema例如{type: object, properties: {...}, required: [...]}。一个真实的参照物是内置的 Bash 工具 omniagent/tools/bash_tool.py它的参数 Schema 声明了command必填、timeout、background三个参数执行前还会做危险命令拦截——这是写工具时值得借鉴的安全习惯。新手提示get_schema()方法会自动把name、description、parameters组装成 LLM 可识别的格式你不需要手写 JSON 字符串。二、注册工具ToolRegistry与Agent内置注册工具写好之后需要挂到 Agent 上才能被调用。ToolRegistry提供四个方法见 tools/base.pyregister(tool)按工具名注册同名会覆盖get(name)按名查找list_tools()/get_schemas()列出全部工具及其 Schema供 LLM 调用时使用。在 Agent 启动时OmniAgent 会批量注册一批内置工具注册点集中在 omniagent/agents/reflexion.pyself.registry.register(BashTool(work_dirself.work_dir, allow_dangerousFalse)) self.registry.register(ReadTool(work_dirself.work_dir)) self.registry.register(WebFetchTool())你也可以看到 Agent 暴露了register_tool()方法reflexion.py它就是对registry.register()的轻量封装——扩展系统注册的自定义工具正是走这条通道。三、扩展插件Extension基类与ExtensionAPI当需求不只是多一个工具而是想监听事件、拦截工具调用、读取配置时就该用扩展Extension了。基类在 omniagent/extensions/base.py生命周期只有两个方法方法时机用途on_load(api)扩展被加载时注册工具、订阅事件、添加钩子on_unload()扩展被卸载时清理资源加载时框架会注入一个ExtensionAPIbase.py它给了你五把钥匙api.register_tool(tool)把自定义工具挂进ToolRegistryapi.subscribe(event_type, handler)订阅 Agent 生命周期事件api.add_before_tool_hook(hook)在工具执行前拦截可阻止执行api.add_after_tool_hook(hook)在工具执行后改写结果api.config/api.work_dir读取全局配置与工作目录。3.1 事件系统订阅Agent生命周期事件类型定义在 omniagent/agents/events.py覆盖四个粒度层级层级事件典型用途Agent 生命周期agent_start/agent_end会话统计、埋点Turn 生命周期turn_start/turn_end单轮耗时监控消息生命周期message_start/update/end流式 UI 联动工具生命周期tool_execution_start/end工具审计日志此外还有压缩compaction_*与审批approval_requested/resolved事件。EventBus的 handler 以asyncio.gather并发执行单个 handler 抛异常不会影响其他订阅者——写扩展时可以放心使用。3.2 工具钩子拦截与改写执行钩子机制在 omniagent/agents/hooks.pybefore 钩子返回ToolHookResult(blockedTrue, block_reason...)即可短路执行任何钩子拦截都会立即终止见 hooks.py 的run_beforeafter 钩子通过override_content替换最终结果文本适合脱敏、审计标记。这为企业级安全管控类插件提供了标准挂载点。四、Manifest插件用plugin.yaml打包你的扩展有了扩展类最后一步是让它被自动发现。加载器ExtensionLoader定义在 omniagent/extensions/init.py它扫描扩展目录默认~/.omniagent/extensions/下的两个模式4.1 标准模式plugin.yaml Manifestmy_plugin/ ├── plugin.yaml # 清单文件 └── my_plugin.py # 扩展模块Manifest 的解析逻辑在 omniagent/extensions/manifest.py字段非常少字段必填说明name否缺省时取目录名version否默认0.1.0module否入口模块文件名缺省等于nameclass否扩展类名缺省为Extensiondescription否插件描述加载器会按 Manifest 动态import对应模块实例化指定的Extension子类并调用on_load(api)。加载失败只记录警告、不会拖垮整个 Agent见init.py。4.2 简写模式extension.py如果目录里没有plugin.yaml只要存在extension.py加载器会自动扫描其中第一个Extension子类并加载_load_direct_extension。写小插件时这一模式最省事。五、最佳实践清单写好 description它是 LLM 判断该不该调用你的工具的唯一依据写清场景与边界。永远优雅地失败捕获异常并返回successFalse的ToolResult让 Reflexion 反思层有机会自我修复而不是把 traceback 抛给 Agent 主循环。Schema 保持精简必填参数放进required可选参数给default避免 LLM 因参数臆测而调用失败。高危操作内置拦截参考 bash_tool.py 的危险命令黑名单在execute()内先自检再依赖外层四层安全扫描兜底。卸载时清理在on_unload()中释放连接、取消订阅避免插件热更新时资源泄漏。小结从Tool基类到ToolRegistry再到Extensionplugin.yamlManifestOmniAgent 的扩展体系可以概括为一条链路工具是原子能力注册表让 Agent 看见它扩展让它在正确的事件点被安全地触发。掌握 tools/base.py 的接口契约与 extensions/manifest.py 的清单格式你就可以开始为这个自进化 Agent 贡献第一个自定义插件了。【免费下载链接】OmniAgentAn agent capable of self-evolving and dynamically hardening security项目地址: https://gitcode.com/gh_mirrors/om/OmniAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考