Инструментарий Hermes Agent

Инструменты — единственный канал, через который Hermes Agent взаимодействует с внешним миром: чтение и запись файлов, выполнение команд, поиск в интернете, генерация изображений; все возможности предоставляются через инструменты.

У Hermes есть 70+ встроенных инструментов, организованных в 28 коллекций инструментов. В этой главе мы поочерёдно разберём основные инструменты, параметры и лучшие практики каждой коллекции инструментов.


Архитектура системы инструментов

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

Hermes использует трёхуровневую структуру для управления инструментами:

工具(Tool)          ← 单个可调用函数,如 read_file、web_search
  └── 工具集(Toolset)   ← 相关工具的逻辑分组,如 file、web
        └── 平台配置        ← 哪个平台加载哪些工具集

Ключевой принцип: Отключение набора инструментов приводит к тому, что его инструменты полностью исчезают из системного промпта — они не просто недоступны для вызова, но Агент вообще не подозревает об их существовании. Это и экономит токены, и не позволяет Агенту неправильно использовать инструменты, которые ему не следует использовать.

Способы управления наборами инструментов:

# TUI 交互式管理(推荐)
hermes tools

# 命令行管理
hermes tools list                # 列出所有工具及启用状态
hermes tools enable browser      # 启用指定工具集
hermes tools disable audio       # 禁用指定工具集

Настройка в config.yaml:

# 文件路径:~/.hermes/config.yaml
# 按平台指定启用的工具集
platform_toolsets:
  cli:
    - hermes-cli         # CLI 核心工具集
    - file
    - terminal
    - web
    - memory
    - skills

В настольной версии, в левом меню «Навыки и инструменты»:

Инструментами также можно управлять на панели управления, в левом меню навыков:


Наборы файловых и системных инструментов

Этот тип набора инструментов позволяет Агенту манипулировать локальной файловой системой, выполнять команды и управлять процессами.

file — файловые операции

Самый базовый набор инструментов; Агент полагается на него почти во всех задачах для чтения и записи файлов.

ИнструментыОсобенностиКлючевые параметры
read_fileЧтение содержимого файлаfile_path (обязательный), offset (начальная строка), limit (максимальное количество строк)
write_fileСоздать или перезаписать файлfile_path (обязательно), content (обязательно)
edit_fileТочно заменять текст в файлахfile_path、old_string、new_string、replace_all
list_dirСписок содержимого каталогаpath (обязательно), recursive (следует ли выполнять рекурсию)
search_filesПоиск по шаблону имени файлаpattern (обязательно, поддерживает glob), path (корневой каталог поиска)
search_contentПоиск текста в содержимом файлаpattern (обязательный, поддерживает регулярные выражения), path, file_types

Как работает edit_file: Он использует точное сопоставление подстроки для определения точки изменения. Агент предоставляет old_string (текст, который действительно существует в файле), инструмент находит его и заменяет на new_string. Если old_string совпадает с несколькими местами, установите replace_all: true, чтобы заменить все вхождения.

edit_file — наиболее часто используемый Агентом способ изменения файлов; он безопаснее, чем write_file, потому что если old_string не найден, операция завершается ошибкой вместо случайной перезаписи файла.

terminal — выполнение команд Shell

Позволяет Агенту выполнять команды Shell в указанной бэкенд-среде.

ИнструментыОсобенностиКлючевые параметры
run_commandВыполнить одну команду Shellcommand (обязательный), workdir (рабочий каталог), timeout (таймаут в миллисекундах)
run_scriptВыполнить многострочные Shell-скриптыscript (обязательный, содержимое многострочного скрипта), workdir, timeout

Команды выполняются в настроенном бэкенде терминала — локальном, docker (контейнер), ssh (удалённый) и т. д.

Результаты выполнения включают stdout, stderr и код выхода. Агент может использовать эту информацию, чтобы определить, успешно ли выполнена команда.

code — выполнение кода в песочнице

Выполняет фрагменты кода в изолированной песочнице с поддержкой Python, JavaScript и Bash.

ИнструментыОсобенностиКлючевые параметры
execute_codeЗапустить код в песочницеlanguage (python/js/bash), code (обязательно), timeout

Отличие от терминала: инструмент code работает в независимой песочнице и не имеет доступа к файловой системе (если только она не смонтирована явно). Он подходит для запуска кода, не требующего взаимодействия с файлами, например для проверки алгоритмов и обработки данных.

computer — автоматизация графического интерфейса рабочего стола

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

ИнструментыОсобенности
screenshotСделать снимок экрана или указанной области
clickЩёлкнуть мышью в указанных координатах
typeИмитировать ввод текста с клавиатуры
scrollПрокрутить колесо мыши
moveПереместить мышь в указанные координаты

