Hermes Agent 自定义工具集实战注册到调用的最短路径【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent你的 Agent 需要查询内部订单库但 Hermes Agent 的内置工具只覆盖 Web 搜索、终端与文件操作没有业务数据查询的入口。两个常见错误做法把业务逻辑塞进系统提示词脆弱且模型会记错字段让模型在终端里现写 SQL不安全且表结构一改就报错。正确路径是把专用工具注册进注册表、再挂到自定义工具集上——这正是 Hermes Agent 留出的扩展点工具是能力的最小单元工具集toolset是会话级的能力开关。本文以一个 SQLite 查询工具为例讲完注册、挂载到会话启用全过程适合已安装 Hermes Agent、想给 Agent 加第一个自定义工具的开发者。读懂注册与工具集的两层结构Hermes Agent 的工具系统分两层tools/registry.py维护全局注册表记录每个工具的名称、JSON Schema 与处理函数toolsets.py用一个TOOLSETS字典把工具按名字归入命名工具集如web、terminal、file。可以类比成仓库与工单注册表是库存工具集是工单——会话启动时只有出现在工单上的工具才会进入发给模型的请求。由此得出关键规则工具不在任何工具集里就是注册了但没暴露模型根本看不到它。核心接口只有一个调用# tools/registry.py 中的注册接口节选 registry.register( nameorder_lookup, # 模型可见的工具名 toolsetops, # 归属哪个工具集 schemaORDER_LOOKUP_SCHEMA, # 参数契约JSON Schema handlerorder_lookup, # 实际执行函数 )工具集声明就是一个字典条目tools字段列工具名includes字段声明依赖的其他工具集。写一个自注册工具工具文件放在tools/目录schema、handler、注册调用同文件共处import json, sqlite3 from tools.registry import registry def order_lookup(order_id: str, **kwargs) - str: # 参数化查询模型传入的 order_id 不可信防注入 row sqlite3.connect(/data/orders.db).execute( SELECT status, amount FROM orders WHERE id ?, (order_id,)).fetchone() return json.dumps({order_id: order_id, row: list(row) if row else None}) ORDER_LOOKUP_SCHEMA { type: function, function: { name: order_lookup, description: 按订单号查询内部订单的状态与金额, parameters: {type: object, properties: {order_id: {type: string}}, required: [order_id]}, }, } registry.register( nameorder_lookup, toolsetops, schemaORDER_LOOKUP_SCHEMA, handlerorder_lookup, )保存后无需任何手动 importmodel_tools加载时tools/registry.py 的discover_builtin_tools()会自动导入tools/下所有含顶层registry.register()调用的文件。此时 Agent 仍看不到该工具——名字还没进任何工具集。把工具挂进工具集打开 toolsets.py在TOOLSETS字典中加一条# toolsets.py TOOLSETS { ... ops: { description: 内部运维工具, tools: [order_lookup], }, }随后运行hermes toolscurses 界面即可看到新的ops工具集并为目标平台勾选启用或写进配置文件# ~/.hermes/config.yaml tools: cli: enabled: [ops]多文件协作时各文件职责如下文件职责tools/order_tool.py工具实现、schema 与注册加载时自动导入toolsets.py声明ops工具集及其包含的工具tools/registry.py中央注册表扫描tools/*.py完成自发现model_tools.py按启用工具集构建发给模型的 tools 列表~/.hermes/config.yaml按平台启用/禁用工具集在会话里验证工具hermes --toolsets ops -q 查一下订单 1024 的状态预期效果模型发出order_lookup(order_id1024)调用返回含 status、amount 的 JSON。若模型转而用终端敲sqlite3说明工具集没启用先回查 config 与hermes tools界面。生产环境三条注意handler 必须返回字符串通常 JSON 序列化这是与 model_tools.py 的契约直接返回 dict 会在序列化处报错。schema 的 description 不要提及其他工具集的工具名如可配合 web_search 使用——该工具可能在当前会话未启用会诱导模型幻觉出不存在的调用。工具依赖外部服务时给register()传check_fn依赖缺失返回 False该工具即被静默隐藏而不是运行时报错。排查工具集三个高频坑坑一工具注册了却从不调用。现象注册表里能查到工具会话中模型却从不调用。 原因⚠️ 工具名没进toolsets.py的任何工具集列表——注册只是入库不等于暴露。 修复把名字加进工具集重开会话生效。坑二模型调用不存在的工具。现象模型发出当前会话未启用工具的调用报错或空转。 原因某工具 schema 描述里点名了其他工具集的工具误导模型。 修复描述保持自足确需交叉引用在model_tools.py的get_tool_definitions()后处理里按启用状态动态注入。坑三会话中换工具集后成本陡增。现象对话中途增删工具集下一轮请求延迟与费用明显上升。 原因tools 列表是提示缓存前缀的一部分工具集构成一变前缀缓存全部失效。 修复工具集在会话开始前定好中途需要变更就开新会话。压降 schema 的 token 开销业务工具放命名工具集别塞进_HERMES_CORE_TOOLS——那是所有平台默认继承的基础包放进去意味着每个平台的每个会话都为这份 schema 付 token 费。schema 字节数每次请求都会注入用/context all命令可查看按工具集拆分的 schema 成本description 写触发条件即可不写营销式长句。若不想改动主仓库代码下一步可以看插件工具插件工具集由系统自动发现启用或禁用时无需触碰toolsets.py。【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考