添加工具

在編寫工具之前，請問自己：這應該是一個 技能 嗎？

當某個功能可以表示為指令 + shell 命令 + 現有工具（如 arXiv 搜索、git 工作流、Docker 管理、PDF 處理）時，請將其作為 技能。

當需要與 API 密鑰進行端到端集成、自定義處理邏輯、二進制數據處理或流式處理（如瀏覽器自動化、TTS、視覺分析）時，請將其作為 工具。

概述

添加一個工具需要修改 3 個文件：

1. tools/your_tool.py — 處理函數、模式、檢查函數、registry.register() 調用
2. toolsets.py — 將工具名稱添加到 _HERMES_CORE_TOOLS（或特定工具集）
3. model_tools.py — 將 "tools.your_tool" 添加到 _discover_tools() 列表中

第一步：創建工具文件

每個工具文件都遵循相同的結構：

# tools/weather_tool.py
"""Weather Tool -- 查找某個位置的當前天氣。"""

import json
import os
import logging

logger = logging.getLogger(__name__)


# --- 可用性檢查 ---

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


# --- 處理程序 ---

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:
        # ...調用天氣 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"],
)

關鍵規則

重要

• 處理函數 必須 返回 JSON 字符串（通過 json.dumps()），不能返回原始字典
• 錯誤 必須 以 {"error": "message"} 形式返回，不能拋出異常
• check_fn 在構建工具定義時被調用 —— 如果返回 False，該工具將被靜默排除
• handler 接收 (args: dict, **kwargs)，其中 args 是 LLM 工具調用的參數

第二步：添加到工具集

在 toolsets.py 中添加工具名稱：

# 如果它應該在所有平臺上可用（CLI + 消息平臺）：
_HERMES_CORE_TOOLS = [
    ...
    "weather",  # <-- 在此添加
]

# 或者創建一個新的獨立 Toolset：
"weather": {
    "description": "Weather lookup tools",
    "tools": ["weather"],
    "includes": []
},

第三步：添加發現導入

在 model_tools.py 中將模塊添加到 _discover_tools() 列表中：

def _discover_tools():
    _modules = [
        ...
        "tools.weather_tool",  # <-- 在此添加
    ]

此導入會觸發工具文件末尾的 registry.register() 調用。

異步處理函數

如果處理函數需要異步代碼，請使用 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 攔截。註冊表仍然保存它們的模式，但如果攔截被繞過，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,
    },
}

檢查清單

• 已創建工具文件，包含處理函數、模式、檢查函數和註冊調用
• 已在 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" 測試