Создание плагина для Hermes

Это руководство проведёт вас через создание полноценного плагина с нуля. В итоге вы получите рабочий плагин с несколькими инструментами, хуками жизненного цикла, файлами данных и встроенным навыком — всё, что поддерживает система плагинов.

Что строим

Плагин calculator с двумя инструментами:

• calculate — вычисляет математические выражения (2**16, sqrt(144), pi * 5**2)
• unit_convert — переводит единицы измерения (100 F → 37.78 C, 5 km → 3.11 mi)

Плюс хук, который логирует каждый вызов инструмента, и файл навыка в комплекте.

Шаг 1: Создайте директорию плагина

mkdir -p ~/.hermes/plugins/calculator
cd ~/.hermes/plugins/calculator

Шаг 2: Напишите манифест

Создайте plugin.yaml:

name: calculator
version: 1.0.0
description: Math calculator — evaluate expressions and convert units
provides_tools:
  - calculate
  - unit_convert
provides_hooks:
  - post_tool_call

Это сообщает Hermes: «Я плагин calculator, предоставляю инструменты и хуки». Поля provides_tools и provides_hooks — списки того, что регистрирует плагин.

Необязательные поля, которые можно добавить:

author: Your Name
requires_env:          # условие загрузки по переменным окружения; запрашиваются при установке
  - SOME_API_KEY       # простой формат — плагин отключён, если переменная не задана
  - name: OTHER_KEY    # расширенный формат — показывает описание и URL при установке
    description: "Key for the Other service"
    url: "https://other.com/keys"
    secret: true

Шаг 3: Напишите схемы инструментов

Создайте schemas.py — именно это читает LLM, чтобы решить, когда вызывать ваши инструменты:

"""Tool schemas — what the LLM sees."""

CALCULATE = {
    "name": "calculate",
    "description": (
        "Evaluate a mathematical expression and return the result. "
        "Supports arithmetic (+, -, *, /, **), functions (sqrt, sin, cos, "
        "log, abs, round, floor, ceil), and constants (pi, e). "
        "Use this for any math the user asks about."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Math expression to evaluate (e.g., '2**10', 'sqrt(144)')",
            },
        },
        "required": ["expression"],
    },
}

UNIT_CONVERT = {
    "name": "unit_convert",
    "description": (
        "Convert a value between units. Supports length (m, km, mi, ft, in), "
        "weight (kg, lb, oz, g), temperature (C, F, K), data (B, KB, MB, GB, TB), "
        "and time (s, min, hr, day)."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "value": {
                "type": "number",
                "description": "The numeric value to convert",
            },
            "from_unit": {
                "type": "string",
                "description": "Source unit (e.g., 'km', 'lb', 'F', 'GB')",
            },
            "to_unit": {
                "type": "string",
                "description": "Target unit (e.g., 'mi', 'kg', 'C', 'MB')",
            },
        },
        "required": ["value", "from_unit", "to_unit"],
    },
}

Почему схемы важны: поле description — это то, как LLM понимает, когда использовать ваш инструмент. Пишите конкретно: что делает инструмент и когда его применять. В parameters описываются аргументы, которые передаёт LLM.

Шаг 4: Напишите обработчики инструментов

Создайте tools.py — код, который выполняется, когда LLM вызывает ваши инструменты:

"""Tool handlers — the code that runs when the LLM calls each tool."""

import json
import math

# Safe globals for expression evaluation — no file/network access
_SAFE_MATH = {
    "abs": abs, "round": round, "min": min, "max": max,
    "pow": pow, "sqrt": math.sqrt, "sin": math.sin, "cos": math.cos,
    "tan": math.tan, "log": math.log, "log2": math.log2, "log10": math.log10,
    "floor": math.floor, "ceil": math.ceil,
    "pi": math.pi, "e": math.e,
    "factorial": math.factorial,
}


def calculate(args: dict, **kwargs) -> str:
    """Evaluate a math expression safely.

    Rules for handlers:
    1. Receive args (dict) — the parameters the LLM passed
    2. Do the work
    3. Return a JSON string — ALWAYS, even on error
    4. Accept **kwargs for forward compatibility
    """
    expression = args.get("expression", "").strip()
    if not expression:
        return json.dumps({"error": "No expression provided"})

    try:
        result = eval(expression, {"__builtins__": {}}, _SAFE_MATH)
        return json.dumps({"expression": expression, "result": result})
    except ZeroDivisionError:
        return json.dumps({"expression": expression, "error": "Division by zero"})
    except Exception as e:
        return json.dumps({"expression": expression, "error": f"Invalid: {e}"})


# Conversion tables — values are in base units
_LENGTH = {"m": 1, "km": 1000, "mi": 1609.34, "ft": 0.3048, "in": 0.0254, "cm": 0.01}
_WEIGHT = {"kg": 1, "g": 0.001, "lb": 0.453592, "oz": 0.0283495}
_DATA = {"B": 1, "KB": 1024, "MB": 1024**2, "GB": 1024**3, "TB": 1024**4}
_TIME = {"s": 1, "ms": 0.001, "min": 60, "hr": 3600, "day": 86400}


def _convert_temp(value, from_u, to_u):
    # Normalize to Celsius
    c = {"F": (value - 32) * 5/9, "K": value - 273.15}.get(from_u, value)
    # Convert to target
    return {"F": c * 9/5 + 32, "K": c + 273.15}.get(to_u, c)


