Hermes Agent自定义工具怎么开发：3步注册一个能用的自定义工具集-育师

Hermes Agent自定义工具怎么开发：3步注册一个能用的自定义工具集

【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent

你想让 Agent 回答客户问题之前，先自己去查一遍公司知识库，而不是每次都被你手动喂资料。Hermes Agent 自定义工具开发，拆开看就三件事：写一个函数、把它的名字挂进工具集、验证模型真的会调。这篇文章带你把这三件事完整跑一遍。

核心机制拆解：注册中心和工具集是怎么配合的

先给你 5 行代码，把框架里的真实配置抄出来感受一下：

# toolsets.py（内置配置节选） TOOLSETS = { "web": { "description": "Web research and content extraction tools", "tools": ["web_search", "web_extract"], }, }

工具集（Toolset）说白了就是给工具按场景打包的一份清单：tools字段列工具名，includes字段引用别的工具集。模型能"看见"哪些工具，完全由这份清单决定。

最小化的工具注册长这样——一个函数、一段参数描述、一次注册：

from tools.registry import registry def ping(args, **kw): return '{"success": true, "pong": true}' registry.register(name="ping", toolset="safe", schema=PING_SCHEMA, handler=ping)

数据流向一句话：模型决定调用工具 → dispatcher 按名字找到 handler → 你的函数跑完返回 JSON 字符串 → 结果回到模型继续推理。registry 负责 schema 收集、调用分发、可用性检查和错误包装，你自己只写中间那个函数。

类比我熟悉的东西：注册中心像后厨，学会了做菜；工具集像菜单——菜做出来了不写进菜单，客人（模型）是点不到的。

动手实操：把一个自定义工具从写出来到调起来

写一个能跑的工具函数

这一步，把函数、JSON Schema 和注册一次写完，全部放在一个新文件里。

# tools/text_transform.py import json from tools.registry import registry def text_transform(args): """把文本转成大写或小写""" text = args.get("text", "") if not text: return json.dumps({"success": False, "error": "text is required"}) mode = args.get("transform_type", "uppercase") result = text.upper() if mode == "uppercase" else text.lower() return json.dumps({"success": True, "result": result}) TEXT_TRANSFORM_SCHEMA = { "name": "text_transform", "description": "把文本转成大写或小写", "parameters": { "type": "object", "properties": { "text": {"type": "string", "description": "要转换的文本"}, "transform_type": {"type": "string", "enum": ["uppercase", "lowercase"]}, }, "required": ["text"], }, } registry.register(name="text_transform", toolset="text_processing", schema=TEXT_TRANSFORM_SCHEMA, handler=text_transform)

跑起来你应该看到：没有报错（注册动作发生在文件被导入时），此时工具已进注册中心——但模型还看不见它，别急，下一节补菜单。

handler 必须返回 JSON 字符串，返回 dict 会在解析结果时报错。

把工具挂进工具集

这一步，把工具名写进 toolsets.py，让它对模型可见。框架有自动发现机制：tools/下任何顶层带registry.register()调用的文件都会被自动导入，不用维护 import 列表；但工具集接线这一步是刻意的、手动的。

# toolsets.py —— 在 TOOLSETS 字典里加一项 "text_processing": { "description": "Text processing: case conversion", "tools": ["text_transform"], "includes": [], },

跑起来你应该看到：重启会话后模型的系统提示里多了一个text_transform的 schema，它能"看见"这个选项了。

工具集里写了一个不存在的工具名不会报错，只是默默不暴露——这类问题最隐蔽。

用 hermes tools 命令行调起来验证

这一步，确认工具集被当前平台启用，再让 Agent 实际调用一次。

hermes tools # 打开 curses 管理界面，找到 text_processing，确认已启用 # 或者在 config.yaml 里检查 tools.<platform>.disabled 是否把它禁了

跑起来你应该看到：界面列表里出现text_processing且处于启用状态。然后直接在会话里说"帮我把 hello 转成大写"，Agent 应回复HELLO。

如果模型不知道要调这个工具，先查 schema 的name和registry.register的name是否一字不差。

进阶与组合：工具集组合、includes 继承与插件动态加载

TOOLSETS里的includes是组合和继承的关键，它支持递归展开：

# toolsets.py —— 组合多个工具集 "content_creation": { "description": "Content creation workflow", "tools": ["text_transform"], "includes": ["web", "text_processing"], },

什么时候你会需要这个？当你想让某个平台或场景拥有一组固定搭配的能力时。每个平台的适配器启动时挑一个基础工具集（比如 Telegram 用messaging），再按includes把依赖的工具集全部展开——你改一处配置，整组能力跟着增减，不用逐平台复制工具列表。

另一条不碰核心代码的路是插件动态加载：在~/.hermes/plugins/<name>/下放plugin.yaml和__init__.py，用ctx.register_tool(...)注册，插件工具集会被自动发现，随用随启：

# ~/.hermes/plugins/kb_lookup/__init__.py def on_load(ctx): def kb_lookup(args): return '{"success": true, "result": "查知识库"}' ctx.register_tool(name="kb_lookup", toolset="kb", schema={"name": "kb_lookup", "description": "查内部知识库", "parameters": {"type": "object", "properties": {}}}, handler=kb_lookup)

什么时候你会需要这个？工具只在你自己的机器上用（查内部文档、读内部系统日志），就不该进tools/核心目录。插件可以按环境开关，多人协作时也不互相污染。

排错速查：自定义工具没生效怎么办

📋 高频问题对照表，按现象查改法：

现象	大概率原因	一行修复
模型从不调用这个工具	名字没出现在任何工具集里	在 toolsets.py 的`TOOLSETS`里加上它
调用报 handler 找不到	schema 的`name`与`register`的`name`不一致	让两个`name`一字不差
工具整个没暴露	缺环境变量，`check_fn`返回 false 被跳过	设置`requires_env`声明的变量
结果解析报错	handler 返回了 dict	改成`json.dumps(...)`
改了工具集不生效	当前会话没重载	重启会话，或跑`hermes tools`确认平台未禁用