需通过插件机制编写自定义工具：一、确认agent≥v2.4.0、激活虚拟环境、安装pydantic；二、在~/.hermes/skills/下建目录与主文件；三、继承basetool，定义name、description、参数及required；四、在execute中实现路径净化与白名单校验；五、配置skills_dir、重启agent、用/skills验证并测试。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望为Hermes Agent添加专属能力，例如对接内部系统、读取本地敏感配置、调用私有API或执行特定业务逻辑，则需通过插件机制编写自定义工具。以下是开展Hermes Agent自定义工具开发的具体步骤：
一、确认开发环境与基础依赖
在编写任何工具前，必须确保运行时环境满足最低要求，避免因版本不兼容或缺失依赖导致插件加载失败或执行异常。Hermes Agent自定义工具基于Python生态构建，依赖pydantic进行参数校验，且要求Agent核心版本不低于v2.4.0。
1、执行hermes version命令，确认输出版本号≥2.4.0。
2、激活Hermes虚拟环境：source ~/.hermes/venv/bin/activate（Linux/macOS）或~\.hermes\venv\Scripts\activate（Windows）。
3、检查pydantic是否已安装：pip show pydantic；若未安装，则运行pip install pydantic。
二、创建自定义工具目录与基础结构
自定义工具需放置于Hermes可识别的技能路径中，推荐使用~/.hermes/skills/作为根目录。该路径下每个子目录对应一个独立工具，Hermes启动时会自动扫描并注册其中符合规范的Python模块。
1、创建工具专属目录：mkdir -p ~/.hermes/skills/file_reader。
2、进入该目录：cd ~/.hermes/skills/file_reader。
3、新建主工具文件：touch file_reader_tool.py。
三、编写继承BaseTool的工具类
所有自定义工具必须继承hermes.tools.base.BaseTool基类，并完整实现name、description、return_direct及参数字段。该结构使LLM能准确理解工具语义、判断调用时机，并对输入执行强类型校验。
1、在file_reader_tool.py中导入必要模块：from hermes.tools.base import BaseTool、from pydantic import Field。
2、定义工具类FileReaderTool，设置name="file_reader"，description="读取指定绝对路径的文本文件内容；仅支持UTF-8编码文件"。
3、声明参数file_path: str = Field(description="待读取文件的绝对路径，必须为本地可访问路径")，并加入required = ["file_path"]。
四、实现execute方法并注入安全校验
工具的实际行为由execute方法定义，该方法接收已校验的参数字典并返回结构化结果。为防止路径遍历攻击，必须对file_path执行规范化与白名单校验，确保其位于允许访问的根目录之下。
1、在FileReaderTool类中定义def execute(self, **kwargs) -> str:。
2、获取传入路径：path = kwargs.get("file_path")。
3、执行路径净化：import os; safe_path = os.path.realpath(path)。
4、校验路径前缀：if not safe_path.startswith("/home/user/documents/"):，否则返回<strong><font color="green">拒绝访问：文件路径超出授权范围</font></strong>。
5、尝试打开并读取文件，捕获FileNotFoundError与UnicodeDecodeError，分别返回对应错误提示。
五、注册工具并验证加载状态
工具代码完成后，需确保Hermes Agent在启动时能发现并注册该工具。注册成功后，可通过交互终端的/skills命令查看其是否出现在已启用列表中，这是验证工具可用性的第一道门槛。
1、确认~/.hermes/config.yaml中skills_dir字段值为"~/.hermes/skills"（支持tilde展开）。
2、重启Hermes Agent进程：pkill -f "hermes" && hermes &。
3、进入CLI交互模式，输入/skills，查找输出中是否存在file_reader条目及对应描述。
4、手动触发测试：请使用file_reader工具读取/home/user/documents/test.txt，观察是否返回预期内容或安全拦截提示。