def unit_convert(args: dict, **kwargs) -> str:
    """Convert between units."""
    value = args.get("value")
    from_unit = args.get("from_unit", "").strip()
    to_unit = args.get("to_unit", "").strip()

    if value is None or not from_unit or not to_unit:
        return json.dumps({"error": "Need value, from_unit, and to_unit"})

    try:
        # Temperature
        if from_unit.upper() in {"C","F","K"} and to_unit.upper() in {"C","F","K"}:
            result = _convert_temp(float(value), from_unit.upper(), to_unit.upper())
            return json.dumps({"input": f"{value} {from_unit}", "result": round(result, 4),
                             "output": f"{round(result, 4)} {to_unit}"})

        # Ratio-based conversions
        for table in (_LENGTH, _WEIGHT, _DATA, _TIME):
            lc = {k.lower(): v for k, v in table.items()}
            if from_unit.lower() in lc and to_unit.lower() in lc:
                result = float(value) * lc[from_unit.lower()] / lc[to_unit.lower()]
                return json.dumps({"input": f"{value} {from_unit}",
                                 "result": round(result, 6),
                                 "output": f"{round(result, 6)} {to_unit}"})

        return json.dumps({"error": f"Cannot convert {from_unit} → {to_unit}"})
    except Exception as e:
        return json.dumps({"error": f"Conversion failed: {e}"})

Главные правила для обработчиков:

1. Сигнатура: def my_handler(args: dict, **kwargs) -> str
2. Возвращаемое значение: всегда JSON-строка — и при успехе, и при ошибке.
3. Не бросайте исключения: ловите все Exception и возвращайте JSON с ошибкой.
4. Принимайте **kwargs: Hermes может передавать дополнительный контекст в будущих версиях.

Шаг 5: Напишите регистрацию

Создайте __init__.py — здесь схемы связываются с обработчиками:

"""Calculator plugin — registration."""

import logging

from . import schemas, tools

logger = logging.getLogger(__name__)

# Track tool usage via hooks
_call_log = []

def _on_post_tool_call(tool_name, args, result, task_id, **kwargs):
    """Hook: runs after every tool call (not just ours)."""
    _call_log.append({"tool": tool_name, "session": task_id})
    if len(_call_log) > 100:
        _call_log.pop(0)
    logger.debug("Tool called: %s (session %s)", tool_name, task_id)


def register(ctx):
    """Wire schemas to handlers and register hooks."""
    ctx.register_tool(name="calculate",    toolset="calculator",
                      schema=schemas.CALCULATE,    handler=tools.calculate)
    ctx.register_tool(name="unit_convert", toolset="calculator",
                      schema=schemas.UNIT_CONVERT, handler=tools.unit_convert)

    # This hook fires for ALL tool calls, not just ours
    ctx.register_hook("post_tool_call", _on_post_tool_call)

Что делает register():

• Вызывается ровно один раз при запуске
• ctx.register_tool() добавляет инструмент в реестр — модель видит его сразу
• ctx.register_hook() подписывается на события жизненного цикла
• ctx.register_cli_command() регистрирует CLI-подкоманду (например, hermes my-plugin <subcommand>)
• ctx.register_command() регистрирует слэш-команду внутри сессии (например, /myplugin <args> в CLI или чате шлюза) — см. Регистрация слэш-команд ниже
• ctx.dispatch_tool(name, arguments) — вызов любого другого инструмента (встроенного или из другого плагина) с контекстом родительского агента (подтверждения, учётные данные, task_id) — всё подключается автоматически. Удобно из обработчиков слэш-команд, которым нужно вызвать terminal, read_file или другой инструмент так, будто это сделала модель напрямую.
• Если функция упадёт с ошибкой, плагин будет отключён, но Hermes продолжит работу

Пример dispatch_tool — слэш-команда, запускающая инструмент:

def handle_scan(ctx, raw_args: str):
    """Implement /scan by invoking the terminal tool through the registry."""
    result = ctx.dispatch_tool("terminal", {"command": f"find . -name '{raw_args}'"})
    return result  # returned to the caller's chat UI

def register(ctx):
    # Handlers receive a single raw_args string; close over ctx via a lambda.
    ctx.register_command(
        "scan",
        lambda raw: handle_scan(ctx, raw),
        description="Find files matching a glob",
    )

Вызванный инструмент проходит через обычный pipeline подтверждений, маскирования данных и бюджета — это настоящий вызов инструмента, а не обход этих механизмов.

Шаг 6: Проверьте

Запустите Hermes:

hermes

В списке инструментов в баннере должна появиться строка calculator: calculate, unit_convert.

Попробуйте эти промпты:

What's 2 to the power of 16?
Convert 100 fahrenheit to celsius
What's the square root of 2 times pi?
How many gigabytes is 1.5 terabytes?

Проверьте статус плагина:

/plugins

Вывод:

Plugins (1):
  ✓ calculator v1.0.0 (2 tools, 1 hooks)

Отладка обнаружения плагинов

Если плагин не появляется или появляется, но не загружается — задайте HERMES_PLUGINS_DEBUG=1, чтобы получить подробные логи обнаружения в stderr:

HERMES_PLUGINS_DEBUG=1 hermes plugins list

Для каждого источника плагинов (встроенные, пользовательские, проектные, entry-points) вы увидите:

• какие директории сканировались и сколько манифестов нашлось в каждой
• по каждому манифесту: разрешённый ключ, имя, тип, источник, путь на диске
• причины пропуска: disabled via config, not enabled in config, exclusive plugin, no plugin.yaml, depth cap reached
• при загрузке: импортируемый плагин и однострочное резюме того, что зарегистрировал register(ctx) (инструменты, хуки, слэш-команды, CLI-команды)
• при ошибке парсинга: полный traceback исключения (ошибки YAML-сканера и т.д.)
• при ошибке register(): полный traceback с указанием строки в вашем __init__.py

Те же логи всегда пишутся в ~/.hermes/logs/agent.log на уровне WARNING (только сбои) и DEBUG (всё), когда задана переменная окружения. Если запустить с переменной нельзя (например, изнутри шлюза), смотрите лог напрямую:

hermes logs --level WARNING | grep -i plugin

Частые причины, по которым плагин не появляется:

