添加工具

本文将指导你如何为 Hermes Agent 添加一个新工具，涵盖以下核心步骤：

• 定义工具的 Schema（模式）
• 实现工具的 Handler（处理器）
• 注册工具到系统
• 将工具归类至 Toolset（工具集）

1. 定义工具的 Schema（模式）

每个工具必须有一个对应的 JSON Schema 来描述其输入参数和行为。

示例：天气查询工具 get_weather

{
  "name": "get_weather",
  "description": "获取指定城市的实时天气信息",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称，如 '北京' 或 'Beijing'"
      },
      "units": {
        "type": "string",
        "enum": ["metric", "imperial"],
        "default": "metric",
        "description": "温度单位：metric（摄氏度）或 imperial（华氏度）"
      }
    },
    "required": ["city"]
  }
}

✅ 最佳实践：

• 使用 name 作为唯一标识符，避免空格或特殊字符。
• description 应清晰说明用途。
• 所有必填字段需在 required 数组中列出。
• 使用 enum 限制可选值以增强安全性。

---

2. 实现工具的 Handler（处理器）

处理器是实际执行逻辑的 Python 函数。它接收参数并返回结果。

示例：get_weather_handler.py

import requests
from typing import Dict, Any

def get_weather_handler(params: Dict[str, Any]) -> Dict[str, Any]:
    city = params["city"]
    units = params.get("units", "metric")

    # 调用外部 API（例如 OpenWeatherMap）
    api_key = "YOUR_API_KEY"  # 建议从环境变量读取
    url = f"http://api.openweathermap.org/data/2.5/weather?q={city}&units={units}&appid={api_key}"

    try:
        response = requests.get(url, timeout=10)
        response.raise_for_status()
        data = response.json()

        return {
            "success": True,
            "result": {
                "city": data["name"],
                "temperature": data["main"]["temp"],
                "feels_like": data["main"]["feels_like"],
                "humidity": data["main"]["humidity"],
                "description": data["weather"][0]["description"]
            }
        }
    except Exception as e:
        return {
            "success": False,
            "error": f"Failed to fetch weather: {str(e)}"
        }

🔐 安全提示：

• 不要在代码中硬编码 API 密钥。
• 使用环境变量：os.getenv("OPENWEATHER_API_KEY")
• 添加超时和异常处理。

---

3. 注册工具

Hermes Agent 使用模块化注册机制。你需要将工具注册到主注册器中。

示例：tool_registry.py

from hermes_agent.tools import register_tool
from .get_weather_handler import get_weather_handler

# 定义工具元数据
weather_tool_schema = {
    "name": "get_weather",
    "description": "获取指定城市的实时天气信息",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "城市名称"},
            "units": {
                "type": "string",
                "enum": ["metric", "imperial"],
                "default": "metric"
            }
        },
        "required": ["city"]
    }
}

# 注册工具
register_tool(
    name="get_weather",
    schema=weather_tool_schema,
    handler=get_weather_handler,
    description="获取指定城市的实时天气信息"
)

📌 注意事项：

• register_tool() 是核心注册函数。
• 确保 name 与 schema 中一致。
• 可选地提供 description 用于文档生成。

---

4. 将工具归类至 Toolset（工具集）

你可以将多个相关工具组织成“工具集”，便于管理与调用。

示例：创建一个 weather_toolset.py

from hermes_agent.toolsets import register_toolset
from .get_weather_handler import get_weather_handler
from .get_forecast_handler import get_forecast_handler  # 假设有另一个工具

# 工具集定义
weather_toolset = {
    "name": "weather",
    "description": "天气相关工具集合",
    "tools": [
        "get_weather",
        "get_forecast"
    ]
}

# 注册工具集
register_toolset(weather_toolset)

💡 工具集优势：

• 支持按组启用/禁用工具。
• 提供统一的上下文提示（prompt）。
• 便于在多 agent 架构中分发职责。

---

5. 验证与测试

启动测试脚本

# test_tool.py
from hermes_agent import run_tool

if __name__ == "__main__":
    result = run_tool(
        tool_name="get_weather",
        params={"city": "Beijing", "units": "metric"}
    )
    print(result)

运行后应输出类似：

{
  "success": true,
  "result": {
    "city": "Beijing",
    "temperature": 18.5,
    "feels_like": 17.2,
    "humidity": 60,
    "description": "scattered clouds"
  }
}

---

6. 高级配置（可选）

使用环境变量管理敏感信息

import os

api_key = os.getenv("OPENWEATHER_API_KEY")
if not api_key:
    raise ValueError("OPENWEATHER_API_KEY is required")

添加权限控制

def get_weather_handler(params: Dict[str, Any], user_role: str = "user") -> Dict[str, Any]:
    if user_role not in ["admin", "premium"]:
        return {"success": False, "error": "Access denied"}
    # ... 处理逻辑

---

7. 推荐目录结构

hermes_agent/
├── tools/
│   ├── get_weather/
│   │   ├── schema.json
│   │   ├── handler.py
│   │   └── __init__.py
│   ├── get_forecast/
│   │   └── ...
│   └── __init__.py
├── tool_registry.py
├── toolsets/
│   ├── weather_toolset.py
│   └── finance_toolset.py
└── main.py

---

8. 参考资源

• Hermes Agent GitHub
• OpenAI Function Calling 文档
• JSON Schema 规范

---

✅ 总结：添加新工具四步法

步骤	操作
1️⃣	定义清晰的 JSON Schema
2️⃣	编写健壮的 Handler 函数
3️⃣	使用 register_tool() 注册
4️⃣	归入 Toolset 并测试

---

🚀 现在你已准备好为 Hermes Agent 添加自定义工具！
欢迎提交 PR 至 agentskills.io 共享你的工具！

🛠️ 想快速上手？使用 Modal 或 Daytona 快速部署开发环境。"

---

添加工具

在编写工具之前，请先问自己：这是否应该是一个 技能 而不是工具？

当某个功能可以通过 指令 + shell 命令 + 现有工具 实现时（例如：arXiv 搜索、Git 工作流、Docker 管理、PDF 处理），请将其作为 技能。

当需要与 API 密钥进行端到端集成、自定义处理逻辑、二进制数据处理或流式传输（如浏览器自动化、TTS、视觉分析）时，才应创建 工具。

概述

添加一个工具涉及修改 3 个文件：

1. tools/your_tool.py — 工具处理器、Schema 定义、检查函数及 registry.register() 调用
2. toolsets.py — 将工具名称加入 _HERMES_CORE_TOOLS（或特定工具集）
3. model_tools.py — 将 "tools.your_tool" 添加至 _discover_tools() 列表

第一步：创建工具文件

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

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

关键规则

重要

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

第二步：添加到工具集

在 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": []
},

第三步：添加发现导入

在 model_tools.py 中，将模块添加到 _discover_tools() 列表中：

def _discover_tools():
    _modules = [
        ...
        "tools.weather_tool",  # <-- add here
    ]

此导入会触发工具文件末尾的 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,  # registry calls _run_async() automatically
)

注册中心会透明地处理异步桥接 —— 你无需手动调用 asyncio.run()。

需要 task_id 的处理器

管理会话级状态的工具会通过 task_id 接收 **kwargs：

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

被代理循环拦截的工具

某些工具（todo、memory、session_search、delegate_task）需要访问会话级代理状态。这些工具在到达注册中心前会被 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 密钥添加至 OPTIONAL_ENV_VARS 的 hermes_cli/config.py
• （可选）已添加至 toolset_distributions.py 以支持批量处理
• 已使用 hermes chat -q "Use the weather tool for London" 测试