API-сервер

API-сервер предоставляет Hermes-агент в качестве 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
# Опционально: только если браузер должен напрямую вызывать Hermes
# 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:

# Тест с 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. Не сохранять состояние — в каждом запросе включается полный диалог через массив 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. Поддерживаются как удаленные URL-адреса http(s), так и URL-адрес data:image/...:

{
  "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) и неизображения data: URL возвращают 400 unsupported_content_type.

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

Прогресс инструментов в потоках: - Завершения чата: Hermes отправляет event: hermes.tool.progress для отображения начала работы инструмента без загрязнения сохраненного текста ассистента. - Ответы: Hermes отправляет собственные критерии для получения результатов function_call и function_call_output во время SSE-потока, чтобы клиенты могли в кратчайшие сроки отображать структурированные инструменты пользовательского интерфейса.

POST /v1/ответы

Формат ответов API от OpenAI. Поддерживает состояние диалога на стороне сервера через 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-адреса, так и URL-адрес data:image/...:

{
  "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) и неизображения data: URL возвращают 400 unsupported_content_type.

Многошаговый режим с previous_response_id

Цепочка ответов для поддержания полного контекста (включая инструменты вызова) между шагами:

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

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

Именованные диалоги

Используйте параметр conversation вместо идентификационного идентификатора ответа:

{"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}

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

ПОЛУЧИТЬ /v1/модели

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

ПОЛУЧИТЬ /v1/capabilities

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

{
  "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
  }
}

Используйте эту конечную точку при региональных панелях управления, браузерном пользовательском интерфейсе или контрольных панелях, чтобы они могли определить поддержку рабочей версии запуска Hermes, стриминга, отмены и непрерывности сеансов, не полагаясь на внутренние данные Python.

ПОЛУЧИТЬ /здоровье

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

GET /health/detailed

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

Запускает 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 отображает его в состоянии запуска, чтобы внешний пользовательский интерфейс мог связать запуск со своими диалогами ID.

GET /v1/runs/{run_id}

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

{
  "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}
}

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

GET /v1/runs/{run_id}/events

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

POST /v1/runs/{run_id}/stop

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

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

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

ПОЛУЧИТЬ /api/jobs

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

POST /api/jobs

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

GET /api/jobs/{job_id}

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

ПАТЧ /api/jobs/{job_id}

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

DELETE /api/jobs/{job_id}

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

POST /api/jobs/{job_id}/pause

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

POST /api/jobs/{job_id}/resume

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

POST /api/jobs/{job_id}/run

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

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

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

Это означает, что вы можете настраивать поведение каждого фронтенда без потери возможностей: - Системный запрос Open WebUI: «Вы эксперт Python. Всегда включайте подсказки по типам». - Агент по-прежнему имеет терминал, файловые инструменты, веб-поиск, память и т.д.

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

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

Authorization: Bearer ***

Настройте ключ через переменное окружение API_SERVER_KEY. Если браузер должен напрямую перейти к Hermes, также установите API_SERVER_CORS_ORIGINS в явном списке разрешенных.:::предупреждение Безопасность API-сервер обеспечивает полный доступ к набору инструментов hermes-agent, ** включая терминала. При привязке к нелокальному адресу, например 0.0.0.0,API_SERVER_KEY обязателен**. Также держите узким API_SERVER_CORS_ORIGINS для контроля доступа браузера.

Адрес привязки по умолчанию (127.0.0.1) предназначен только для локального использования. Доступ к браузеру отключен по умолчанию; Включайте его только для явно доверенных источников.