• Не включён в конфиге — плагины подключаются явно. Запустите hermes plugins enable <name> (имя берётся из вывода plugins list; для вложенных структур может быть <category>/<plugin>).
• Неправильная структура директории — нужен путь ~/.hermes/plugins/<plugin-name>/plugin.yaml (плоский) или ~/.hermes/plugins/<category>/<plugin-name>/plugin.yaml (один уровень категории, максимум). Всё, что глубже, игнорируется.
• Нет __init__.py — в директории плагина должны быть и plugin.yaml, и __init__.py с функцией register(ctx).
• Неправильный kind — адаптеры шлюза требуют kind: platform в манифесте. Провайдеры памяти автоматически определяются как kind: exclusive и подключаются через параметр memory.provider в конфиге, а не через plugins.enabled.

Финальная структура плагина

~/.hermes/plugins/calculator/
├── plugin.yaml      # "I'm calculator, I provide tools and hooks"
├── __init__.py      # Wiring: schemas → handlers, register hooks
├── schemas.py       # What the LLM reads (descriptions + parameter specs)
└── tools.py         # What runs (calculate, unit_convert functions)

Четыре файла, чёткое разделение:

• Манифест объявляет, что это за плагин
• Схемы описывают инструменты для LLM
• Обработчики реализуют логику
• Регистрация связывает всё вместе

Что ещё умеют плагины?

Поставлять файлы данных

Положите любые файлы в директорию плагина и читайте их при импорте:

# In tools.py or __init__.py
from pathlib import Path

_PLUGIN_DIR = Path(__file__).parent
_DATA_FILE = _PLUGIN_DIR / "data" / "languages.yaml"

with open(_DATA_FILE) as f:
    _DATA = yaml.safe_load(f)

Встраивать навыки

Плагины могут поставлять файлы навыков, которые агент загружает через skill_view("plugin:skill"). Регистрируйте их в __init__.py:

~/.hermes/plugins/my-plugin/
├── __init__.py
├── plugin.yaml
└── skills/
    ├── my-workflow/
    │   └── SKILL.md
    └── my-checklist/
        └── SKILL.md

from pathlib import Path

def register(ctx):
    skills_dir = Path(__file__).parent / "skills"
    for child in sorted(skills_dir.iterdir()):
        skill_md = child / "SKILL.md"
        if child.is_dir() and skill_md.exists():
            ctx.register_skill(child.name, skill_md)

Теперь агент может загружать ваши навыки по именам с пространством имён:

skill_view("my-plugin:my-workflow")   # → версия плагина
skill_view("my-workflow")              # → встроенная версия (без изменений)

Важные свойства:

• Навыки плагина только для чтения — они не попадают в ~/.hermes/skills/ и не редактируются через skill_manage.
• Навыки плагина не перечисляются в индексе <available_skills> системного промпта — их подключают явно.
• Короткие имена навыков не затрагиваются — пространство имён предотвращает коллизии со встроенными навыками.
• Когда агент загружает навык плагина, перед ним добавляется баннер с перечнем соседних навыков из того же плагина.

Управлять доступностью через переменные окружения

Если плагину нужен API-ключ:

# plugin.yaml — простой формат (обратно совместимый)
requires_env:
  - WEATHER_API_KEY

Если WEATHER_API_KEY не задан, плагин отключается с понятным сообщением. Никакого краша, никаких ошибок в агенте — просто «Plugin weather disabled (missing: WEATHER_API_KEY)».

При запуске hermes plugins install пользователю интерактивно предложат ввести все недостающие переменные из requires_env. Значения автоматически сохраняются в .env.

Для лучшего опыта при установке используйте расширенный формат с описаниями и ссылками:

# plugin.yaml — расширенный формат
requires_env:
  - name: WEATHER_API_KEY
    description: "API key for OpenWeather"
    url: "https://openweathermap.org/api"
    secret: true

Поле	Обязательно	Описание
name	Да	Имя переменной окружения
description	Нет	Показывается пользователю при установке
url	Нет	Где получить учётные данные
secret	Нет	Если true, ввод скрыт (как поле пароля)

Оба формата можно смешивать в одном списке. Уже установленные переменные молча пропускаются.

Отложенная установка опциональных Python-зависимостей

Если плагин оборачивает SDK, который есть не у каждого пользователя (вендорский SDK, тяжёлая ML-библиотека, платформо-специфичный пакет) — не делайте import на верхнем уровне модуля. Используйте хелпер tools.lazy_deps.ensure(...) внутри обработчика инструмента. Hermes установит пакет при первом использовании, если параметр security.allow_lazy_installs в конфиге разрешает это.

# tools.py
from tools.lazy_deps import ensure, FeatureUnavailable

def my_tool_handler(args, **kwargs):
    try:
        ensure("my-plugin.my-backend")   # key must be in LAZY_DEPS
    except FeatureUnavailable as exc:
        return {"error": str(exc)}

    import my_backend_sdk   # safe now
    ...

Два правила модели безопасности из tools/lazy_deps.py:

Правило	Почему
Ключ фичи должен быть в дереве LAZY_DEPS	Предотвращает ситуацию, когда вредоносный конфиг вынуждает Hermes устанавливать произвольные пакеты — допустимы только спеки, которые Hermes поставляет сам
Спецификации — только PyPI по имени	Никаких --index-url, git+https:// или file:-путей. Версии фиксируются через PEP 440 ("my-sdk>=1.2,<2") внутри записи в allowlist

Для сторонних плагинов, распространяемых через pip, объявите опциональные зависимости как [project.optional-dependencies] extras в вашем pyproject.toml и попросите пользователей запустить pip install your-plugin[backend] — этот путь не проходит через lazy_deps. Механизм отложенной установки полезен прежде всего для встроенных плагинов, где жёсткая зависимость раздувала бы базовый footprint Hermes.

Если глобально задано security.allow_lazy_installs: false, ensure() сразу выбрасывает FeatureUnavailable с подсказкой по устранению — ваш плагин должен перехватить это и деградировать корректно (вернуть результат с ошибкой, а не ронять цикл инструментов).

