Hermes Agent 自定义工具集实战：一个工具从注册到被 Agent 调用的全链路

Hermes Agent 自定义工具集实战一个工具从注册到被 Agent 调用的全链路【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent你想让 Agent 批量改写文档大小写翻遍内置工具没现成的。Hermes Agent 的扩展开发里需求分两层工具Tool是真正干活的函数自定义工具集Toolset决定 Agent 能看见哪些工具。两层分清注册和调试才不乱。心智模型Tool 干活Toolset 发工牌打开toolsets.py所有工具集都挂在同一个TOOLSETS字典上。每个集合就三个字段description写给人和文档看tools列出这个集合直接包含的工具名includes声明它还要把哪些别的工具集合并进来。web: { description: Web research and content extraction, tools: [web_search, web_extract], includes: [] }可以把工具集想成文件夹tools是放进去的文件includes是软链接指向另一个文件夹展开时一起算进来。另外还有一个_HERMES_CORE_TOOLS它是所有平台都默认继承的公共基础包各平台工具集在它之上做加减。一条主线从写函数到 Agent 真正调起它先写处理函数。新建tools/text_transform.py实现真正干活的逻辑。Hermes 的硬性约定是所有 handler 必须返回 JSON 字符串注册层负责 schema 收集、分发、可用性检查和错误包装。import json def text_transform(text: str, transform_type: str uppercase) - str: if transform_type uppercase: return json.dumps({success: True, data: text.upper()}) return json.dumps({success: True, data: text.lower()})这段代码里最值得记住的是返回值必须是 JSON 字符串注册系统只替你兜错误包装不兜数据格式。把参数描述成 JSON Schema然后注册。Schema 就是模型看到的函数说明书name / description / parameters一样都不能少。from tools.registry import registry registry.register( nametext_transform, toolsettext_processing, schema{name: text_transform, description: 转换文本大小写, parameters: {type: object, properties: {text: {type: string}, transform_type: {type: string, enum: [uppercase, lowercase]}}, required: [text]}}, handlerlambda args, **kw: text_transform(args.get(text, ), args.get(transform_type, uppercase)), )这段代码里最值得记住的是tools/下任何带顶层registry.register()调用的 .py 文件都会被自动发现并导入但自动发现只注册 schema不代表工具已经暴露给 Agent。把工具挂进工具集。打开toolsets.py把工具名写进某个集合的tools里——这是唯一必须手动做的装配步骤。TOOLSETS { text_processing: { description: 文本处理工具集, tools: [text_transform], includes: [web] }, }这段代码里最值得记住的是工具名没出现在任何 toolset 里Agent 就永远看不见它挂集合不是可选项。验证并启动。先跑校验函数确认名字和依赖都没拼错再用命令行指定工具集起会话from toolsets import validate_toolset validate_toolset(text_processing)hermes run --toolset text_processing这段代码里最值得记住的是validate 失败十有八九是工具名拼错或者includes指向了一个不存在的集合名。进阶玩法与排坑清单运行时创建工具集不改文件也能加不想为了一个临时组合去改toolsets.py再重启create_custom_toolset可以在运行时直接挂一个动态工具集tools和includes的写法与静态定义完全一致会话结束即失效适合做实验性组合。from toolsets import create_custom_toolset create_custom_toolset( namemy_dynamic_toolset, description运行时创建的动态工具集, tools[text_transform], includes[web], )先问一句工具到底在不在症状是 Agent 报工具不存在。原因多半不是没注册而是check_fn或requires_env没满足——比如工具依赖的 API key 没配。解法调一次registry.check_tool_availability()它会分开返回可用和不可用的工具两组名字缺什么一目了然。用依赖树排查 toolset includes 指向问题症状是工具明明注册了某个平台下却用不了。原因通常是 includes 链条上有一环指错了集合名或者被平台配置关掉了。解法print_toolset_tree(text_processing)会把依赖树递归打出来includes 断在哪一层、哪些工具没被展开看一眼树就清楚。 工具注册了为什么 Agent 看不见症状registry.register()执行成功、validate 也过了Agent 就是不调用。原因注册只把 schema 放进注册表暴露给 Agent 的开关在工具集那一层。解法确认工具名出现在某个 toolset 的tools里如果工具只给自己用更干净的路是走插件——在~/.hermes/plugins/name/__init__.py里用ctx.register_tool(...)注册插件工具集会被自动发现完全不用动核心文件。收尾速查表与延伸入口 不知道往哪下手时先查这张表我想做什么该改哪个文件调哪个函数写一个新核心工具tools/your_tool.pyregistry.register(...)把工具暴露给 Agenttoolsets.py写进TOOLSETS的tools校验工具集定义toolsets.pyvalidate_toolset(name)运行时动态建工具集无需改文件create_custom_toolset(...)按平台开关工具config.yaml或 CLIhermes tools延伸入口从toolsets.py和tools/registry.py读起回归用例在tests/test_toolsets.py。工具是肌肉工具集是神经系统——挂对位置Agent 才会真的伸手去用。【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考