ACP и API Server

· 4 мин чтения · admin

ACP: интеграция Hermes в редакторы кода

ACP (Agent Client Protocol) — протокол, позволяющий запускать Hermes Agent как ACP-сервер и подключать его к совместимым редакторам через stdio. В ACP-режиме Hermes работает как нативный агент: отображает сообщения чата, активность инструментов, диффы файлов, команды терминала и потоковые фрагменты ответов.

Поддерживаемые редакторы

  • VS Code — установите расширение ACP Client, откройте панель, выберите Hermes Agent и подключитесь.
  • Zed — добавьте Hermes в settings.json в секции agent_servers с типом custom и командой hermes acp.
  • JetBrains — используйте совместимый ACP-плагин, указав путь к acp_registry.

Установка и запуск

Установите дополнение [acp] и запустите одной из команд: hermes acp, hermes-acp или python -m acp_adapter.

В ACP-режиме используется набор инструментов hermes-acp: файловые операции (read_file, write_file, patch, search_files), терминал, веб-поиск, память, навыки. Сессии привязаны к рабочей директории редактора, опасные команды запрашивают подтверждение в редакторе. Конфигурация общая с CLI: ~/.hermes/.env, ~/.hermes/config.yaml.

GitHub Copilot ACP

Hermes может работать как ACP-бэкенд для GitHub Copilot в VS Code. Для подключения установите переменную окружения COPILOT_CLI_PATH, указывающую на исполняемый файл Copilot CLI. Также поддерживается OAuth-аутентификация через hermes login --provider openai-codex.

При использовании Copilot ACP Hermes получает доступ к инструментам Copilot и может использовать их совместно с собственными инструментами. Токен Copilot задаётся через COPILOT_GITHUB_TOKEN в ~/.hermes/.env.

Важно: токены gh auth login не работают для Copilot API — необходим OAuth device code flow через hermes model → GitHub Copilot.

API Server: OpenAI-совместимый HTTP API

API Server превращает Hermes Agent в OpenAI-совместимый HTTP-эндпоинт. Любой фронтенд, работающий с форматом OpenAI — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox и другие — подключается к Hermes как к бэкенду.

Ключевые возможности

  • Полный набор инструментов — терминал, файловые операции, веб-поиск, память и навыки через API.
  • Стриминг — индикаторы прогресса отображаются inline.
  • Эндпоинты — POST /v1/chat/completions, POST /v1/responses, GET /v1/models, GET /health.
  • Runs API — асинхронный режим с SSE-стримингом и возможностью остановки.
  • Jobs API — управление запланированными задачами агента.

Быстрый старт

Добавьте в ~/.hermes/.env переменные API_SERVER_ENABLED=true и API_SERVER_KEY=ваш-ключ, запустите шлюз командой hermes gateway и подключите фронтенд по адресу http://localhost:8642/v1.

Подключение Open WebUI

Open WebUI — один из самых популярных фронтендов для LLM. Для подключения к Hermes API Server:

  1. Запустите Hermes с API Server: API_SERVER_ENABLED=true hermes gateway.
  2. В Open WebUI откройте Settings → Connections.
  3. В поле OpenAI API Base URL укажите http://<ip-сервера>:8642/v1.
  4. В поле API Key введите значение API_SERVER_KEY.
  5. Сохраните — модели Hermes появятся в списке моделей Open WebUI.

Поле model в запросах косметическое — реальная модель выбирается на стороне Hermes. Open WebUI может отображать её как hermes-agent.

Безопасность

Авторизация через Bearer-токен. По умолчанию сервер слушает только 127.0.0.1. Для удалённого доступа настройте ключ и API_SERVER_CORS_ORIGINS. С помощью профилей можно запустить изолированные экземпляры для разных пользователей.

Ограничения

  • Загрузка файлов не поддерживается (только inline-изображения).
  • Поле model косметическое — реальная модель настраивается на сервере.

Webhooks: событийные триггеры

Webhooks позволяют внешним системам отправлять HTTP POST запросы в Hermes, запуская обработку агентом. Это полезно для интеграции с CI/CD, мониторингом, уведомлениями и автоматизацией.

Управление подписками

Команда Описание
hermes webhook subscribe NAME Создать маршрут /webhooks/NAME
hermes webhook list Показать все активные подписки
hermes webhook remove NAME Удалить подписку
hermes webhook test NAME Отправить тестовый POST на маршрут

Как работают webhooks

При создании подписки Hermes регистрирует HTTP-эндпоинт /webhooks/<name> на API Server. Входящий POST обрабатывается агентом — тело запроса передаётся как контекст для генерации ответа. Webhook может использоваться для:

  • CI/CD уведомлений — GitHub Actions, GitLab CI отправляют результаты сборки.
  • Мониторинга — системы алертов (Grafana, PagerDuty) передают инциденты.
  • Автоматизации — внешние скрипты запускают задачи агента по событиям.

Требования

Webhooks работают через API Server — необходимо включить API_SERVER_ENABLED=true. Подписки сохраняются в конфигурации профиля и переживают перезапуск шлюза.

Подробнее: документация ACP и документация API Server.