Потокобезопасные ленивые синглтоны

Плагины часто кэшируют дорогой объект — SDK-клиент, HTTP-сессию, пул соединений — в переменной уровня модуля, которая создаётся при первом обращении:

_client = None

def get_client():
    global _client
    if _client is not None:
        return _client
    _client = ExpensiveClient(...)   # ← TOCTOU race
    return _client

Это грабли. Hermes гоняет несколько потоков в одном процессе (делегированные вызовы инструментов, фоновые воркеры, форк самоулучшения), так что два потока могут зайти в get_client() до того, как _client присвоен. Оба пройдут проверку is not None, оба выполнят дорогую сборку, и вторая запись затрёт первую — утечёт тот ресурс, который открыл проигравший (соединение, файловый дескриптор, фоновый поток).

Не пишите блокировку руками. Возьмите хелперы из plugins/plugin_utils.py:

from plugins.plugin_utils import lazy_singleton, SingletonSlot

# Аксессор без аргументов → навесьте декоратор:
@lazy_singleton
def get_client():
    return ExpensiveClient(load_config())   # runs exactly once

client = get_client()    # safe across threads
get_client.reset()       # drop the instance (tests / teardown)


# Аксессор с аргументом для сборки → используйте слот:
_slot: SingletonSlot = SingletonSlot()

def get_client(config=None):
    return _slot.get(lambda: ExpensiveClient(resolve(config)))

def reset_client():
    _slot.reset()

Оба сериализуют конкурентные первые вызовы через двойную проверку с блокировкой и запускают фабрику не более одного раза. Если фабрика бросает исключение, ничего не кэшируется, и следующий вызов повторит попытку. Эталонный потребитель — плагин памяти honcho (plugins/memory/honcho/client.py).

Правило большого пальца: всякий раз, когда вы пишете global _something, за которым идёт проверка is None и сборка, берите вместо этого один из этих хелперов.

Условная доступность инструментов

Для инструментов, зависящих от опциональных библиотек:

ctx.register_tool(
    name="my_tool",
    schema={...},
    handler=my_handler,
    check_fn=lambda: _has_optional_lib(),  # False = инструмент скрыт от модели
)

Переопределение встроенного инструмента

Чтобы заменить встроенный инструмент своей реализацией (например, поменять стандартный браузерный инструмент на headed-Chrome CDP бэкенд, или заменить web_search корпоративным индексом), передайте override=True:

def register(ctx):
    ctx.register_tool(
        name="browser_navigate",             # то же имя, что у встроенного
        toolset="plugin_my_browser",         # ваше пространство имён
        schema={...},
        handler=my_custom_navigate,
        override=True,                       # явное разрешение
    )

Без override=True реестр отклоняет любую регистрацию, которая затеняла бы существующий инструмент из другого набора инструментов — это защищает от случайных перезаписей. Переопределение логируется на уровне INFO, так что его видно в ~/.hermes/logs/agent.log. Плагины загружаются после встроенных инструментов, поэтому порядок регистрации правильный: ваш обработчик заменяет встроенный.

Регистрация нескольких хуков

def register(ctx):
    ctx.register_hook("pre_tool_call", before_any_tool)
    ctx.register_hook("post_tool_call", after_any_tool)
    ctx.register_hook("pre_llm_call", inject_memory)
    ctx.register_hook("on_session_start", on_new_session)
    ctx.register_hook("on_session_end", on_session_end)

Справочник хуков

Каждый хук подробно описан в справочнике хуков событий — сигнатуры колбэков, таблицы параметров, когда именно срабатывает каждый хук и примеры. Краткая сводка:

Хук	Когда срабатывает	Сигнатура колбэка	Возвращает
pre_tool_call	До выполнения любого инструмента	tool_name: str, args: dict, task_id: str	игнорируется
post_tool_call	После возврата любого инструмента	tool_name: str, args: dict, result: str, task_id: str, duration_ms: int	игнорируется
pre_llm_call	Раз за ход, до цикла вызовов инструментов	session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str	инъекция контекста
post_llm_call	Раз за ход, после цикла вызовов (только успешные ходы)	session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str	игнорируется
on_session_start	Создана новая сессия (только первый ход)	session_id: str, model: str, platform: str	игнорируется
on_session_end	Конец каждого вызова run_conversation + выход CLI	session_id: str, completed: bool, interrupted: bool, model: str, platform: str	игнорируется
on_session_finalize	CLI/шлюз завершает активную сессию	session_id: str | None, platform: str	игнорируется
on_session_reset	Шлюз подключает новый ключ сессии (/new, /reset)	session_id: str, platform: str	игнорируется

Большинство хуков — наблюдатели типа «выстрелил и забыл»: их возвращаемые значения игнорируются. Исключение — pre_llm_call: он может вставлять контекст в разговор.

Все колбэки должны принимать **kwargs для обратной совместимости. Если колбэк хука падает с ошибкой, она логируется, и выполнение продолжается. Остальные хуки и агент работают в штатном режиме.

Инъекция контекста через pre_llm_call

Единственный хук, возвращаемое значение которого имеет значение. Когда колбэк pre_llm_call возвращает dict с ключом "context" (или просто строку), Hermes вставляет этот текст в сообщение пользователя текущего хода. На этом механизме строятся плагины памяти, RAG-интеграции, guardrails и любые плагины, которым нужно снабдить модель дополнительным контекстом.

Формат возврата

# Dict с ключом context
return {"context": "Recalled memories:\n- User prefers dark mode\n- Last project: hermes-agent"}

# Просто строка (эквивалентно форме с dict)
return "Recalled memories:\n- User prefers dark mode"

# Возврат None или отсутствие return → инъекции нет (только наблюдение)
return None

Любой не-None, не-пустой возврат с ключом "context" (или непустая строка) собирается и добавляется к сообщению пользователя на текущий ход.

