🏠 Главная › Документация › Разработчикам

Добавление инструментов

Прежде чем писать инструмент, спросите себя: может, это лучше оформить как скилл?

Встроенные основные инструменты Эта страница для добавления встроенного инструмента Hermes в сам репозиторий. Если вы хотите создать персональный, локальный для проекта или другой кастомный инструмент без изменения ядра Hermes, используйте вместо этого плагины:

По умолчанию используйте плагины для создания большинства кастомных инструментов. Следуйте этой странице только если вы явно хотите добавить новый встроенный инструмент в tools/ и toolsets.py.

Делайте это Скиллом, когда функциональность можно выразить через инструкции + shell-команды + существующие инструменты (поиск по arXiv, git-воркфлоу, управление Docker, обработка PDF).

Делайте это Инструментом, когда требуется сквозная интеграция с API-ключами, кастомная логика обработки, работа с бинарными данными или стриминг (автоматизация браузера, TTS, анализ изображений).

Обзор

Добавление инструмента затрагивает 2 файла:

  1. tools/your_tool.py — обработчик, схема, функция проверки, вызов registry.register()

  2. toolsets.py — добавьте имя инструмента в _HERMES_CORE_TOOLS (или в конкретный набор)

Любой файл tools/*.py с вызовом registry.register() на верхнем уровне автоматически обнаруживается при запуске — ручной импорт не требуется.

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

Ключевые правила

Важно

Шаг 2: Добавление встроенного инструмента в набор

В 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() на верхнем уровне автоматически обнаруживаются функцией discover_builtin_tools() в tools/registry.py. Никакого ручного списка импортов — просто создайте файл в 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,  # registry calls _run_async() automatically
)

Реестр прозрачно обрабатывает асинхронное bridging — вам никогда не нужно вызывать 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 до того, как достигают реестра. Реестр всё ещё хранит их схемы, но dispatch() возвращает fallback-ошибку, если перехват был обойдён.

Опционально: Интеграция с мастером настройки

Если ваш инструмент требует 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,
    },
}

Контрольный список