Интеграция с редакторами через ACP

Hermes Agent умеет работать как ACP-сервер. ACP-совместимый редактор общается с ним по stdio и сам рисует:

• сообщения чата
• активность инструментов
• диффы файлов
• команды терминала
• запросы на подтверждение
• потоковые фрагменты размышлений и ответа

ACP подходит, когда хочется, чтобы Hermes вёл себя как встроенный в редактор кодинг-агент, а не как отдельный CLI или чат-бот в мессенджере.

Что Hermes даёт в режиме ACP

В этом режиме запускается отобранный набор инструментов hermes-acp, заточенный под работу в редакторе. В него входят:

• файловые инструменты: read_file, write_file, patch, search_files
• терминальные инструменты: terminal, process
• веб- и браузерные инструменты
• память, todo, поиск по сессиям
• навыки
• execute_code и delegate_task
• зрение (vision)

Намеренно за бортом остаётся то, что плохо ложится на типичный редакторский UX, — например, доставка сообщений и управление cron-задачами.

Установка

Поставьте Hermes как обычно, а затем добавьте ACP-экстру:

pip install -e '.[acp]'

Так подтянется зависимость agent-client-protocol и включатся команды:

• hermes acp
• hermes-acp
• python -m acp_adapter

При установке через реестр Zed редактор запускает Hermes по официальной записи в ACP Registry. Эта запись использует дистрибуцию через uvx, которая выполняет:

uvx --from 'hermes-agent[acp]==<version>' hermes-acp

Перед тем как идти этим путём, убедитесь, что uv доступен в PATH.

Запуск ACP-сервера

Hermes стартует в режиме ACP любой из команд:

hermes acp

hermes-acp

python -m acp_adapter

Логи Hermes пишет в stderr, чтобы stdout оставался свободным под трафик ACP JSON-RPC.

Для неинтерактивных проверок:

hermes acp --version
hermes acp --check

Браузерные инструменты (опционально)

Браузерные инструменты (browser_navigate, browser_click и прочие) зависят от npm-пакета agent-browser и Chromium, а они не входят в Python-wheel. Поставьте их так:

hermes acp --setup-browser           # интерактивно (спросит перед загрузкой ~400 МБ)
hermes acp --setup-browser --yes     # принять загрузку без вопросов

Это отдельная команда. Поток терминальной авторизации из реестра Zed (hermes acp --setup) тоже предлагает развернуть браузер — отдельным вопросом уже после выбора модели, так что напрямую --setup-browser большинству вообще не понадобится.

Что под капотом:

• ставит Node.js 22 LTS в ~/.hermes/node/, если его там нет
• выполняет npm install -g agent-browser @askjo/camofox-browser в этот префикс (sudo не нужен — --prefix у npm указывает на доступный пользователю Node под управлением Hermes)
• ставит Playwright Chromium или подхватывает найденный системный Chrome/Chromium, если он есть

Запуск идемпотентный: повторный прогон проходит быстро и пропускает уже сделанную работу.

Настройка редактора

VS Code

Поставьте расширение ACP Client.

Чтобы подключиться:

1. Откройте панель ACP Client с боковой панели активности.
2. Выберите Hermes Agent из встроенного списка агентов.
3. Подключитесь и начинайте переписку.

Если хочется задать Hermes вручную, добавьте его через настройки VS Code в раздел acp.agents:

{
  "acp.agents": {
    "Hermes Agent": {
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

Zed

Zed версии 0.221.x и выше ставит внешних агентов через официальный ACP Registry.

1. Откройте панель агента (Agent Panel).
2. Нажмите Add Agent или выполните команду zed: acp registry.
3. Найдите Hermes Agent.
4. Установите его и откройте новый тред внешнего агента Hermes.

Что нужно заранее:

• Сначала задайте учётные данные провайдера Hermes командой hermes model либо пропишите их в ~/.hermes/.env / ~/.hermes/config.yaml.
• Поставьте uv, чтобы лаунчер из реестра смог выполнить uvx --from 'hermes-agent[acp]==<version>' hermes-acp.

Для локальной разработки, пока записи в реестре ещё нет, пропишите кастомный сервер агента в настройках Zed:

{
  "agent_servers": {
    "hermes-agent": {
      "type": "custom",
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

JetBrains

Возьмите ACP-совместимый плагин и направьте его на:

/path/to/hermes-agent/acp_registry

Манифест реестра

Исходная копия официальных метаданных Hermes для ACP Registry лежит здесь:

acp_registry/agent.json
acp_registry/icon.svg

PR в апстрим-реестр копирует эти файлы в каталог верхнего уровня hermes-agent/ внутри agentclientprotocol/registry.

Запись в реестре использует дистрибуцию через uvx, которая ссылается прямо на релиз hermes-agent на PyPI:

uvx --from 'hermes-agent[acp]==<version>' hermes-acp

CI реестра проверяет, что зафиксированная версия существует на PyPI, поэтому поле version в манифесте и пин package в uvx обязаны всегда совпадать с pyproject.toml. Скрипт scripts/release.py синхронизирует их автоматически.

Конфигурация и учётные данные

Режим ACP берёт ту же конфигурацию Hermes, что и CLI:

• ~/.hermes/.env
• ~/.hermes/config.yaml
• ~/.hermes/skills/
• ~/.hermes/state.db

Провайдер определяется обычным рантайм-резолвером Hermes, так что ACP наследует текущего настроенного провайдера и его учётные данные. Кроме того, Hermes объявляет метод терминальной авторизации (--setup) для клиентов реестра при первом запуске — он открывает интерактивную настройку модели и провайдера.

Поведение сессий

Пока сервер работает, ACP-сессиями заведует встроенный менеджер сессий ACP-адаптера, хранящий их в памяти.

В каждой сессии лежат:

• идентификатор сессии
• рабочий каталог
• выбранная модель
• текущая история диалога
• событие отмены (cancel event)

Сам AIAgent по-прежнему использует штатные пути персистентности и логирования Hermes, но операции ACP list/load/resume/fork ограничены процессом текущего запущенного ACP-сервера.

Поведение рабочего каталога

ACP-сессия привязывает cwd редактора к идентификатору задачи Hermes, чтобы файловые и терминальные инструменты работали относительно рабочего пространства редактора, а не cwd серверного процесса.

Подтверждения

Опасные команды терминала можно вернуть в редактор как запросы на подтверждение. Набор вариантов в ACP проще, чем в CLI:

• разрешить однократно
• разрешить всегда
• запретить

При тайм-ауте или ошибке мост подтверждений отклоняет запрос.

Автоподтверждение правок в пределах сессии

В ACP есть третий уровень между разрешить однократно и разрешить всегда — Разрешить для сессии. Если выбрать его в запросе разрешения внутри редактора, согласие запоминается только для текущей ACP-сессии: каждая следующая подходящая команда в этой сессии пройдёт без вопроса, но новая ACP-сессия (или перезапуск редактора) обнуляет всё, и в первый раз вопрос появится снова.

Вариант	Подпись в редакторе	Область	Сохраняется между перезапусками
allow_once	Allow once	Только этот вызов инструмента	Нет
allow_session	Allow for session	Все подходящие вызовы в этой ACP-сессии	Нет — стирается с концом сессии
allow_always	Allow always	Все будущие сессии	Да (пишется в постоянный список разрешений Hermes)
deny	Deny	Только этот вызов инструмента	Нет

allow_session — разумный выбор по умолчанию для работы в редакторе, когда вы доверяете агенту на время одной задачи, но не хотите заводить долгоживущую запись в списке разрешений. Компромисс по безопасности прост: чем шире область, тем реже редактор вас дёргает — и тем больше успеет натворить сбойнувший агент (или внедрённый промпт), пока вы не заметите. Незнакомым командам выдавайте allow_once; повышайте до allow_session, когда пару раз увидели, что агент верно прогоняет один и тот же шаблон; а allow_always приберегите для по-настоящему идемпотентных команд, которым доверяете навсегда (скажем, git status).

ACP-мост раскладывает эти варианты на внутреннюю семантику подтверждений Hermes: allow_always пишет постоянную запись в список разрешений ровно так же, как это делает CLI, а allow_session затрагивает только внутрипроцессный кэш согласий текущей ACP-сессии.

Решение проблем

ACP-агент не появляется в редакторе

Проверьте:

• В Zed откройте ACP Registry командой zed: acp registry и поищите Hermes Agent.
• Для ручной / локальной разработки убедитесь, что кастомная команда в agent_servers указывает на hermes acp.
• Hermes установлен и доступен в PATH.
• Установлена ACP-экстра (pip install -e '.[acp]').
• Если запуск идёт из официальной записи реестра Zed, установлен uv.

ACP стартует, но тут же падает с ошибкой

Прогоните эти проверки:

hermes acp --version
hermes acp --check
hermes doctor
hermes status

Нет учётных данных

Режим ACP опирается на уже настроенного провайдера Hermes. Задайте учётные данные командой:

hermes model

или правкой ~/.hermes/.env. Клиенты реестра также могут запустить поток терминальной авторизации Hermes — это та же интерактивная настройка провайдера и модели.

Лаунчер реестра Zed не находит uv

Установите uv по официальной инструкции по установке uv, а затем заново откройте тред Hermes Agent в Zed.

Смотрите также

• Внутреннее устройство ACP
• Определение провайдера в рантайме
• Рантайм инструментов