Как работает инъекция

Контекст добавляется к сообщению пользователя, а не в системный промпт. Это намеренное архитектурное решение:

• Сохранение кэша промпта — системный промпт остаётся одинаковым между ходами. Anthropic и OpenRouter кэшируют префикс системного промпта, поэтому его стабильность экономит 75%+ входных токенов в многоходовых разговорах. Если бы плагины изменяли системный промпт, каждый ход был бы промахом кэша.
• Эфемерность — инъекция происходит только в момент вызова API. Оригинальное сообщение пользователя в истории разговора никогда не мутирует, ничего не сохраняется в базу сессии.
• Системный промпт — территория Hermes — он содержит модель-специфичные инструкции, правила применения инструментов, настройки личности и закэшированный контент навыков. Плагины вносят контекст рядом с вводом пользователя, а не изменяя базовые инструкции агента.

Пример: плагин вспоминания памяти

"""Memory plugin — recalls relevant context from a vector store."""

import httpx

MEMORY_API = "https://your-memory-api.example.com"

def recall_context(session_id, user_message, is_first_turn, **kwargs):
    """Called before each LLM turn. Returns recalled memories."""
    try:
        resp = httpx.post(f"{MEMORY_API}/recall", json={
            "session_id": session_id,
            "query": user_message,
        }, timeout=3)
        memories = resp.json().get("results", [])
        if not memories:
            return None  # nothing to inject

        text = "Recalled context from previous sessions:\n"
        text += "\n".join(f"- {m['text']}" for m in memories)
        return {"context": text}
    except Exception:
        return None  # fail silently, don't break the agent

def register(ctx):
    ctx.register_hook("pre_llm_call", recall_context)

Пример: плагин guardrails

"""Guardrails plugin — enforces content policies."""

POLICY = """You MUST follow these content policies for this session:
- Never generate code that accesses the filesystem outside the working directory
- Always warn before executing destructive operations
- Refuse requests involving personal data extraction"""

def inject_guardrails(**kwargs):
    """Injects policy text into every turn."""
    return {"context": POLICY}

def register(ctx):
    ctx.register_hook("pre_llm_call", inject_guardrails)

Пример: хук только для наблюдения (без инъекции)

"""Analytics plugin — tracks turn metadata without injecting context."""

import logging
logger = logging.getLogger(__name__)

def log_turn(session_id, user_message, model, is_first_turn, **kwargs):
    """Fires before each LLM call. Returns None — no context injected."""
    logger.info("Turn: session=%s model=%s first=%s msg_len=%d",
                session_id, model, is_first_turn, len(user_message or ""))
    # No return → no injection

def register(ctx):
    ctx.register_hook("pre_llm_call", log_turn)

Несколько плагинов возвращают контекст

Когда несколько плагинов возвращают контекст из pre_llm_call, их выводы объединяются через двойной перенос строки и добавляются к сообщению пользователя вместе. Порядок соответствует порядку обнаружения плагинов (алфавитный, по имени директории плагина).

Регистрация CLI-команд

Плагины могут добавлять собственное дерево подкоманд hermes <plugin>:

def _my_command(args):
    """Handler for hermes my-plugin <subcommand>."""
    sub = getattr(args, "my_command", None)
    if sub == "status":
        print("All good!")
    elif sub == "config":
        print("Current config: ...")
    else:
        print("Usage: hermes my-plugin <status|config>")

def _setup_argparse(subparser):
    """Build the argparse tree for hermes my-plugin."""
    subs = subparser.add_subparsers(dest="my_command")
    subs.add_parser("status", help="Show plugin status")
    subs.add_parser("config", help="Show plugin config")
    subparser.set_defaults(func=_my_command)

def register(ctx):
    ctx.register_tool(...)
    ctx.register_cli_command(
        name="my-plugin",
        help="Manage my plugin",
        setup_fn=_setup_argparse,
        handler_fn=_my_command,
    )

После регистрации пользователи смогут запускать hermes my-plugin status, hermes my-plugin config и т.д.

Плагины провайдеров памяти используют другой подход — через соглашение: добавьте функцию register_cli(subparser) в файл cli.py вашего плагина. Система обнаружения плагинов памяти найдёт её автоматически — вызов ctx.register_cli_command() не нужен. Подробности — в руководстве по плагинам провайдеров памяти.

Привязка к активному провайдеру: CLI-команды плагинов памяти появляются только тогда, когда их провайдер задан активным в параметре memory.provider конфига. Если пользователь не настроил ваш провайдер, ваши команды не захламляют вывод --help.

Регистрация слэш-команд

Плагины могут регистрировать слэш-команды внутри сессии — команды, которые пользователь вводит в ходе разговора (например, /lcm status или /ping). Они работают как в CLI, так и в шлюзах (Telegram, Discord и т.д.).

def _handle_status(raw_args: str) -> str:
    """Handler for /mystatus — called with everything after the command name."""
    if raw_args.strip() == "help":
        return "Usage: /mystatus [help|check]"
    return "Plugin status: all systems nominal"

def register(ctx):
    ctx.register_command(
        "mystatus",
        handler=_handle_status,
        description="Show plugin status",
    )

После регистрации пользователи могут вводить /mystatus в любой сессии. Команда появляется в автодополнении, выводе /help и меню Telegram-бота.

Сигнатура: ctx.register_command(name: str, handler: Callable, description: str = "", args_hint: str = "")

Параметр	Тип	Описание
name	str	Имя команды без начального слэша (например, "lcm", "mystatus")
handler	Callable[[str], str | None]	Вызывается со строкой аргументов. Может быть async.
description	str	Отображается в /help, автодополнении и меню Telegram-бота

Ключевые отличия от register_cli_command():

	register_command()	register_cli_command()