Набор инструментов для работы с компьютером в основном используется для тестирования GUI-приложений и автоматизированных операций. Если ваш сценарий не связан с настольными приложениями, его можно отключить для экономии токенов.


Наборы инструментов для сети и контента

Эти наборы инструментов позволяют Агенту искать в интернете, извлекать содержимое веб-страниц и автоматизировать операции браузера.

web — Веб-поиск и извлечение контента

Основной канал, через который Агент получает внешнюю информацию.

ИнструментыОсобенностиКлючевые параметры
web_searchПоиск контента в интернетеquery (обязательно), num_results (количество результатов)
web_extractИзвлечь основное содержимое указанного URLurl (обязательно), extract_mode (auto/text/markdown)

web_search возвращает список результатов поиска (заголовок + URL + краткое описание). Агент обычно сначала выполняет поиск, затем вызывает web_extract для интересующих страниц, чтобы получить подробное содержимое.

Для его использования необходимо настроить API поиска. Поддерживается несколько провайдеров:

Пример

# Путь к файлу: ~/.hermes/config.yaml
# Настроить бэкенд веб-поиска
web
:
  search_provider
: firecrawl    # или brave, serpapi, tavily
  # Укажите соответствующий API-ключ в .env
  # FIRECRAWL_API_KEY=fc-...
  # Или BRAVE_API_KEY=BS...

browser — Автоматизация браузера

Полные возможности управления браузером — навигация, клики, заполнение форм, скриншоты — работа с веб-страницами как человек.

ИнструментыОсобенностиКлючевые параметры
navigateПерейти по указанному URLurl (обязательно)
clickНажать на элемент страницыselector (CSS-селектор или текстовое описание)
fill_formЗаполнить поля формыfields (сопоставление имён полей со значениями)
screenshotСделать снимок текущей страницыfull_page (делать ли снимок всей страницы)
extractИзвлечь структурированные данные со страницыselector、format(json/text)
execute_jsВыполняет JavaScript на страницеcode (обязательно)

Набор инструментов браузера требует Playwright или облачный бэкенд браузера.

Набор инструментов браузера потребляет дополнительные ресурсы при запуске экземпляров браузера. Если вам нужно только извлечь текстовое содержимое веб-страницы, предпочитайте web_extract вместо извлечения через браузер — первый представляет собой облегчённый HTTP-запрос, а второй требует запуска полноценного браузера.

vision — анализ изображений

Позволяет Агенту «понимать» содержимое изображения.

ИнструментыОсобенностиКлючевые параметры
analyze_imageАнализирует содержимое изображения и создаёт описаниеimage_path или image_url (обязательно), question (необязательно, конкретный вопрос об изображении)
describe_imageСоздаёт подробное текстовое описание изображенияimage_path или image_url (обязательно)

Инструмент vision отправляет изображения в LLM, способную обрабатывать изображения (например, claude-sonnet-4-6, gpt-4o), а модель распознаёт и описывает содержимое изображения.

audio — обработка аудио

Преобразование речи в текст и текста в речь.

ИнструментыОсобенностиКлючевые параметры
transcribeПреобразование аудиофайлов в текстaudio_path (обязательно), language (необязательно)
ttsПреобразование текста в речевые файлыtext (обязательно), voice (выбор голоса), provider

Наборы инструментов для возможностей агента

Этот тип набора инструментов управляет собственным состоянием агента — памятью, навыками и взаимодействием с субагентами.

memory — управление памятью

Чтение и запись постоянной памяти, а также поиск по истории между сессиями.

ИнструментыОсобенностиКлючевые параметры
memoryУправление постоянной памятью (добавление, удаление, изменение)action(add/replace/remove)、target(memory/user)、content
session_searchПолнотекстовый поиск по историческим сессиямquery (обязателен, поддерживает синтаксис FTS5)

Инструмент memory не имеет операции чтения — постоянная память уже внедрена в системный промпт при запуске сессии, поэтому Агенту не нужно читать её отдельно.

skills — управление навыками

Загружает и управляет переиспользуемыми навыками рабочих процессов.

ИнструментыОсобенностиКлючевые параметры
skills_listПеречислить все установленные навыки и их описанияНет (автоматически вызывается при запуске сессии)
skill_viewЗагрузить полное содержимое навыкаname (обязательно), path (необязательно, загружать ссылки на подфайлы)
skill_manageСоздавать, изменять или удалять файлы навыковaction、name、content

delegation — делегирование субагентам

Запускает субагентов для параллельного выполнения задач.

