ochenstarik/agent-control-center
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
agent-control-center/docs/adapters/HERMES.md

19 KiB
Raw Blame History

Hermes Agent Adapter Specification

Версия: 0.1.0-draft Дата: 2026-07-20 Статус: Draft — implementation blocked Зависит от: SPECIFICATION.md (§6.2 Connectors and agents), ARCHITECTURE.md (§4 Connector), RESEARCH.md

Этот документ детализирует адаптер Hermes Agent в рамках Agent Adapter Protocol (AAP) согласно SPECIFICATION.md. Реализация запрещена до закрытия G0/G1 и явного утверждения оператором. Формулировки MUST/SHALL обязательны; SHOULD требуют обоснования отклонения.

1. Обзор

Hermes Agent — open-source фреймворк ИИ-агентов от Nous Research, работающий в терминале, desktop-приложении, мессенджерах и IDE. Адаптер ACC подключается через HTTP API Hermes (/v1/chat/completions, /v1/responses, /v1/runs) и использует систему профилей для изоляции рабочих нагрузок.

Hermes обеспечивает: provider-agnostic model routing, credential pools, профили, навыки (skills), память, cron, gateway (Telegram/20+ платформ), делегирование, сессионный поиск, tools (terminal, browser, file, code execution), плагины, MCP-серверы и webhook'и.

2. Профили

Hermes использует профили для изоляции независимых экземпляров агента. Каждый профиль имеет собственный config.yaml, .env, skills/, plugins/, cron/ и memories/.

2.1 Базовый профиль

Профиль Назначение Модель по умолчанию Провайдер
default Управляющий оркестратор deepseek-v4-pro nvidia

Профиль default является точкой входа: принимает пользовательские запросы, маршрутизирует подзадачи worker-профилям через delegate_task, агрегирует результаты.

2.2 Worker-профили

Профиль Назначение Модель Провайдер Типовые задачи
worker-code Разработка и генерация кода kimi-k2.7-code opencode-go Написание, рефакторинг, отладка кода; PR; code review
worker-fast Быстрые задачи, не требующие глубокого анализа grok-4.5 fireworks Простые скрипты, форматирование, быстрый поиск
worker-research Исследования и анализ gemini-3-flash-preview gemini Анализ документации, исследование API, literature review
worker-review Рецензирование и проверка качества deepseek-v4-pro nvidia Code review, security audit, проверка спецификаций

Каждый worker-профиль SHOULD иметь ограниченный набор инструментов, соответствующий его роли.

3. Модели и провайдеры

3.1 Модели

Модель Провайдер Контекст (прибл.) Назначение Статус
kimi-k2.7-code opencode-go 128K Генерация кода, сложный рефакторинг Активен
grok-4.5 fireworks 128K Быстрые ответы, простые задачи Активен
gemini-3-flash-preview gemini 1M Исследования, анализ больших документов Активен
deepseek-v4-pro nvidia 128K Оркестрация, review, сложное рассуждение Активен

Модели резервируются: при недоступности одной моделью SHOULD срабатывать fallback-цепочка (см. WORKER_ORCHESTRATION.md).

3.2 Провайдеры

Провайдер Тип Аутентификация Env-переменная
opencode-go OpenCode Go API API key OPENCODE_GO_API_KEY
fireworks OpenAI-совместимый кастомный API key FIREWORKS_API_KEY
gemini Google Gemini API API key GOOGLE_API_KEY или GEMINI_API_KEY
nvidia NVIDIA AI API API key NVIDIA_API_KEY
ollama Локальный Без аутентификации —

Custom OpenAI-совместимый провайдер (fireworks): настраивается через model.base_url и model.api_key в config.yaml. Должен реализовывать /v1/chat/completions с поддержкой tool calling. Конфигурация:

model:
  provider: fireworks
  base_url: "https://api.fireworks.ai/inference/v1"
  api_key: "${FIREWORKS_API_KEY}"
  model: grok-4.5

4. Инструменты

Hermes предоставляет следующие инструментальные наборы (toolsets), релевантные для адаптера:

Инструмент Назначение Доступность в профилях
terminal Выполнение shell-команд и управление процессами Все профили
browser Браузерная автоматизация (Chromium) default, worker-research
file Чтение/запись/поиск/редактирование файлов Все профили
delegation Делегирование подзадач sub-agent'ам default (оркестратор)
cronjob Управление запланированными задачами default
memory Персистентная память между сессиями default
session_search Поиск по истории сессий default
skills Просмотр и установка навыков default
gateway Управление gateway-сообщениями default
web Веб-поиск и извлечение контента default, worker-research
code_execution Песочница для выполнения Python worker-code

