平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Hermes-Agent 自定义工具开发实践”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。
今天直接上实战——教你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内置依赖，一般已安装）
二、自定义工具开发步骤（核心流程）
结合项目来看，我们以「开发一个本地文件查询工具」为例（功能：根据文件路径，查询文件内容同时得到），一步步演示开发全过程。
Step 1：找到工具存放目录
在这个场景下，Hermes的工具分为「内置工具」和「自定义工具」，自定义工具建议放在 ~/.hermes/skills/ 目录下（自动被Hermes识别）：
# 创建自定义工具目录（若不存在）
mkdir -p ~/.hermes/skills/my_custom_tools
cd ~/.hermes/skills/my_custom_tools
Step 2：编写工具代码（核心文件）
新建文件 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())
Step 3：关键代码解析（必看）
- 继承BaseTool：所有自定义工具必须继承Hermes的BaseTool基类，否则无法被识别
- 基础信息：name（唯一标识）、description（给LLM看的说明，决定LLM是否调用该工具）、return_direct（是否直接得到结果）
- 参数定义：用pydantic的Field定义参数，description会告诉LLM需传入什么参数
- execute方法：工具的核心逻辑，必须是async异步方法（Hermes底层是异步执行），得到字符串结果（LLM可直接处理）
- 注册工具：借助register_tools函数，将工具注册到ToolManager，Hermes启动时会自动扫描执行
Step 4：验证工具是否加载成功
# 1. 重启Hermes（加载新工具）
hermes stop # 若已启动，先停止
hermes # 重新启动
# 2. 在Hermes交互界面，查看所有工具
/hermes tools list
若输出中包含file_query，说明工具加载成功！
三、测试自定义工具（实战验证）
在Hermes交互界面，直接输入指令，让AI调用我们的自定义工具：
# Hermes交互界面输入
帮我查询文件 /home/user/test.txt 的内容
结合项目来看，此时Hermes会自动识别需调用 file_query 工具，传入文件路径参数，执行后得到文件内容，完美！
四、进阶技巧（扩展功能）
1. 工具参数扩展（多参数示例）
若需多参数（比如查询文件的指定行数），只需新增Field即可：
start_line: Optional[int] = Field(
default=1,
description="开始读取的行数，默认从第1行开始"
)
end_line: Optional[int] = Field(
default=None,
description="结束读取的行数，默认读取到文件末尾"
)
然后在execute方法中处理这两个参数即可。
2. 工具打包与分享
理解这一步时，将自定义工具目录打包成zip，发给他人，他人只需解压到 ~/.hermes/skills/ 目录，重启Hermes即可采用，无需额外设置！
3. 调试工具（关键技巧）
若工具执行失败，可借助以下命令查看日志：
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 自定义工具内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多兼容脚本之家！