Hermes Agent от Nous Research — это AI-агент с открытым исходным кодом, который расширяется плагинами: собственными инструментами, хуками, слэш-командами и интеграциями. В статье — как установить и включить плагин, какие плагины уже встроены по умолчанию, почему они подключаются только вручную и как написать свой первый плагин за 10 минут.
Что такое плагины в Hermes Agent?
Плагин — это способ добавить агенту новую возможность без изменения основного кода: папка в каталоге ~/.hermes/plugins/, в которой лежат файл-манифест plugin.yaml и Python-код. После перезапуска Hermes находит плагин, и модель может сразу вызывать новые инструменты наравне со встроенными.
Минимальный плагин состоит из двух файлов. Первый — манифест:
# ~/.hermes/plugins/hello-world/plugin.yaml
name: hello-world
version: "1.0"
description: A minimal example plugin
Второй — код с функцией регистрации:
# ~/.hermes/plugins/hello-world/__init__.py
def register(ctx):
ctx.register_tool(
name="hello_world",
toolset="custom",
schema={
"name": "hello_world",
"description": "Say hello",
"parameters": {"type": "object", "properties": {}},
},
handler=lambda args, **kw: "Hello, world!",
)
После перезапуска Hermes модель может вызвать инструмент hello_world так же, как любой встроенный инструмент. Это и есть базовая идея плагинов: вы описываете агенту, что умеет новый инструмент, и он начинает им пользоваться.
Что умеют плагины Hermes?
Плагины — это не только новые инструменты. Через объект ctx внутри функции register(ctx) доступен полный набор точек расширения:
| Возможность | Как это делается |
|---|---|
| Новые инструменты для модели | `ctx.register_tool(name=…, schema=…, handler=…)` |
| Хуки — реакции на события | `ctx.register_hook(«post_tool_call», callback)` |
| Слэш-команды в чате | `ctx.register_command(name, handler, description)` — команда `/имя` |
| Подкоманды CLI | `ctx.register_cli_command(…)` — команда `hermes ` |
| Вызов других инструментов | `ctx.dispatch_tool(name, args)` — с контекстом родительского агента |
| Внедрение сообщений в диалог | `ctx.inject_message(«текст», role=»user»)` |
| Собственные файлы данных | обычные файлы в папке плагина, например `data/languages.yaml` |
| Встроенные скиллы | `ctx.register_skill(name, path)` — загружаются как `plugin:skill` |
| Проверка API-ключей | `requires_env: [API_KEY]` в `plugin.yaml` — плагин не загрузится без ключа |
| Распространение через pip | entry point `hermes_agent.plugins` в `pyproject.toml` |
| Новая платформа шлюза | `ctx.register_platform(…)` — свой адаптер Discord, Telegram, IRC |
| Генерация изображений и видео | `ctx.register_image_gen_provider(…)`, `ctx.register_video_gen_provider(…)` |
| Своя система сжатия контекста | `ctx.register_context_engine(…)` |
| Своя память | класс `MemoryProvider` в `plugins/memory//` |
| Свой LLM-провайдер | `register_provider(ProviderProfile(…))` в `plugins/model-providers//` |
| Одноразовый вызов LLM из плагина | `ctx.llm.complete(…)` — использует модель и авторизацию пользователя |
Плагины делятся на четыре типа. Общие плагины (инструменты, хуки, слэш-команды) можно включать в любых комбинациях. Провайдеры памяти и движки контекста — по одному активному одновременно. Модельные провайдеры регистрируются все сразу, а пользователь выбирает один через --provider или конфиг.
Отдельный и важный случай — внешние инструменты по протоколу MCP. Их подключать проще, чем писать плагин: достаточно объявить сервер в config.yaml, и Hermes сам обнаружит и зарегистрирует его инструменты. Плагины нужны, когда готового MCP-сервера нет или требуется глубоко встроиться в жизнь агента: хуки, слэш-команды, собственная платформа.
Как установить плагин и включить его?
Установка плагина из GitHub-репозитория делается одной командой:
hermes plugins install user/repo
После установки Hermes спросит: Enable 'name' now? [y/N] — по умолчанию ответ «нет». Для скриптовой установки есть флаги:
hermes plugins install user/repo --enable # установить И включить
hermes plugins install user/repo --no-enable # установить, но не включать
Полный набор команд управления:
hermes plugins # интерактивный интерфейс (пробел — вкл/выкл)
hermes plugins list # таблица: enabled / disabled / not enabled
hermes plugins enable имя # добавить в allow-list
hermes plugins disable имя # убрать из allow-list и добавить в disabled
hermes plugins update имя # обновить до последней версии
hermes plugins remove имя # удалить
Плагин можно включить и вручную — в файле ~/.hermes/config.yaml:
plugins:
enabled:
- my-tool-plugin
- disk-cleanup
disabled: # опциональный deny-list
- noisy-plugin
В запущенной сессии команда /plugins показывает, какие плагины загружены прямо сейчас.
Какие плагины уже встроены в Hermes?
Hermes поставляется с набором встроенных плагинов. Они лежат в репозитории и подключаются той же командой hermes plugins enable . Все они опциональны — по умолчанию не загружаются.
| Плагин | Что делает |
|---|---|
| `disk-cleanup` | Автоматически отслеживает временные файлы (тесты, кэш, логи cron) и удаляет их в конце сессии. Слэш-команда `/disk-cleanup` с режимами status, dry-run, quick, deep |
| `security-guidance` | Проверяет код на 25 опасных паттернов (pickle.load, eval, os.system, shell=True и другие) и добавляет предупреждение к результату инструмента. Набор правил — Apache-2.0 форк Anthropic claude-plugins-official |
| `observability/langfuse` | Отправляет трассировки сессий, LLM-вызовов и инструментов в Langfuse |
| `observability/nemo_relay` | Передаёт события наблюдаемости в NVIDIA NeMo |
| `teams_pipeline` | Пайплайн совещаний Microsoft Teams: суммаризация по транскрипту через Graph API |
| `spotify` | Нативные инструменты Spotify: воспроизведение, очередь, поиск, плейлисты, альбомы, библиотека (7 инструментов) |
| `google_meet` | Подключение к Google Meet, субтитры в реальном времени |
| `image_gen/openai` | Генерация изображений через OpenAI gpt-image-2 |
| `image_gen/openai-codex` | Генерация изображений через OpenAI Codex OAuth |
| `image_gen/xai` | Генерация изображений через xAI grok-2-image |
| `hermes-achievements` | Достижения в стиле Steam-бейджей, собранные из реальной истории сессий |
| `kanban/dashboard` | Интерфейс канбан-доски для мультиагентного диспетчера |
Провайдеры памяти (Honcho, Mem0, Supermemory и другие) и движки контекста — это тоже плагины, но управляются они отдельно: через hermes memory и настройку context.engine в конфиге.
Как написать свой плагин за 10 минут?
Разберём на реальном примере из документации — плагин-калькулятор с двумя инструментами: calculate (вычислить выражение) и unit_convert (перевести единицы измерения). Для него нужны четыре файла.
Шаг 1. Создайте папку и манифест
mkdir -p ~/.hermes/plugins/calculator
# ~/.hermes/plugins/calculator/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
Поля provides_tools и provides_hooks — списки того, что регистрирует плагин. Опционально можно добавить author и requires_env — список переменных окружения, без которых плагин не загрузится.
Шаг 2. Опишите схемы инструментов
Схема — это то, что читает модель, чтобы понять, когда вызывать инструмент:
# ~/.hermes/plugins/calculator/schemas.py
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)."
),
"parameters": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "Math expression to evaluate (e.g., '2**10', 'sqrt(144)')",
},
},
"required": ["expression"],
},
}
Описание (description) — главное: именно по нему модель решает, когда использовать ваш инструмент. Чем конкретнее, тем лучше.
Шаг 3. Напишите обработчики
# ~/.hermes/plugins/calculator/tools.py
import json, math
def calculate(args: dict, **kwargs) -> str:
expression = args.get("expression", "").strip()
if not expression:
return json.dumps({"error": "No expression provided"})
try:
result = eval(expression, {"__builtins__": {}}, {"sqrt": math.sqrt, "pi": math.pi, "e": math.e})
return json.dumps({"expression": expression, "result": result})
except Exception as e:
return json.dumps({"expression": expression, "error": f"Invalid: {e}"})
Правила обработчиков простые: принимать аргументы словарём, всегда возвращать JSON-строку (и при ошибке тоже), никогда не выбрасывать исключение, принимать **kwargs для совместимости.
Шаг 4. Зарегистрируйте плагин
# ~/.hermes/plugins/calculator/__init__.py
from .schemas import CALCULATE
from .tools import calculate
def register(ctx):
ctx.register_tool(name="calculate", toolset="custom", schema=CALCULATE, handler=calculate)
Функция register(ctx) вызывается один раз при старте. Если она упадёт с ошибкой — плагин просто отключится, а Hermes продолжит работать.
Шаг 5. Проверьте
Запустите hermes — в списке инструментов в баннере появятся calculator: calculate, unit_convert. Проверить состояние можно командой /plugins:
Plugins (1):
✓ calculator v1.0.0 (2 tools, 1 hooks)
Если плагин не появился, запустите отладку: HERMES_PLUGINS_DEBUG=1 hermes plugins list. Логи всегда пишутся в ~/.hermes/logs/agent.log.
Частые причины, почему плагин не виден: он не включён в конфиге (нужно hermes plugins enable ), неправильная структура папок (должно быть ~/.hermes/plugins//plugin.yaml, вложенность категорий — не больше одного уровня), отсутствует __init__.py или неверно указан kind в манифесте.
Почему плагины не подключаются автоматически?
По умолчанию все общие плагины выключены. Hermes находит их при сканировании, показывает в списке hermes plugins, но не загружает, пока вы явно не добавите имя в plugins.enabled. Это осознанное решение по безопасности: произвольный код из интернета не должен запускаться без вашего согласия.
У плагина три состояния:
| Состояние | Значение | В `plugins.enabled`? | В `plugins.disabled`? |
|---|---|---|---|
| `enabled` | Загрузится в следующей сессии | Да | Нет |
| `disabled` | Явно выключен — не загрузится, даже если в enabled | — | Да |
| `not enabled` | Найден, но никогда не включался | Нет | Нет |
Исключения есть только для «инфраструктуры», без которой Hermes не работает: встроенные платформы шлюза (IRC, Teams), встроенные бэкенды генерации изображений, провайдеры памяти и модельные провайдеры загружаются автоматически. А вот сторонние платформы и pip-плагины — только через allow-list.
При обновлении до версии с opt-in плагинами (схема конфига v21+) уже установленные пользовательские плагины автоматически переносятся в plugins.enabled — ничего не сломается. Встроенные плагины при этом grandfathering не получают: их нужно включить явно.
Хуки: какие события можно перехватывать?
Хук — это функция, которая вызывается в определённый момент жизни агента. Через хуки плагины могут логировать, блокировать или дополнять поведение:
| Хук | Когда срабатывает |
|---|---|
| `pre_tool_call` | Перед выполнением любого инструмента |
| `post_tool_call` | После возврата любого инструмента |
| `pre_llm_call` | Раз за ход, до цикла LLM — можно вернуть `{«context»: «…»}` для подстановки в сообщение |
| `post_llm_call` | Раз за ход, после успешного цикла LLM |
| `on_session_start` | Создана новая сессия (первый ход) |
| `on_session_end` | Конец каждого запуска диалога + выход из CLI |
| `on_session_finalize` | CLI/шлюз завершают активную сессию (`/new`, сборка мусора, выход) |
| `on_session_reset` | Шлюз меняет ключ сессии (`/new`, `/reset`, `/clear`) |
| `subagent_stop` | Раз на каждого ребёнка после `delegate_task` |
| `pre_gateway_dispatch` | Шлюз получил сообщение пользователя до авторизации — можно вернуть `skip`, `rewrite` или `allow` |
Отдельный приём — ctx.inject_message("текст", role="user"). Если агент простаивает, сообщение станет следующим входом и запустит новый ход; если агент работает — прервёт текущую операцию, как если бы пользователь написал сообщение. Так плагины-вебхуки и мосты сообщений «вталкивают» данные в диалог извне.
Где искать плагины и как их распространять?
Hermes сканирует плагины из пяти источников, в порядке приоритета:
/plugins// ~/.hermes/plugins// (личные)./.hermes/plugins// (для одного проекта; по умолчанию выключены, включаются через HERMES_ENABLE_PROJECT_PLUGINS=true)hermes_agent.plugins (пакеты из PyPI)services.hermes-agent.extraPlugins / extraPythonPackages (декларативные установки NixOS)При совпадении имён поздний источник побеждает: пользовательский плагин с тем же именем, что у встроенного, заменяет его.
Готовые плагины ищутся на GitHub (команда hermes plugins install owner/repo) и в PyPI. Если вы написали полезный плагин, его можно распространять как pip-пакет: добавьте в pyproject.toml секцию [project.entry-points."hermes_agent.plugins"] — и пользователи установят его обычным pip install.
FAQ
Нужно ли уметь программировать, чтобы пользоваться плагинами?
Нет. Установка и включение готового плагина — две команды: hermes plugins install user/repo и hermes plugins enable имя. Программирование нужно только если вы хотите написать собственный плагин — для этого достаточно базового Python.
Чем плагин отличается от скилла?
Скилл — это документ с инструкциями, который читает модель (процедурная память). Плагин — это исполняемый код: новые инструменты, хуки, команды. Скиллы учат агента действовать, плагины дают ему новые возможности. Плагин может встраивать свои скиллы — они загружаются как plugin:skill.
Безопасно ли ставить плагины из интернета?
Плагины из третьих источников не загружаются без явного согласия — нужно включить их в plugins.enabled. Но сам по себе плагин — это код с доступом к вашему окружению, поэтому ставьте только проверенные репозитории. Встроенный плагин security-guidance помогает ловить опасные паттерны в коде.
Как понять, что плагин работает?
Команда /plugins в сессии покажет загруженные плагины с количеством инструментов и хуков. Для диагностики: HERMES_PLUGINS_DEBUG=1 hermes plugins list — подробные логи сканирования, а в ~/.hermes/logs/agent.log всегда пишутся ошибки загрузки.
Можно ли отключить плагин без удаления?
Да. hermes plugins disable имя убирает плагин из allow-list и добавляет в deny-list. Он останется на диске, но не будет загружаться, пока вы снова не выполните hermes plugins enable имя.