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

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

Все три используют одно и то же ядро ​​AIAgent. Они отличаются только форматом провода и набором функций, которые они предоставляют.

ACP (протокол агента-клиента)

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

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

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

hermes acp                  # serve ACP on stdio
hermes acp --check          # verify ACP dependencies and adapter imports
hermes acp --setup          # interactive provider/model setup for ACP terminal auth

TUI-шлюз 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      subagent.steer
spawn_tree.save / list / load
terminal.resize         clipboard.paste         image.attach

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

Перемотка истории на prompt.submit

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

Порядковый номер без confirm_truncate отклоняется с кодом 4029 и ничего не записывается. Хосты, реализующие перемотку, должны устанавливать флаг в тот момент, когда пользователь запрашивает его, и никогда не должны сохранять порядковый номер в состоянии при обычных отправках.

События передаются обратно

message.delta, message.complete, tool.start, tool.progress, tool.complete, approval.request, clarify.request, sudo.request, sudo.expire, secret.request, secret.expire, gateway.ready, а также жизненный цикл сеанса и события ошибок. События истечения срока действия содержат исходный { request_id }; внешние хосты должны очищать только соответствующее ожидающее приглашение.

Сопоставление RPC в стиле Pi

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

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

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

Конечные точки:

POST /v1/chat/completions        OpenAI Chat Completions (streaming via SSE)
POST /v1/responses               OpenAI Responses API (stateful)
POST /v1/runs                    Start a run, returns run_id (202)
GET  /v1/runs/{id}               Run status
GET  /v1/runs/{id}/events        SSE stream of lifecycle events
POST /v1/runs/{id}/approval      Resolve a pending approval
POST /v1/runs/{id}/stop          Interrupt the run
GET  /v1/capabilities            Machine-readable feature flags
GET  /v1/models                  Lists hermes-agent
GET  /api/model/options          Provider-aware picker inventory
GET  /health, /health/detailed

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

Поверхности каталога моделей

API-интерфейс, совместимый с OpenAI, намеренно сводит GET /v1/models к минимуму: это ожидаемые интерфейсы конечной точки совместимости, а не полный поставщик/модель Hermes каталог подборщика.

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

• API-сервер REST: GET /api/model/options с ключом носителя API-сервера.
• REST серверной части информационной панели: GET /api/model/options с помощью X-Hermes-Session-Token.
• RPC шлюза TUI: model.options

Эти поверхности используют один и тот же конструктор полезных данных и одного и того же специального поставщика. политика зондирования:

• Нормальное открытие: проверяйте только текущего пользовательского поставщика, поэтому сохраняется в автономном режиме. конечные точки не останавливают сборщик.
• Явное обновление (refresh=1 или refresh: true): разрушает модель поставщика. кэшируйте и проверяйте все сохраненные пользовательские поставщики, чтобы живые каталоги заполнялись полностью.

Используйте /v1/models для совместимости с OpenAI-клиентом. Используйте /api/model/options или model.options, когда вы создаете средство выбора моделей с поддержкой Hermes.

Какой из них мне следует использовать?

• Вы пишете плагин IDE, а IDE уже поддерживает ACP → ACP. Нулевой протокол работает на стороне IDE.
• Вы пишете собственный хост для рабочего стола, веб-сайта или TUI и хотите использовать все функции Hermes (команды с косой чертой, утверждения, уточнение, мультиагентность, ветвление сеансов) → шлюз TUI JSON-RPC.
• Вам нужен любой OpenAI-совместимый интерфейс, HTTP-клиент, не зависящий от языка, или автоматизация на основе Curl → API-сервер.
• Вы хотите внедрить Python в процесс без подпроцесса → импортируйте run_agent.AIAgent напрямую. См. Агентный цикл.

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

Переключение модели в середине сеанса работает на любой поверхности — это слэш-команда /model под капотом.

• CLI/TUI: /model claude-sonnet-4 или /model openrouter:anthropic/claude-sonnet-4.6
• RPC шлюза TUI: command.dispatch с {"command": "/model claude-sonnet-4"}
• ACP: среда IDE отправляет косую черту в качестве приглашения; агент отправляет его
• API-сервер: включите поле model в тело запроса.

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

Примечание по --mode rpc

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