Вызывается как	/name в сессии	hermes name в терминале
Где работает	CLI-сессии, Telegram, Discord и т.д.	Только терминал
Обработчик получает	Строку сырых аргументов	argparse Namespace
Сценарий использования	Диагностика, статус, быстрые действия	Сложные деревья подкоманд, мастера настройки

Защита от конфликтов: если плагин пытается зарегистрировать имя, совпадающее со встроенной командой (help, model, new и т.д.), регистрация молча отклоняется с предупреждением в логе. Встроенные команды всегда имеют приоритет.

Асинхронные обработчики: диспетчер шлюза автоматически определяет и awaits асинхронные обработчики, так что можно использовать как синхронные, так и асинхронные функции:

async def _handle_check(raw_args: str) -> str:
    result = await some_async_operation()
    return f"Check result: {result}"

def register(ctx):
    ctx.register_command("check", handler=_handle_check, description="Run async check")

Вызов инструментов из слэш-команд

Обработчики слэш-команд, которым нужно оркестрировать инструменты (запустить субагент через delegate_task, вызвать file_edit и т.д.), должны использовать ctx.dispatch_tool() вместо прямого обращения к внутренностям фреймворка. Контекст родительского агента (подсказки о рабочем пространстве, спиннер, наследование модели) подключается автоматически.

def register(ctx):
    def _handle_deliver(raw_args: str):
        result = ctx.dispatch_tool(
            "delegate_task",
            {
                "goal": raw_args,
                "toolsets": ["terminal", "file", "web"],
            },
        )
        return result

    ctx.register_command(
        "deliver",
        handler=_handle_deliver,
        description="Delegate a goal to a subagent",
    )

Сигнатура: ctx.dispatch_tool(name: str, args: dict, *, parent_agent=None) -> str

Параметр	Тип	Описание
name	str	Имя инструмента в реестре (например, "delegate_task", "file_edit")
args	dict	Аргументы инструмента в том же виде, в каком их передаёт модель
parent_agent	Agent | None	Необязательное переопределение. Если не задан, берётся из текущего CLI-агента (или деградирует в режиме шлюза)

Поведение во время выполнения:

• Режим CLI: parent_agent берётся из активного CLI-агента, поэтому подсказки о рабочем пространстве, спиннер и выбор модели наследуются как ожидается.
• Режим шлюза: CLI-агента нет, поэтому инструменты деградируют корректно — рабочее пространство читается из сконфигурированной рабочей директории терминала, спиннер не показывается.
• Явное переопределение: если вызывающий передаёт parent_agent= явно, это значение сохраняется без перезаписи.

Это публичный, стабильный интерфейс для вызова инструментов из команд плагинов. Плагины не должны обращаться к ctx._cli_ref.agent или аналогичному приватному состоянию.

Обработка кликов по кнопкам Slack Block Kit

Плагины, которые постят сообщения Block Kit с интерактивными элементами (кнопки, overflow-меню, datepicker и т.д.), могут зарегистрировать обработчики кликов прямо в адаптере Slack — без monkey-патчинга slack_bolt.AsyncApp.

def register(ctx):
    async def _on_approve(ack, body, action):
        # ack within 3 seconds — slack_bolt requirement.
        await ack()
        # body["channel"]["id"], body["user"]["id"], body["message"]["ts"]
        # action["action_id"], action["value"]
        sweep_id = (action.get("value") or "").split("|", 1)[-1]
        # ...do the deterministic work, then post a follow-up.

    ctx.register_slack_action_handler("inbox_sweep_approve", _on_approve)

Сигнатура: ctx.register_slack_action_handler(action_id, callback) -> None

Параметр	Тип	Описание
action_id	str | re.Pattern | dict	Всё, что принимает slack_bolt.App.action(): литеральный action_id, скомпилированный regex для нескольких id или dict-ограничение вида {"action_id": "...", "block_id": "..."}
callback	async-вызываемое	Получает (ack, body, action) по соглашению slack_bolt

Поведение во время выполнения:

• Обработчик ставится в очередь на этапе загрузки плагина и подключается к slack_bolt.AsyncApp адаптера, когда платформа Slack устанавливает соединение.
• Каждый колбэк обёрнут защитно: если ваш обработчик бросает исключение, шлюз логирует ошибку и по возможности подтверждает клик, чтобы Slack перестал слать повторы.
• Действуют обычные правила slack_bolt — await ack() в течение 3 секунд, затем более долгая работа.
• В мультиворкспейсных развёртываниях обработчик срабатывает на клики из любого подключённого воркспейса; если нужно ограничить поведение, используйте body["team"]["id"].

Это публичный способ для плагинов участвовать в интерактиве Slack. Старые плагины могут патчить SlackAdapter.connect; предпочитайте этот API.

Специализированные типы плагинов

Помимо общей поверхности, Hermes имеет пять специализированных типов плагинов. Каждый располагается в директории plugins/<category>/<name>/ (встроенные) или ~/.hermes/plugins/<category>/<name>/ (пользовательские). Контракт отличается по категории — выберите нужную и прочитайте полное руководство.

Плагины модельных провайдеров — добавление LLM-бэкенда

Положите профиль в plugins/model-providers/<name>/:

# plugins/model-providers/acme/__init__.py
from providers import register_provider
from providers.base import ProviderProfile

register_provider(ProviderProfile(
    name="acme",
    aliases=("acme-inference",),
    display_name="Acme Inference",
    env_vars=("ACME_API_KEY", "ACME_BASE_URL"),
    base_url="https://api.acme.example.com/v1",
    auth_type="api_key",
    default_aux_model="acme-small-fast",
    fallback_models=("acme-large-v3", "acme-medium-v3"),
))

# plugins/model-providers/acme/plugin.yaml
name: acme-provider
kind: model-provider
version: 1.0.0
description: Acme Inference — OpenAI-compatible direct API

