Hermes-Agent 自定义工具开发实战

目录

• 📌 前言：为什么要自定义工具？
• ✅ 一、开发前准备（环境确认）
• 🛠️ 二、自定义工具开发步骤（核心流程）
• Step 1：找到工具存放目录
• Step 2：编写工具代码（核心文件）
• Step 3：关键代码解析（必看）
• Step 4：验证工具是否加载成功
• 🚀 三、测试自定义工具（实战验证）
• 🎯 四、进阶技巧（扩展功能）
• 1. 工具参数扩展（多参数示例）
• 2. 工具打包与分享
• 3. 调试工具（关键技巧）
• 💡 五、常见问题&解决方案
• 📌 总结&互动引流

今天直接上实战——教你5分钟快速开发一个自定义工具，集成到Hermes中，让AI智能体拥有你想要的专属功能！全文代码可直接复制，新手也能零失败上手，建议先收藏+关注，避免开发时迷路～

Hermes-Agent自带40+内置工具（搜索、文件操作、浏览器自动化等），但实际使用中，我们常常需要适配自己的场景：比如对接公司内部系统、操作本地软件、调用专属API，这时候就需要开发自定义工具。

好在Hermes的工具系统采用插件化设计，开发门槛极低——无需修改核心源码，只需继承基类、实现2个核心方法，就能快速集成，甚至可以直接打包供他人使用！

确保你已经成功安装Hermes-Agent（参考上一篇安装教程），并确认开发环境：

# 1. 激活Hermes虚拟环境（手动安装用户）
source ~/.hermes/venv/bin/activate
# 2. 确认hermes命令可用
hermes version
# 3. 安装必要依赖（若未安装）
pip install pydantic  # 工具参数校验（Hermes内置依赖，一般已安装）

我们以「开发一个本地文件查询工具」为例（功能：根据文件路径，查询文件内容并返回），一步步演示开发全过程。

Hermes的工具分为「内置工具」和「自定义工具」，自定义工具建议放在 ~/.hermes/skills/ 目录下（自动被Hermes识别）：

# 创建自定义工具目录（若不存在）
mkdir -p ~/.hermes/skills/my_custom_tools
cd ~/.hermes/skills/my_custom_tools

创建文件 file_query_tool.py，代码如下（注释详细，可直接复制）：

from hermes.tools.base import BaseTool
from pydantic import Field
from typing import Optional
# 自定义工具类，必须继承BaseTool
class FileQueryTool(BaseTool):
    # 1. 工具基础信息（必填）
    name: str = "file_query"  # 工具唯一标识（调用时用这个名字）
    description: str = "用于查询本地文件的内容，需要传入文件的绝对路径；如果文件不存在，会返回错误提示"  # LLM用来判断是否调用该工具
    return_direct: bool = False  # 是否直接返回结果（无需LLM二次处理）
    # 2. 工具参数（必填，用pydantic校验）
    file_path: str = Field(
        description="本地文件的绝对路径，例如：/home/user/test.txt、C:/Users/test.txt（WSL2中用Linux路径）"
    )
    encoding: Optional[str] = Field(
        default="utf-8",
        description="文件编码格式，默认utf-8，若出现乱码可尝试gbk"
    )
    # 3. 核心执行方法（必填，实现工具逻辑）
    async def execute(self) -> str:
        """执行工具，查询文件内容并返回"""
        try:
            # 读取文件内容
            with open(self.file_path, "r", encoding=self.encoding) as f:
                content = f.read()
            # 处理长文本（避免超过LLM上下文限制）
            if len(content) > 1000:
                return f"文件内容（前1000字符）：n{content[:1000]}nn提示：文件内容过长，已截取前1000字符，如需完整内容请指定截取范围。"
            else:
                return f"文件内容：n{content}"
        except FileNotFoundError:
            return f"错误：未找到文件，请检查路径是否正确（路径：{self.file_path}）"
        except Exception as e:
            return f"读取文件失败：{str(e)}"
# 注册工具（Hermes启动时会自动扫描并加载）
def register_tools(tool_manager):
    tool_manager.register_tool(FileQueryTool())

• 继承BaseTool：所有自定义工具必须继承Hermes的BaseTool基类，否则无法被识别
• 基础信息：name（唯一标识）、description（给LLM看的说明，决定LLM是否调用该工具）、return_direct（是否直接返回结果）
• 参数定义：用pydantic的Field定义参数，description会告诉LLM需要传入什么参数
• execute方法：工具的核心逻辑，必须是async异步方法（Hermes底层是异步执行），返回字符串结果（LLM可直接处理）
• 注册工具：通过register_tools函数，将工具注册到ToolManager，Hermes启动时会自动扫描执行

# 1. 重启Hermes（加载新工具）
hermes stop  # 若已启动，先停止
hermes       # 重新启动
# 2. 在Hermes交互界面，查看所有工具
/hermes tools list

如果输出中包含file_query，说明工具加载成功！

在Hermes交互界面，直接输入指令，让AI调用我们的自定义工具：

# Hermes交互界面输入
帮我查询文件 /home/user/test.txt 的内容

此时Hermes会自动识别需要调用 file_query 工具，传入文件路径参数，执行后返回文件内容，完美！

如果需要多参数（比如查询文件的指定行数），只需新增Field即可：

start_line: Optional[int] = Field(
    default=1,
    description="开始读取的行数，默认从第1行开始"
)
end_line: Optional[int] = Field(
    default=None,
    description="结束读取的行数，默认读取到文件末尾"
)

然后在execute方法中处理这两个参数即可。

将自定义工具目录打包成zip，发给他人，他人只需解压到 ~/.hermes/skills/ 目录，重启Hermes即可使用，无需额外配置！

如果工具执行失败，可通过以下命令查看日志：

hermes logs  # 查看Hermes运行日志，定位错误

问题	解决方案
工具未被加载	1. 检查文件路径是否在 ~/.hermes/skills/ 下；2. 检查register_tools函数是否正确；3. 重启Hermes
执行工具报错“async错误”	确保execute方法是async异步方法，且没有同步阻塞操作（如time.sleep，需替换为asyncio.sleep）
LLM不调用自定义工具	优化description，更明确说明工具的用途和适用场景，让LLM知道何时该调用

本文手把手教你开发Hermes自定义工具，核心就3步：继承基类、定义参数、实现执行逻辑，5分钟就能搞定！学会这个，你可以开发任何你需要的工具，让Hermes完全适配你的场景～

到此这篇关于Hermes-Agent 自定义工具开发实战的文章就介绍到这了,更多相关Hermes-Agent 自定义工具内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！