sidebar_position: 2 title: "Adding Tools" description: "How to add a new tool to Hermes Agent — schemas, handlers, registration, and toolsets" lang: ru
Добавление инструментов
Прежде чем писать инструмент, спросите себя: должен ли это быть skill?
⚠️ Warning
Только встроенные основные инструменты Эта страница предназначена для добавления **встроенного инструмента Hermes** в сам репозиторий. Если вам нужен личный, локальный для проекта или другой специальный инструмент без модифицируя ядро Hermes, вместо этого используйте маршрут плагина: - [Плагины](/docs/user-guide/features/plugins) - [Создать плагин Hermes](/docs/guides/build-a-hermes-plugin) По умолчанию используются плагины для создания большинства пользовательских инструментов. Следуйте этой странице только тогда, когда вы явно хотите выпустить новый встроенный инструмент в `tools/` и `toolsets.py`.Сделайте это навыком, когда способность может быть выражена в виде инструкций + команд оболочки + существующих инструментов (поиск в arXiv, рабочие процессы git, управление Docker, обработка PDF).
Превратите его в инструмент, когда требуется сквозная интеграция с ключами API, пользовательской логикой обработки, обработкой двоичных данных или потоковой передачей (автоматизация браузера, TTS, анализ изображения).
Обзор
Добавление инструмента затрагивает 2 файла:
tools/your_tool.py— обработчик, схема, функция проверки, вызовregistry.register()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"],
)
Ключевые правила
:::опасность Важно
- Обработчики ДОЛЖНЫ возвращать строку JSON (через json.dumps()), а не необработанные значения.
– Ошибки ДОЛЖНЫ возвращаться как {"error": "message"} и никогда не вызываться как исключения.
- check_fn вызывается при создании определений инструментов — если он возвращает False, инструмент автоматически исключается.
- handler получает (args: dict, **kwargs), где args — аргументы вызова инструмента LLM.