Hermes Agent 扩展开发实战：如何快速注册自定义工具并组装工具集
【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent
Hermes Agent 是一款开源 AI 代理框架，其内置的工具集（Toolset）系统管理着搜索、终端等 40 余种工具。内置能力再全，也总有覆盖不到的业务场景——比如你希望对文档做特定格式的大小写转换、批量统计字数，这些都得自己动手加。读完这篇文章，你能在 30 分钟内完成 Hermes Agent 自定义工具集的完整链路：注册一个自己的工具、把它组装进可复用的工具集、并掌握验证与排错手段。
原理先行：工具、工具集、注册表各是什么
动手之前先建立心智模型，用工具箱来类比：
- 工具（Tool）：一把单独的螺丝刀。它由三样东西构成——干活的 Python 函数（handler）、描述输入参数的 JSON Schema，以及在注册表里的登记记录。
- 工具集（Toolset）：工具箱里的一个抽屉。一个抽屉可以放多把工具，也可以引用另一个抽屉（嵌套包含），方便整组拿取。
- 注册表（Registry）：仓库的台账。工具只有登记在册，代理运行时才"借得到"它；工具集本身只是抽屉的布局图，真正能用的前提是抽屉里的工具都已经在台账上。
技术定义对应到代码：工具集统一声明在 toolsets.py 的字典里，每个条目有description、tools（直接包含的工具名列表）、includes（依赖的其他工具集）三个关键属性；工具则通过 tools/registry.py 中的registry.register()方法登记。
最短路径：5 分钟注册一个自定义工具
以文本大小写转换为例。先写处理函数并完成注册——注意toolset参数要指向你打算归属的工具集名，注册时就会和抽屉绑定：
from tools.registry import registry def text_transform(args): text = args.get("text", "") mode = args.get("transform_type", "uppercase") return text.upper() if mode == "uppercase" else text.lower() registry.register( name="text_transform", toolset="text_processing", schema=TEXT_TRANSFORM_SCHEMA, handler=text_transform, )Schema 负责告诉代理"这个工具吃什么参数"，enum约束取值范围，required保证必填项不会被漏传：
TEXT_TRANSFORM_SCHEMA = { "name": "text_transform", "description": "转换文本大小写", "parameters": { "type": "object", "properties": { "text": {"type": "string"}, "transform_type": {"type": "string", "enum": ["uppercase", "lowercase"]}, }, "required": ["text"], }, }两段拼起来就是一个可运行的最小工具：函数负责执行，Schema 负责契约，注册负责上架。
进阶组装：工具集的组合、复用与动态创建
用 includes 实现抽屉套抽屉
工具集的价值在于复用。在 toolsets.py 的TOOLSETS字典里新增条目，includes可以引用任意已有工具集，依赖会逐层展开：
TOOLSETS = { # ... 内置条目 "text_processing": { "description": "文本处理：大小写转换、字数统计", "tools": ["text_transform", "word_count"], "includes": ["web"], # 复用 web 工具集 }, "content_creation": { "description": "内容创作综合工具集", "tools": ["text_rewrite"], "includes": ["text_processing"], # 间接带上 web }, }组装好之后，启动时指定工具集即可生效：
hermes run --toolset text_processing运行时动态创建工具集
不想改源码文件时，可以用create_custom_toolset在运行时直接创建：
from toolsets import create_custom_toolset create_custom_toolset( name="my_dynamic_toolset", description="运行时创建的动态工具集", tools=["text_transform"], includes=["web", "vision"], )适合做灰度验证：先在运行时拼一个临时工具集跑通流程，确认没问题再固化到toolsets.py。
验证与排错：工具集没生效时先查这三处
先验证，再启动
from toolsets import validate_toolset, get_toolset_info if validate_toolset("text_processing"): info = get_toolset_info("text_processing") print(info["description"], info["resolved_tools"])resolved_tools给出依赖展开后的完整工具清单——看到自己的工具名出现在里面，说明链路是通的。
三个高频错误
⚠️ 按出现频率排序：
工具没注册或名字对不上：工具集里写了
text_transform，但注册时用了transform_text。用注册表核对最可靠：available, unavailable = registry.check_tool_availability()unavailable非空就是工具集声明了未注册的工具。includes 引用了不存在的工具集：比如手误写成
"webs"。这种情况validate_toolset会直接报错，不要带病启动。Schema 缺
required或字段类型错误：工具能注册成功，但代理调用时传参失败。改完 Schema 后手动跑一次 handler 验证最稳妥。
用树形视图看结构
from toolsets import print_toolset_tree print_toolset_tree("content_creation")输出形如：
📦 content_creation: 内容创作综合工具集 Tools: text_rewrite Includes: text_processing: 文本处理 Tools: text_transform, word_count Includes: web: Web research tools嵌套层级一目了然，includes 写错层级、漏依赖的问题在这一屏里基本都能发现。
要点回顾
- 工具 = 函数 + Schema + 注册记录，三者缺一不可；
- 工具集是声明式的抽屉布局，
tools放具体工具，includes做复用； - 注册名必须与工具集中的引用严格一致，用
check_tool_availability()兜底； - 动态创建适合灰度验证，稳定后再固化到 toolsets.py。
延伸资源：工具集定义见 toolsets.py，注册系统源码见 tools/registry.py，测试写法参考 tests/tools/test_registry.py 和 tests/test_toolsets.py。
【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
