API Server — Hermes as a Service | Easy Understand Hermes Agent

API Server — Hermes как сервис

Представьте: вы создали потрясающего AI-агента с помощью Hermes. Он умеет выполнять команды в терминале, искать в интернете, управлять файлами и запоминать информацию. Но он живёт в вашем терминале. Что, если бы вы могли подключить его к красивому чат-интерфейсу вроде Open WebUI или LobeChat? Именно это и делает API Server.

Думайте о нём как об универсальном переводчике. API Server предоставляет Hermes как HTTP-эндпоинт, совместимый с OpenAI. Это означает, что любой фронтенд, который «говорит на языке OpenAI» — а таких сотни — может подключиться к Hermes и использовать его как мощный бэкенд. Ваш агент сохраняет весь свой набор инструментов, а фронтенд становится просто красивой обёрткой для него.

Самое лучшее? При потоковой передаче ответов индикаторы прогресса инструментов появляются прямо в тексте. Так что ваши пользователи могут видеть, как агент выполняет команду или ищет в интернете, а не просто смотреть на мигающий курсор.

Один бэкенд — полная мощность

Прежде чем мы начнём, небольшой совет. Чтобы Hermes был полезен, ему нужны настроенный провайдер и инструментальные бэкенды. Подписка на Nous Portal решает обе задачи — вы получаете доступ к 300+ моделям, а также к веб-, графическим, TTS- и браузерным инструментам через Tool Gateway.

Выполните hermes setup --portal один раз — и вы готовы предоставить любому фронтенду полностью оснащённый инструментами бэкенд. Это самый простой способ начать.

Быстрый старт: три шага

1. Включите API Server

Откройте файл ~/.hermes/.env и добавьте эти строки:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Необязательно: только если браузер должен вызывать Hermes напрямую
# API_SERVER_CORS_ORIGINS=http://localhost:3000

API_SERVER_KEY — это ваш пароль. Смените его на что-то надёжное!

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.

Эндпоинты: два способа общения

API Server предлагает два основных эндпоинта.

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

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

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

Работают как удалённые URL, так и URL вида data:image/.... Обратите внимание: загруженные файлы и URL с данными, не являющимися изображениями, вернут ошибку 400 unsupported_content_type.

В потоковой передаче и кроется вся магия. Установите "stream": true, и вы получите Server-Sent Events (SSE) с ответами токен за токеном. Для Chat Completions вы увидите стандартные события chat.completion.chunk, а также специальное событие hermes.tool.progress. Это позволяет фронтендам показывать активность инструментов, не засоряя итоговый текст ассистента.

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", "status": "completed", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
    {"type": "function_call_output", "status": "completed", "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}
}

Обратите внимание, что вызовы инструментов имеют "status": "completed". Hermes уже выполнил их на стороне сервера. Клиенту остаётся только отобразить структурированный интерфейс инструментов.

Многоходовые диалоги — это просто. Просто связывайте ответы:

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

Сервер восстанавливает весь разговор, включая все вызовы инструментов, и продолжает с того места, где вы остановились.

Готовы к работе?

API Server превращает Hermes из локального инструмента в полноценный сервис. Предпочитаете ли вы простоту Chat Completions или мощь Responses с сохранением состояния — теперь у вас есть универсальный бэкенд для любого OpenAI-совместимого фронтенда. Попробуйте — ваш агент готов служить.