添加工具

在动手写工具之前，先问自己一句：这件事是否更适合做成技能？

当能力可以通过“说明 + shell 命令 + 现有工具”表达时，更适合做成技能，例如 arXiv 搜索、git 工作流、Docker 管理、PDF 处理。

当能力需要与 API Key、定制处理逻辑、二进制数据或流式处理做端到端集成时，更适合做成工具，例如浏览器自动化、TTS、视觉分析。

总览

新增一个工具通常只需要改 2 个文件：

tools/your_tool.py — 处理器、schema、检查函数，以及 registry.register() 调用
toolsets.py — 把工具名加入 _HERMES_CORE_TOOLS（或某个特定 toolset）

任何带有顶层 registry.register() 调用的 tools/*.py 文件，都会在启动时自动发现，无需维护手工导入列表。

步骤 1：创建工具文件

每个工具文件都遵循相同结构：

# tools/weather_tool.py
"""Weather Tool -- look up current weather for a location."""

import json
import os
import logging

logger = logging.getLogger(__name__)


# --- Availability check ---

def check_weather_requirements() -> bool:
    """Return True if the tool's dependencies are available."""
    return bool(os.getenv("WEATHER_API_KEY"))


# --- Handler ---

def weather_tool(location: str, units: str = "metric") -> str:
    """Fetch weather for a location. Returns JSON string."""
    api_key = os.getenv("WEATHER_API_KEY")
    if not api_key:
        return json.dumps({"error": "WEATHER_API_KEY not configured"})
    try:
        # ... call weather 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"]
    }
}


# --- Registration ---

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"],
)

关键规则

Important

Handler 必须返回 JSON 字符串（通过 json.dumps()），不能直接返回原始字典
错误必须以 {"error": "message"} 的形式返回，不能直接抛异常
构建工具定义时会调用 check_fn，如果它返回 False，该工具会被静默排除
handler 的接收形式是 (args: dict, **kwargs)，其中 args 是 LLM 给出的工具调用参数

步骤 2：加入 toolset

在 toolsets.py 中加入工具名：

# If it should be available on all platforms (CLI + messaging):
_HERMES_CORE_TOOLS = [
    ...
    "weather",  # <-- add here
]

# Or create a new standalone toolset:
"weather": {
    "description": "Weather lookup tools",
    "tools": ["weather"],
    "includes": []
},

步骤 3：添加发现导入（现在不需要）

只要工具模块中存在顶层 registry.register() 调用，tools/registry.py 中的 discover_builtin_tools() 就会自动发现它。也就是说，只要把文件放进 tools/，启动时就会自动加载，不需要再去维护手动导入列表。

异步 Handler

如果 Handler 需要异步代码，使用 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,  # registry calls _run_async() automatically
)

注册表会透明处理 async bridging；你不需要自己调用 asyncio.run()。

需要 `task_id` 的 Handler

如果工具需要管理按会话隔离的状态，可以通过 **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 Loop 拦截的工具

有一些工具（todo、memory、session_search、delegate_task）需要访问 agent 的会话级状态，因此会在 run_agent.py 中优先被拦截，而不会走普通注册表分发流程。注册表仍然保存这些工具的 schema，但如果拦截失效，dispatch() 只会返回一个回退错误。

可选：集成进设置向导

如果你的工具需要 API Key，可在 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,
    },
}

检查清单

已创建工具文件，包含 handler、schema、check 函数与注册逻辑
已在 toolsets.py 中加入合适的 toolset
Handler 返回 JSON 字符串，错误以 {"error": "..."} 形式返回
可选：已在 hermes_cli/config.py 的 OPTIONAL_ENV_VARS 中加入 API Key
可选：已加入 toolset_distributions.py，用于 batch processing
已用 hermes chat -q "Use the weather tool for London" 做过验证

总览​

步骤 1：创建工具文件​

关键规则​

步骤 2：加入 toolset​

步骤 3：添加发现导入（现在不需要）​

异步 Handler​

需要 task_id 的 Handler​

被 Agent Loop 拦截的工具​

可选：集成进设置向导​

检查清单​

总览