Hermes agent

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

Прежде чем писать инструмент, задайте себе вопрос: а не лучше ли сделать навык?

внимание
Только встроенные базовые инструменты

Эта страница — о добавлении встроенного инструмента 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:
        # ... вызов 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

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

В toolsets.py добавьте имя инструмента:

# Если инструмент должен быть доступен на всех платформах (CLI + мессенджеры):
_HERMES_CORE_TOOLS = [
    ...
    "weather",  # <-- добавить сюда
]

# Или создайте новый самостоятельный набор:
"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 вызывает _run_async() автоматически
)

Реестр сам управляет асинхронным мостом — вызывать 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() вернёт резервную ошибку.

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

Если инструмент требует 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
  • Подтверждено, что это действительно должен быть встроенный инструмент ядра, а не плагин
  • Обработчик возвращает JSON-строки, ошибки возвращаются как {"error": "..."}
  • Опционально: API-ключ добавлен в OPTIONAL_ENV_VARS в hermes_cli/config.py
  • Опционально: добавлен в toolset_distributions.py для пакетной обработки
  • Проверено командой hermes chat -q "Use the weather tool for London"
⌕ ESC