ИнструментыОсобенностиКлючевые параметры
spawn_agentСоздаёт одного субагента для выполнения задачиprompt (обязательно), model (необязательно)
spawn_parallelСоздать несколько субагентов параллельноtasks (обязательно, список задач)

Субагенты имеют независимые окна контекста и не загрязняют историю диалога главного Агента. После выполнения они возвращают сводку результатов.

kanban — мультиагентная канбан-доска

Структурированная система совместной работы нескольких Агентов, требующая явного включения (all/* не включает её автоматически).

ИнструментыОсобенности
task_createСоздать новую задачу на канбан-доске
task_updateОбновить статус задачи (todo/in_progress/done)
task_listВывести список всех задач тенанта
task_assignНазначает задачи указанным рабочим Агентам

Kanban — основной механизм совместной работы нескольких Профилей: один Профиль-оркестратор создаёт задачи, а несколько рабочих Профилей забирают их и выполняют. Для этого требуется одновременная работа шлюзов нескольких Профилей.


Набор инструментов для создания медиа

Этот тип набора инструментов обычно требует подписку на Nous Portal или соответствующий API-ключ стороннего сервиса.

image_gen — генерация изображений с помощью ИИ

Генерирует изображения из текстовых описаний, поддерживает 9 моделей.

ИнструментыОсобенностиКлючевые параметры
generate_imageСгенерировать изображение на основе промптаprompt(обязательный)、model(flux/gpt-image/ideogram и т.д.)、size、style

tts — синтез речи

Функциональность TTS, независимая от набора аудиоинструментов, предлагает более широкий выбор провайдеров.

ИнструментыОсобенности
text_to_speechПреобразование текста в речевые файлы
list_voicesСписок доступных тембров голоса

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

Существующие коллекции инструментов можно объединять в пользовательские наборы инструментов для конкретного проекта:

Пример

# Путь к файлу: ~/.hermes/config.yaml
# Определить набор инструментов для конкретного проекта
custom_toolsets
:
 # Инструменты, необходимые для проектов в области data science
  data-science
:
   - file
    - terminal
    - code
    - web

  # Проектам, связанным только с написанием текстов, нужны только файловые операции
  writing
:
   - file
    - web
    - memory

  # Ops-проектам нужны терминал и файлы
  devops
:
   - file
    - terminal
    - memory

При использовании, через--toolsetsУказание параметров:

Пример

# Использовать пользовательский набор инструментов при запуске
hermes --tools data-science chat

# Или сделайте значением по умолчанию в конфигурации профиля
coder config set toolsets data-science

Поток вызова инструмента

Понимание полного потока вызова инструмента помогает понять поведение Агента и устранять проблемы.

Полный вызов инструмента проходит следующие шаги:

  1. LLM решает вызвать инструмент во время генерации своего ответа, выводя имя инструмента и параметры
  2. Выполнение Middleware tool_request (может изменять параметры)
  3. Проверка одобрения — если инструмент является опасной операцией, решает, показывать ли запрос на подтверждение на основе approvals.mode
  4. Фактическое выполнение инструмента
  5. Выполняется Middleware tool_execution (может изменять результаты)
  6. Хук post_tool_call записывает телеметрические данные
  7. Результат выполнения возвращается в LLM, и LLM продолжает генерировать ответ

Если ваш Middleware изменяет параметры инструмента, изменённые параметры становятся входными данными для утверждения и фактического выполнения. Если вы досрочно завершите выполнение в Middleware (вернёте собственный результат), фактический инструмент не запустится.


Статистика использования инструментов

Знание того, какие инструменты часто используются, помогает оптимизировать конфигурацию набора инструментов и потребление токенов.

В рамках сессии просмотрите статистику вызовов инструментов для текущей сессии:

Пример

# Просмотр статистики использования инструментов для этой сессии
/usage

# Пример вывода:
# Использование токенов: Ввод 12,340 | Вывод 5,678 | Всего 18,018
# Вызовы инструментов: read_file (15 раз) | edit_file (8 раз)
# terminal (3 раза) | web_search (2 раза)

В сценариях пакетной обработки файл statistics.json содержит более подробную статистику:

Пример

// Путь к файлу: data/my_first_run/statistics.json
{
  "total_tool_calls": 1523,
  "tools": {
    "read_file": {"count": 520, "success": 510, "failure": 10},
    "edit_file": {"count": 380, "success": 375, "failure": 5},
    "terminal": {"count": 290, "success": 270, "failure": 20},
    "web_search": {"count": 180, "success": 178, "failure": 2}
  },
  "avg_tool_calls_per_turn": 2.4,
  "most_common_tool_sequence": [
    "read_file", "edit_file", "terminal"
  ]
}
Другие расширения