API Server

API-сервер предоставляет hermes-agent в виде HTTP-эндпоинта, совместимого с OpenAI. Любой интерфейс, поддерживающий формат OpenAI — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox и сотни других — может подключиться к hermes-agent и использовать его в качестве бэкенда.

Ваш агент обрабатывает запросы, используя полный набор инструментов (терминал, файловые операции, веб-поиск, память, навыки) и возвращает итоговый ответ. При стриминге индикаторы выполнения инструментов отображаются в реальном времени, чтобы интерфейсы могли показывать, что делает агент.

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

1. Включение API-сервера

Добавьте в ~/.hermes/.env:

API_SERVER_ENABLED=true
|API_SERVER_KEY=change-me-local-dev
|# Optional: only if a browser must call Hermes directly
|# API_SERVER_CORS_ORIGINS=http://localhost:3000
|

2. Запуск шлюза

hermes gateway
|

Вы увидите:

[API Server] API server listening on http://127.0.0.1:8642
|

3. Подключение интерфейса

Направьте любой OpenAI-совместимый клиент на http://localhost:8642/v1:

# Test with curl
|curl http://localhost:8642/v1/chat/completions \
|  -H "Authorization: Bearer change-me-local-dev" \
|  -H "Content-Type: application/json" \
|  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'
|

Или подключите Open WebUI, LobeChat или любой другой интерфейс — смотрите руководство по интеграции Open WebUI для пошаговых инструкций.

Эндпоинты

POST /v1/chat/completions

Стандартный формат OpenAI Chat Completions. Не хранит состояние — полная история беседы передаётся в каждом запросе через массив messages.

Запрос:

{
|  "model": "hermes-agent",
|  "messages": [
|    {"role": "system", "content": "You are a Python expert."},
|    {"role": "user", "content": "Write a fibonacci function"}
|  ],
|  "stream": false
|}
|

Ответ:

{
|  "id": "chatcmpl-abc123",
|  "object": "chat.completion",
|  "created": 1710000000,
|  "model": "hermes-agent",
|  "choices": [{
|    "index": 0,
|    "message": {"role": "assistant", "content": "Here's a fibonacci function..."},
|    "finish_reason": "stop"
|  }],
|  "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
|}
|

Встроенный ввод изображений: сообщения пользователя могут передавать content в виде массива частей text и image_url. Поддерживаются как удалённые http(s) URL, так и data:image/... URL:

{
|  "model": "hermes-agent",
|  "messages": [
|    {
|      "role": "user",
|      "content": [
|        {"type": "text", "text": "What is in this image?"},
|        {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
|      ]
|    }
|  ]
|}
|

Загруженные файлы (file / input_file / file_id) и URL, не являющиеся изображениями (data:), возвращают ошибку 400 unsupported_content_type.

Стриминг ("stream": true): Возвращает Server-Sent Events (SSE) с частями ответа токен за токеном. Для Chat Completions поток использует стандартные события chat.completion.chunk плюс пользовательское событие Hermes hermes.tool.progress для отображения начала работы инструмента. Для Responses поток использует типы событий OpenAI Responses, такие как response.created, response.output_text.delta, response.output_item.added, response.output_item.done и response.completed.

Прогресс выполнения инструментов в потоках:

• Chat Completions: Hermes отправляет событие event: hermes.tool.progress для отображения начала работы инструмента, не загрязняя сохранённый текст ассистента.

• Responses: Hermes отправляет нативные элементы вывода function_call и function_call_output во время SSE-потока, чтобы клиенты могли отображать структурированный UI инструментов в реальном времени.

POST /v1/responses

Формат OpenAI Responses API. Поддерживает состояние беседы на стороне сервера через previous_response_id — сервер хранит полную историю разговора (включая вызовы инструментов и результаты), так что контекст многошагового диалога сохраняется без необходимости управления им со стороны клиента.

Запрос:

{
|  "model": "hermes-agent",
|  "input": "What files are in my project?",
|  "instructions": "You are a helpful coding assistant.",
|  "store": true
|}
|

Ответ:

{
|  "id": "resp_abc123",
|  "object": "response",
|  "status": "completed",
|  "model": "hermes-agent",
|  "output": [
|    {"type": "function_call", "name": "terminal", "arguments": "{\\"command\\": \\"ls\\"}", "call_id": "call_1"},
|    {"type": "function_call_output", "call_id": "call_1", "output": "README.md src/ tests/"},
|    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
|  ],
|  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
|}
|

Встроенный ввод изображений: input[].content может содержать части input_text и input_image. Поддерживаются как удалённые URL, так и data:image/... URL:

{
|  "model": "hermes-agent",
|  "input": [
|    {
|      "role": "user",
|      "content": [
|        {"type": "input_text", "text": "Describe this screenshot."},
|        {"type": "input_image", "image_url": "data:image/png;base64,iVBORw0K..."}
|      ]
|    }
|  ]
|}
|

Загруженные файлы (input_file / file_id) и URL, не являющиеся изображениями (data:), возвращают ошибку 400 unsupported_content_type.

Многошаговый диалог с previous_response_id

Связывайте ответы, чтобы сохранять полный контекст (включая вызовы инструментов) между шагами:

{
|  "input": "Now show me the README",
|  "previous_response_id": "resp_abc123"
|}
|

Сервер восстанавливает полный диалог из сохранённой цепочки ответов — все предыдущие вызовы инструментов и результаты сохраняются. Связанные запросы также используют одну сессию, так что многошаговые беседы отображаются как единая запись на панели управления и в истории сессий.

Именованные беседы

Используйте параметр conversation вместо отслеживания ID ответов:

{"input": "Hello", "conversation": "my-project"}
|{"input": "What's in src/?", "conversation": "my-project"}
|{"input": "Run the tests", "conversation": "my-project"}
|

Сервер автоматически связывает запрос с последним ответом в этой беседе. Работает аналогично команде /title для сессий шлюза.

GET /v1/responses/{id}

Получить ранее сохранённый ответ по ID.

DELETE /v1/responses/{id}

Удалить сохранённый ответ.

GET /v1/models

Возвращает агента как доступную модель. Отображаемое имя модели по умолчанию соответствует имени профиля (или hermes-agent для профиля по умолчанию). Требуется большинством интерфейсов для обнаружения моделей.

GET /v1/capabilities

Возвращает машиночитаемое описание стабильной поверхности API-сервера для внешних UI, оркестраторов и плагинов-мостов.

{
|  "object": "hermes.api_server.capabilities",
|  "platform": "hermes-agent",
|  "model": "hermes-agent",
|  "auth": {"type": "bearer", "required": true},
|  "features": {
|    "chat_completions": true,
|    "responses_api": true,
|    "run_submission": true,
|    "run_status": true,
|    "run_events_sse": true,
|    "run_stop": true
|  }
|}
|

Используйте этот эндпоинт при интеграции панелей управления, браузерных UI или control plane, чтобы они могли определить, поддерживает ли работающая версия Hermes запуски (runs), стриминг, отмену и непрерывность сессий без обращения к внутренним Python-интерфейсам.

GET /health

Проверка работоспособности. Возвращает {"status": "ok"}. Также доступен по адресу GET /v1/health для OpenAI-совместимых клиентов, ожидающих префикс /v1/.

GET /health/detailed

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

Runs API (альтернатива для стриминга)

В дополнение к /v1/chat/completions и /v1/responses сервер предоставляет Runs API для длительных сессий, где клиент хочет подписываться на события прогресса вместо самостоятельного управления стримингом.

POST /v1/runs

Создать новый запуск агента. Возвращает run_id, который можно использовать для подписки на события прогресса.

{
|  "run_id": "run_abc123",
|  "status": "started"
|}
|

Запуски принимают простую строку input и опциональные параметры session_id, instructions, conversation_history или previous_response_id. При передаче session_id Hermes отображает его в статусе запуска, чтобы внешние UI могли соотносить запуски со своими идентификаторами бесед.

GET /v1/runs/{run_id}

Опрос текущего состояния запуска. Полезно для панелей управления, которым нужен статус без постоянного SSE-соединения, или для UI, переподключающихся после навигации.

{
|  "object": "hermes.run",
|  "run_id": "run_abc123",
|  "status": "completed",
|  "session_id": "space-session",
|  "model": "hermes-agent",
|  "output": "Done.",
|  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
|}
|

Статусы сохраняются в течение короткого времени после завершающих состояний (completed, failed или cancelled) для опроса и синхронизации UI.

GET /v1/runs/{run_id}/events

Поток Server-Sent Events с информацией о прогрессе вызовов инструментов, дельтах токенов и событиях жизненного цикла запуска. Разработан для панелей управления и «толстых» клиентов, которым нужно подключаться и отключаться без потери состояния.

POST /v1/runs/{run_id}/stop

Прервать выполняющийся шаг агента. Эндпоинт немедленно возвращает {"status": "stopping"}, пока Hermes запрашивает остановку активного агента в ближайшей безопасной точке прерывания.

Jobs API (фоновые запланированные задачи)

Сервер предоставляет лёгкий CRUD-интерфейс для управления запланированными/фоновыми запусками агента с удалённого клиента. Все эндпоинты защищены тем же bearer-аутентификацией.

GET /api/jobs

Список всех запланированных задач.

POST /api/jobs

Создать новую запланированную задачу. Тело принимает ту же структуру, что и hermes cron — prompt, расписание, навыки, переопределение провайдера, цель доставки.

GET /api/jobs/{job_id}

Получить определение задачи и состояние последнего запуска.

PATCH /api/jobs/{job_id}

Обновить поля существующей задачи (prompt, расписание и т.д.). Частичные обновления объединяются.

DELETE /api/jobs/{job_id}

Удалить задачу. Также отменяет выполняющийся запуск, если таковой имеется.

POST /api/jobs/{job_id}/pause

Приостановить задачу без удаления. Временные метки следующего запланированного запуска приостанавливаются до возобновления.

POST /api/jobs/{job_id}/resume

Возобновить ранее приостановленную задачу.

POST /api/jobs/{job_id}/run

Запустить задачу немедленно, вне расписания.

Обработка системного промпта

Когда интерфейс отправляет системное сообщение system (Chat Completions) или поле instructions (Responses API), hermes-agent добавляет его поверх своего основного системного промпта. Ваш агент сохраняет все инструменты, память и навыки — системный промпт интерфейса добавляет дополнительные инструкции.

Это означает, что вы можете настраивать поведение для каждого интерфейса без потери функциональности:

• Системный промпт Open WebUI: «You are a Python expert. Always include type hints.»

• Агент по-прежнему имеет доступ к терминалу, файловым инструментам, веб-поиску, памяти и т.д.

Аутентификация

Bearer-аутентификация через заголовок Authorization:

Authorization: Bearer ***
|

Настройте ключ через переменную окружения API_SERVER_KEY. Если браузер должен напрямую обращаться к Hermes, также установите API_SERVER_CORS_ORIGINS с явным списком разрешённых источников.