Обнаруживается лениво при первом вызове get_provider_profile() или list_providers() — auth.py, config.py, doctor.py, models.py, runtime_provider.py и транспорт chat_completions подключаются к нему автоматически. Пользовательские плагины переопределяют встроенные по имени.

Полное руководство: Плагины модельных провайдеров — справочник полей, переопределяемые хуки (prepare_messages, build_extra_body, build_api_kwargs_extras, fetch_models), выбор api_mode, типы аутентификации, тестирование.

Платформенные плагины — добавление канала шлюза

Положите адаптер в plugins/platforms/<name>/:

# plugins/platforms/myplatform/adapter.py
from gateway.platforms.base import BasePlatformAdapter

class MyPlatformAdapter(BasePlatformAdapter):
    async def connect(self): ...
    async def send(self, chat_id, text): ...
    async def disconnect(self): ...

def check_requirements():
    import os
    return bool(os.environ.get("MYPLATFORM_TOKEN"))

def _env_enablement():
    import os
    tok = os.getenv("MYPLATFORM_TOKEN", "").strip()
    if not tok:
        return None
    return {"token": tok}

def register(ctx):
    ctx.register_platform(
        name="myplatform",
        label="MyPlatform",
        adapter_factory=lambda cfg: MyPlatformAdapter(cfg),
        check_fn=check_requirements,
        required_env=["MYPLATFORM_TOKEN"],
        # Auto-populate PlatformConfig.extra from env so env-only setups
        # show up in `hermes gateway status` without SDK instantiation.
        env_enablement_fn=_env_enablement,
        # Opt in to cron delivery: `deliver=myplatform` routes to this var.
        cron_deliver_env_var="MYPLATFORM_HOME_CHANNEL",
        emoji="💬",
        platform_hint="You are chatting via MyPlatform. Keep responses concise.",
    )

# plugins/platforms/myplatform/plugin.yaml
name: myplatform-platform
label: MyPlatform
kind: platform
version: 1.0.0
description: MyPlatform gateway adapter
requires_env:
  - name: MYPLATFORM_TOKEN
    description: "Bot token from the MyPlatform console"
    password: true
optional_env:
  - name: MYPLATFORM_HOME_CHANNEL
    description: "Default channel for cron delivery"
    password: false

Полное руководство: Добавление платформенных адаптеров — полный контракт BasePlatformAdapter, маршрутизация сообщений, ограничение по аутентификации, интеграция с мастером настройки. Рабочий пример только на stdlib — plugins/platforms/irc/.

Плагины провайдеров памяти — добавление кросс-сессионного хранилища знаний

Положите реализацию MemoryProvider в plugins/memory/<name>/:

# plugins/memory/my-memory/__init__.py
from agent.memory_provider import MemoryProvider

class MyMemoryProvider(MemoryProvider):
    @property
    def name(self) -> str:
        return "my-memory"

    def is_available(self) -> bool:
        import os
        return bool(os.environ.get("MY_MEMORY_API_KEY"))

    def initialize(self, session_id: str, **kwargs) -> None:
        self._session_id = session_id

    def sync_turn(self, user_content, assistant_content, *,
                  session_id="", messages=None) -> None:
        ...

    def prefetch(self, query, *, session_id="") -> str:
        ...

    def get_tool_schemas(self) -> list[dict]:
        return []   # обязательный @abstractmethod — см. полное руководство

def register(ctx):
    ctx.register_memory_provider(MyMemoryProvider())

Провайдеры памяти работают в режиме одного выбора — активен только один, задаётся через memory.provider в config.yaml.

Полное руководство: Плагины провайдеров памяти — полный ABC MemoryProvider, контракт потоков, изоляция профилей, регистрация CLI-команд через cli.py.

Плагины движков контекста — замена компрессора контекста

# plugins/context_engine/my-engine/__init__.py
from agent.context_engine import ContextEngine

class MyContextEngine(ContextEngine):
    @property
    def name(self) -> str:
        return "my-engine"

    def update_from_response(self, usage) -> None: ...
    def should_compress(self, prompt_tokens: int = None) -> bool: ...
    def compress(self, messages, current_tokens=None, focus_topic=None) -> list: ...

def register(ctx):
    ctx.register_context_engine(MyContextEngine())

Движки контекста работают в режиме одного выбора — задаётся через context.engine в config.yaml.

Полное руководство: Плагины движков контекста.

Бэкенды генерации изображений

Положите провайдер в plugins/image_gen/<name>/:

# plugins/image_gen/my-imggen/__init__.py
from agent.image_gen_provider import ImageGenProvider

class MyImageGenProvider(ImageGenProvider):
    @property
    def name(self) -> str:
        return "my-imggen"

    def is_available(self) -> bool: ...
    def generate(self, prompt: str, aspect_ratio="landscape", **kwargs) -> dict:
        # returns success_response(...) / error_response(...)
        ...

def register(ctx):
    ctx.register_image_gen_provider(MyImageGenProvider())

# plugins/image_gen/my-imggen/plugin.yaml
name: my-imggen
kind: backend
version: 1.0.0
description: Custom image generation backend

Полное руководство: Плагины провайдеров генерации изображений — полный ABC ImageGenProvider, метаданные list_models() / get_setup_schema(), хелперы success_response()/error_response(), вывод base64 vs URL, переопределения пользователя, распространение через pip.

Примеры: plugins/image_gen/openai/ (DALL-E / GPT-Image через OpenAI SDK), plugins/image_gen/openai-codex/, plugins/image_gen/xai/ (Grok image gen).

Не-Python поверхности расширений

Hermes принимает расширения, которые не являются Python-плагинами. Они показаны в таблице расширяемых интерфейсов; разделы ниже кратко описывают каждый стиль.

MCP-серверы — регистрация внешних инструментов

Серверы Model Context Protocol (MCP) регистрируют свои инструменты в Hermes без Python-плагина. Объявите их в ~/.hermes/config.yaml:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    timeout: 120

  linear:
    url: "https://mcp.linear.app/sse"
    auth:
      type: "oauth"

