Программная интеграция

У Hermes есть три протокола, чтобы управлять агентом из внешних программ — плагинов IDE, своих интерфейсов, CI-пайплайнов, встроенных субагентов. Выбирайте тот, что подходит по транспорту и типу потребителя.

Протокол	Транспорт	Лучше всего подходит для	Реализован в
ACP	JSON-RPC поверх stdio	IDE-клиентов (VS Code, Zed, JetBrains), которые уже говорят на Agent Client Protocol	`acp_adapter/`
TUI gateway	JSON-RPC поверх stdio (или WebSocket)	Кастомных хостов с тонким управлением сессиями, слэш-командами, подтверждениями и потоковыми событиями	`tui_gateway/server.py`
API-сервер	HTTP + Server-Sent Events	Фронтендов, совместимых с OpenAI (Open WebUI, LobeChat, LibreChat…), и веб-клиентов на любом языке	`gateway/platforms/api_server.py`

Все три работают поверх одного ядра AIAgent. Разница лишь в формате сообщений и наборе доступных возможностей.

ACP (Agent Client Protocol)

hermes acp запускает stdio JSON-RPC сервер, говорящий на ACP. В продакшне его используют VS Code (расширение ACP от Zed Industries), Zed и любая JetBrains IDE с ACP-плагином.

Доступные возможности: создание сессии, отправка промпта, потоковая передача фрагментов сообщений агента, события вызова инструментов, запросы разрешений, форк сессии, отмена и аутентификация. Вывод инструментов оборачивается в ACP-блоки Diff/ToolCall, понятные IDE.

Полный жизненный цикл, событийный мост и процесс подтверждения: ACP Internals.

hermes acp                  # запустить ACP на stdio
hermes acp --bootstrap      # вывести сниппет установки для ACP-совместимой IDE

TUI Gateway JSON-RPC

tui_gateway/server.py — протокол, которым пользуются Ink TUI (hermes --tui) и встроенный PTY-мост дашборда. Любой внешний хост может говорить на том же протоколе через stdio или WebSocket (tui_gateway/ws.py).

Каталог методов (выборка)

prompt.submit           prompt.background       session.steer
session.create          session.list            session.active_list
session.activate        session.close           session.interrupt
session.history         session.compress        session.branch
session.title           session.usage           session.status
clarify.respond         sudo.respond            secret.respond
approval.respond        config.set / config.get commands.catalog
command.resolve         command.dispatch        cli.exec
reload.mcp              reload.env              process.stop
delegation.status       subagent.interrupt      spawn_tree.save / list / load
terminal.resize         clipboard.paste         image.attach

session.active_list, session.activate и session.close управляют живыми сессиями локально внутри процесса — их использует переключатель сессий TUI. Для работы с сохранёнными транскриптами берите session.list / /resume; методы для активных сессий применяйте только к тем, что открыты в процессе TUI gateway.

Потоковые события

message.delta, message.complete, tool.start, tool.progress, tool.complete, approval.request, clarify.request, sudo.request, secret.request, gateway.ready, а также события жизненного цикла сессий и ошибки.

Маппинг RPC-команд в стиле Pi

Каждой команде из RPC-спецификации Pi-mono (issue #360) соответствует эквивалент в TUI gateway:

Команда Pi	Эквивалент в Hermes
`prompt`	`prompt.submit` (или ACP `session/prompt`)
`steer`	`session.steer`
`follow_up`	`prompt.submit` в очереди после текущего хода
`abort`	`session.interrupt`
`set_model`	`command.dispatch` для `/model <provider:model>` (в рамках сессии, постоянно)
`compact`	`session.compress`
`get_state`	`session.status`
`get_messages`	`session.history`
`switch_session`	`session.resume`
`fork`	`session.branch`
`ui_request` / `ui_response`	`clarify.respond` / `sudo.respond` / `secret.respond` / `approval.respond`

API-сервер, совместимый с OpenAI

gateway/platforms/api_server.py открывает доступ к Hermes по HTTP для любого клиента, говорящего на формате OpenAI. Удобно, когда нужен веб-фронтенд, CI-раннер на curl или потребитель не на Python.

Эндпоинты:

POST /v1/chat/completions        OpenAI Chat Completions (стриминг через SSE)
POST /v1/responses               OpenAI Responses API (с сохранением состояния)
POST /v1/runs                    Запустить задачу, возвращает run_id (202)
GET  /v1/runs/{id}               Статус задачи
GET  /v1/runs/{id}/events        SSE-поток событий жизненного цикла
POST /v1/runs/{id}/approval      Разрешить ожидающее подтверждение
POST /v1/runs/{id}/stop          Прервать выполнение
GET  /v1/capabilities            Флаги возможностей в машиночитаемом формате
GET  /v1/models                  Список — hermes-agent
GET  /health, /health/detailed

Настройка, заголовки (X-Hermes-Session-Id, X-Hermes-Session-Key) и подключение фронтенда: API Server.

Какой протокол выбрать?

Пишете плагин для IDE, которая уже поддерживает ACP → ACP. Никакой дополнительной работы с протоколом на стороне IDE.
Строите кастомный десктоп / веб / TUI-хост и хотите весь набор возможностей Hermes (слэш-команды, подтверждения, уточняющие запросы, мультиагентность, ветвление сессий) → TUI gateway JSON-RPC.
Нужен любой фронтенд с поддержкой OpenAI, HTTP-клиент на произвольном языке или curl-автоматизация → API-сервер.
Хотите встроить агента прямо в Python-процесс без сабпроцессов → импортируйте run_agent.AIAgent напрямую. Подробнее: Agent Loop.

Горячая замена модели

Сменить модель прямо во время сессии можно на любом из протоколов — под капотом везде работает слэш-команда /model.

CLI / TUI: /model claude-sonnet-4 или /model openrouter:anthropic/claude-sonnet-4.6
TUI gateway RPC: command.dispatch с {"command": "/model claude-sonnet-4"}
ACP: IDE передаёт слэш-команду как промпт, а агент её обрабатывает
API-сервер: передайте поле model в теле запроса или установите заголовок X-Hermes-Model

Разрешение имени с учётом провайдера встроено изначально: одно и то же имя модели подбирает нужный формат под любого подключённого провайдера. См. hermes_cli/model_switch.py.

О флаге `--mode rpc`

В Hermes нет флага --mode rpc. Три описанных протокола уже закрывают все сценарии: ACP — для IDE-клиентов, TUI gateway — для stdio JSON-RPC хостов, API-сервер — для HTTP. Нашли реальный случай, который ни один из них не покрывает, — откройте issue с конкретным описанием того, что строите.