sidebar position: 2 title: "添加工具" description: "如何向 Hermes Agent 添加新工具——Schema、处理器、注册和工具集" 在编写工具之前，先问自己： 这应该是一个 Skill(技能) 吗？ 当能力可以用指令 + Shell 命令 + 现有工具表达时，将其作为
> 📖 本文档翻译自 Adding Tools > 最后更新：2026-04-16
sidebar_position: 2 title: "添加工具" description: "如何向 Hermes Agent 添加新工具——Schema、处理器、注册和工具集"
添加工具
在编写工具之前，先问自己：这应该是一个 Skill(技能) 吗？
当能力可以用指令 + Shell 命令 + 现有工具表达时，将其作为技能（arXiv 搜索、Git 工作流、Docker 管理、PDF 处理）。
当需要与 API 密钥、自定义处理逻辑、二进制数据处理或流式传输进行端到端集成时，将其作为工具（浏览器自动化、TTS、视觉分析）。
概述
添加一个工具涉及2 个文件：
tools/your_tool.py——处理器、Schema、检查函数、registry.register()调用toolsets.py——将工具名称添加到_HERMES_CORE_TOOLS（或特定工具集）
任何带有顶层 registry.register() 调用的 tools/*.py 文件都会在启动时自动发现——不需要手动导入列表。
步骤 1：创建工具文件
每个工具文件遵循相同的结构：
# tools/weather_tool.py
"""天气工具 -- 查询指定地点的当前天气。"""
import json
import os
import logging
logger = logging.getLogger(__name__)
# --- 可用性检查 ---
def check_weather_requirements() -> bool:
"""当工具的依赖可用时返回 True。"""
return bool(os.getenv("WEATHER_API_KEY"))
# --- 处理器 ---
def weather_tool(location: str, units: str = "metric") -> str:
"""获取指定地点的天气。返回 JSON 字符串。"""
api_key = os.getenv("WEATHER_API_KEY")
if not api_key:
return json.dumps({"error": "WEATHER_API_KEY not configured"})
try:
# ... 调用天气 API ...
return json.dumps({"location": location, "temp": 22, "units": units})
except Exception as e:
return json.dumps({"error": str(e)})
# --- Schema ---
WEATHER_SCHEMA = {
"name": "weather",
"description": "Get current weather for a location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name or coordinates (e.g. 'London' or '51.5,-0.1')"
},
"units": {
"type": "string",
"enum": ["metric", "imperial"],
"description": "Temperature units (default: metric)",
"default": "metric"
}
},
"required": ["location"]
}
}
# --- 注册 ---
from tools.registry import registry
registry.register(
name="weather",
toolset="weather",
schema=WEATHER_SCHEMA,
handler=lambda args, **kw: weather_tool(
location=args.get("location", ""),
units=args.get("units", "metric")),
check_fn=check_weather_requirements,
requires_env=["WEATHER_API_KEY"],
)
关键规则
:::danger 重要
- 处理器必须返回 JSON 字符串（通过
json.dumps()），绝不能返回原始字典 - 错误必须以
{"error": "message"}格式返回，绝不能作为异常抛出 check_fn在构建工具定义时被调用——如果返回False，工具会被静默排除handler接收(args: dict, **kwargs)，其中args是 LLM 的工具调用参数 :::
步骤 2：添加到工具集
在 toolsets.py 中，添加工具名称：
# 如果它应该在所有平台（CLI + 消息平台）上可用：
_HERMES_CORE_TOOLS = [
...
"weather", # <-- 在此添加
]
# 或者创建新的独立工具集：
"weather": {
"description": "Weather lookup tools",
"tools": ["weather"],
"includes": []
},
步骤 3：添加发现导入（不再需要）
带有顶层 registry.register() 调用的工具模块会被 tools/registry.py 中的 discover_builtin_tools() 自动发现。不需要维护手动导入列表——只需在 tools/ 中创建文件，启动时就会自动加载。
异步处理器
如果你的处理器需要异步代码，用 is_async=True 标记：
async def weather_tool_async(location: str) -> str:
async with aiohttp.ClientSession() as session:
...
return json.dumps(result)
registry.register(
name="weather",
toolset="weather",
schema=WEATHER_SCHEMA,
handler=lambda args, **kw: weather_tool_async(args.get("location", "")),
check_fn=check_weather_requirements,
is_async=True, # 注册表自动调用 _run_async()
)
注册表透明地处理异步桥接——你不需要自己调用 asyncio.run()。
需要 task_id 的处理器
管理每会话状态的工具通过 **kwargs 接收 task_id：
def _handle_weather(args, **kw):
task_id = kw.get("task_id")
return weather_tool(args.get("location", ""), task_id=task_id)
registry.register(
name="weather",
...
handler=_handle_weather,
)
Agent 循环拦截的工具
某些工具（todo、memory、session_search、delegate_task）需要访问每会话的 Agent 状态。这些工具在到达注册表之前被 run_agent.py 拦截。注册表仍然持有它们的 Schema，但如果拦截被绕过，dispatch() 会返回回退错误。
可选：设置向导集成
如果你的工具需要 API 密钥，将其添加到 hermes_cli/config.py：
OPTIONAL_ENV_VARS = {
...
"WEATHER_API_KEY": {
"description": "Weather API key for weather lookup",
"prompt": "Weather API key",
"url": "https://weatherapi.com/",
"tools": ["weather"],
"password": True,
},
}
检查清单
- 创建了带处理器、Schema、检查函数和注册的工具文件
- 已添加到
toolsets.py中适当的工具集 - 发现导入已添加到
model_tools.py - 处理器返回 JSON 字符串，错误以
{"error": "..."}格式返回 - 可选：API 密钥已添加到
hermes_cli/config.py的OPTIONAL_ENV_VARS - 可选：已添加到
toolset_distributions.py用于批处理 - 使用
hermes chat -q "Use the weather tool for London"测试通过