Worker-профили SHOULD иметь минимально необходимый набор инструментов для выполнения своей роли.

4.1 Делегирование (delegate_task)

delegate_task порождает sub-agent с изолированным контекстом и терминальной сессией.

Параметры:

  • goal (обязательный) — цель подзадачи
  • context — контекстная информация
  • role — leaf (по умолчанию; не может ре-делегировать) или orchestrator (может порождать своих worker'ов)
  • background — если true, возвращает handle немедленно
  • tasks — массив задач для параллельного выполнения (fan-out)

Ограничения:

  • max_spawn_depth (в delegation секции config.yaml) ограничивает глубину вложенности оркестраторов
  • max_concurrent_children (по умолчанию 3) — максимум параллельных детей
  • Максимальное количество итераций: delegation.max_iterations (по умолчанию 50)

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

5. Gateway

Hermes Gateway обеспечивает подключение к 20+ мессенджинг-платформам.

5.1 Telegram

Параметр Значение
Режим Polling (long polling)
Fallback IPs Поддерживаются альтернативные IP-адреса для обхода блокировок
Формат сообщений MarkdownV2 / HTML
Доставка уведомлений Через gateway adapter
Команды /approve, /deny, /restart, /sethome, /status, /agents

Настройка Telegram polling:

gateway:
  platforms:
    telegram:
      token: "${TELEGRAM_BOT_TOKEN}"
      polling: true
      fallback_ips:
        - "149.154.167.220"
        - "149.154.167.50"

5.2 Поддерживаемые платформы

Discord, Slack, WhatsApp (Baileys + Business Cloud API), iMessage (Photon), Signal, Email, SMS, Matrix, Mattermost, Microsoft Teams, LINE, SimpleX, ntfy, Google Chat, Home Assistant, DingTalk, Feishu, WeCom, Weixin (WeChat), Raft, API Server, Webhooks.

Каждая платформа конфигурируется в секции gateway.platforms.<name>.

6. Cron

Планировщик Hermes поддерживает durable scheduled jobs.

6.1 Синтаксис расписаний

Формат Пример Описание
Длительность "30m", "2h", "90s" Интервал между запусками
"Every"-фраза "every monday 9am", "every 6 hours" Человеко-читаемое расписание
5-полевой cron "0 9 * * *" Стандартный cron-синтаксис
ISO timestamp "2026-07-20T15:00:00Z" Однократный запуск

6.2 Параметры задания

Параметр Описание
skills Список навыков для загрузки
model/provider Переопределение модели/провайдера
script Pre-run скрипт сбора данных; no_agent=True делает скрипт единственным действием
context_from Цепочка: вывод задания A → контекст задания B
workdir Рабочая директория (загружает AGENTS.md/CLAUDE.md из неё при наличии)
Доставка Multi-platform: Telegram, Email, Webhooks

6.3 Инварианты

  • 3-минутный hard interrupt на каждый run
  • .tick.lock предотвращает дублирование тиков между процессами
  • Cron-сессии передают skip_memory=True по умолчанию
  • Доставка обрамляется header/footer, не зеркалируется в gateway-сессию

6.4 Watch patterns

При запуске через terminal(background=True, watch_patterns=[...]) Hermes отслеживает вывод фонового процесса на совпадение с шаблонами. Rate limit: не более 1 уведомления в 15 секунд; после 3 последовательных окон с dropped matches отключается.

7. Skills (навыки)

Skills — переиспользуемые процедуры, сохраняемые агентом.

7.1 Жизненный цикл

create → use → idle → stale → archive
           ↑                  ↓
           └── restore ←──────┘
  • Только навыки с created_by: "agent" подлежат автоматическому curator'у
  • Bundled + hub-установленные навыки неприкосновенны
  • Максимальное деструктивное действие — archive (никогда не delete)
  • Pinned навыки исключены из всех авто-переходов

7.2 Curator

Фоновый процесс обслуживания навыков:

hermes curator status    # статус
hermes curator run       # ручной запуск
hermes curator pin NAME  # защита от авто-архивации
hermes curator archive NAME  # ручная архивация
hermes curator restore NAME  # восстановление
hermes curator backup    # создание снапшота

Consolidation (объединение пересекающихся навыков) выключен по умолчанию (curator.consolidate: false), требует aux-модель и явного включения.

7.3 Категории навыков

  • Встроенные — поставляются с Hermes (code review, planning, TDD, debugging, и др.)
  • Пользовательские — создаются агентом в процессе работы
  • Hub — устанавливаются из реестра hermes skills install

8. Память

Hermes ведёт два файла памяти:

Файл Назначение
MEMORY.md Факты, решения, уроки, выученные в процессе работы
USER.md Предпочтения пользователя, окружение, постоянные параметры

Память опционально может использовать внешние провайдеры (Honcho, Mem0) через hermes memory setup.

9. Конфигурация

9.1 config.yaml

Основной конфигурационный файл (~/.hermes/config.yaml или $HERMES_HOME/config.yaml). Ключевые секции для адаптера:

model:
  default: deepseek-v4-pro
  provider: nvidia
  base_url: "https://integrate.api.nvidia.com/v1"

agent:
  max_turns: 90
  tool_use_enforcement: true

terminal:
  backend: local
  timeout: 180

delegation:
  model: kimi-k2.7-code
  provider: opencode-go
  max_iterations: 50
  max_spawn_depth: 2
  max_concurrent_children: 3

gateway:
  platforms:
    telegram:
      token: "${TELEGRAM_BOT_TOKEN}"
      polling: true

curator:
  enabled: true
  consolidate: false
  interval_hours: 24
  stale_after_days: 30

9.2 .env

Секреты и API-ключи:

OPENCODE_GO_API_KEY=sk-...
FIREWORKS_API_KEY=fw-...
GOOGLE_API_KEY=AIza...
NVIDIA_API_KEY=nvapi-...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

9.3 Профили

Каждый профиль — изолированная директория ~/.hermes/profiles/<name>/ с собственными config.yaml, .env, skills/, plugins/, cron/, memories/.

Создание профиля:

hermes profile create worker-code
hermes profile create worker-fast
hermes profile create worker-research
hermes profile create worker-review

10. Возможности адаптера (capabilities)

При handshake с ACC адаптер Hermes публикует следующий набор capabilities:

Capability Значение Примечание
stream true HTTP SSE / JSON Lines
cancel true Через cancel в run API
checkpoint true Observable checkpoint schema
approvals true Built-in approval flow
tools ["terminal", "browser", "file", "web", "code_execution", ...] Зависит от профиля
mcp true MCP client support
artifacts true Файловая система + object refs
usage_exact false Hermes не предоставляет authoritative usage API
usage_estimated true Token usage из LLM-ответов
filesystem_scope ["cwd", "home"] Ограничивается рабочей директорией
structured_output true JSON mode в моделях
profiles ["default", "worker-code", "worker-fast", "worker-research", "worker-review"] Доступные профили
resume true Session resume через session ID

11. Соответствие AAP

Адаптер Hermes реализует Agent Adapter Protocol (ARCHITECTURE.md §4.2):

AAP-метод Реализация в Hermes
handshake() GET /v1/status → identity, version, capabilities
health() GET /v1/health → status, latency, active_runs
start(run_spec, context) POST /v1/runs → native_run_ref
stream(run_ref, cursor) GET /v1/runs/{id}/events?cursor= → SSE
checkpoint(run_ref, reason) POST /v1/runs/{id}/checkpoint → checkpoint bundle
cancel(run_ref, mode) POST /v1/runs/{id}/cancel → outcome
resume(run_ref) POST /v1/runs/{id}/resume → outcome
usage(scope) GET /v1/usage → measured/estimated/unknown signal
artifacts(run_ref) GET /v1/runs/{id}/artifacts → metadata + refs

12. Ограничения и риски

Ограничение Влияние Мера
Hermes не предоставляет authoritative usage API Бюджетирование только estimated Явная маркировка confidence; ручной budget policy
Делегирование не durable Потеря задачи при падении родителя Критичные задачи → cronjob
Worker-профили требуют отдельных процессов Накладные расходы на запуск Keep-warm пул worker'ов в production
Adapter версионирование отстаёт от Hermes Incompatible handshake Pinned version + contract tests + N-1 policy
Gateway polling подвержен сетевым сбоям Задержка доставки Fallback IPs, метрики polling latency

13. Ссылки