Hermes подключается к каждому серверу при запуске, получает список его инструментов и регистрирует их рядом со встроенными. LLM видит их точно так же, как любой другой инструмент. Полное руководство: MCP.

Хуки событий шлюза — срабатывание на жизненные события

Положите манифест и обработчик в ~/.hermes/hooks/<name>/:

# ~/.hermes/hooks/long-task-alert/HOOK.yaml
name: long-task-alert
description: Send a push notification when a long task finishes
events:
  - agent:end

# ~/.hermes/hooks/long-task-alert/handler.py
async def handle(event_type: str, context: dict) -> None:
    if context.get("duration_seconds", 0) > 120:
        # send notification …
        pass

События: gateway:startup, session:start, session:end, session:reset, agent:start, agent:step, agent:end и маска command:*. Ошибки в хуках перехватываются и логируются — они никогда не блокируют основной pipeline.

Полное руководство: Хуки событий шлюза.

Шелл-хуки — запуск shell-команды на вызовы инструментов

Если нужно просто выполнять скрипт при срабатывании инструмента (уведомления, аудит-логи, оповещения на рабочем столе, автоформатирование), используйте шелл-хуки в config.yaml — Python не нужен:

hooks:
  - event: post_tool_call
    command: "notify-send 'Tool ran: {tool_name}'"
    when:
      tools: [terminal, patch, write_file]

Поддерживаются все те же события, что и в Python-хуках плагинов (pre_tool_call, post_tool_call, pre_llm_call, post_llm_call, on_session_start, on_session_end, pre_gateway_dispatch), плюс структурированный JSON-вывод для блокирующих решений pre_tool_call.

Полное руководство: Шелл-хуки.

Источники навыков — добавление собственного реестра навыков

Если у вас есть GitHub-репозиторий с навыками (или вы хотите брать из общественного индекса за пределами встроенных источников), добавьте его как тап:

hermes skills tap add myorg/skills-repo
hermes skills search my-workflow --source myorg/skills-repo
hermes skills install myorg/skills-repo/my-workflow

Публикация собственного тапа — просто GitHub-репозиторий с директориями skills/<skill-name>/SKILL.md. Никакого сервера или регистрации в реестре не нужно.

Полные руководства: Skills Hub · Публикация собственного тапа (структура репозитория, минимальный пример, нестандартные пути, уровни доверия).

TTS / STT через шаблоны команд

Любой CLI, читающий или записывающий аудио или текст, можно подключить через config.yaml — Python-код не нужен:

tts:
  provider: voxcpm
  providers:
    voxcpm:
      type: command
      command: "voxcpm --ref ~/voice.wav --text-file {input_path} --out {output_path}"
      output_format: mp3
      voice_compatible: true

Для STT укажите HERMES_LOCAL_STT_COMMAND как shell-шаблон. Поддерживаемые плейсхолдеры: {input_path}, {output_path}, {format}, {voice}, {model}, {speed} (TTS); {input_path}, {output_dir}, {language}, {model} (STT). Любой CLI, работающий с путями, автоматически становится плагином.

Полные руководства: TTS: провайдеры на основе команд · STT.

Распространение через pip

Для публичного распространения плагинов добавьте точку входа в Python-пакет:

# pyproject.toml
[project.entry-points."hermes_agent.plugins"]
my-plugin = "my_plugin_package"

pip install hermes-plugin-calculator
# Плагин автоматически обнаруживается при следующем запуске Hermes

Распространение для NixOS

Пользователи NixOS могут устанавливать ваш плагин декларативно, если вы предоставите pyproject.toml с точками входа:

Плагины через точки входа (рекомендуется для распространения):

# User's configuration.nix
services.hermes-agent.extraPythonPackages = [
  (pkgs.python312Packages.buildPythonPackage {
    pname = "my-plugin";
    version = "1.0.0";
    src = pkgs.fetchFromGitHub {
      owner = "you";
      repo = "hermes-my-plugin";
      rev = "v1.0.0";
      hash = "sha256-...";  # nix-prefetch-url --unpack
    };
    format = "pyproject";
    build-system = [ pkgs.python312Packages.setuptools ];
  })
];

Директорийные плагины (pyproject.toml не нужен):

services.hermes-agent.extraPlugins = [
  (pkgs.fetchFromGitHub {
    owner = "you";
    repo = "hermes-my-plugin";
    rev = "v1.0.0";
    hash = "sha256-...";
  })
];

Полная документация — в руководстве по настройке Nix: overlay, проверка коллизий.

Распространённые ошибки

Обработчик не возвращает JSON-строку:

# Неверно — возвращает dict
def handler(args, **kwargs):
    return {"result": 42}

# Верно — возвращает JSON-строку
def handler(args, **kwargs):
    return json.dumps({"result": 42})

Нет **kwargs в сигнатуре обработчика:

# Неверно — сломается, если Hermes передаст дополнительный контекст
def handler(args):
    ...

# Верно
def handler(args, **kwargs):
    ...

Обработчик бросает исключения:

# Неверно — исключение распространяется, вызов инструмента падает
def handler(args, **kwargs):
    result = 1 / int(args["value"])  # ZeroDivisionError!
    return json.dumps({"result": result})

# Верно — перехватывайте и возвращайте JSON с ошибкой
def handler(args, **kwargs):
    try:
        result = 1 / int(args.get("value", 0))
        return json.dumps({"result": result})
    except Exception as e:
        return json.dumps({"error": str(e)})

Слишком расплывчатое описание в схеме:

# Плохо — модель не понимает, когда использовать инструмент
"description": "Does stuff"

# Хорошо — модель точно знает когда и как
"description": "Evaluate a mathematical expression. Use for arithmetic, trig, logarithms. Supports: +, -, *, /, **, sqrt, sin, cos, log, pi, e."