🤖HermesBlog
Hermes Feature Guides · パート 268/9/2026

APIサーバー — サービスとしてのHermes

API Server — Hermes as a Service — easy-to-understand guide based on official docs

hermes-feature-26-api-server

APIサーバー — サービスとしてのHermes

想像してみてください。Hermesで素晴らしいAIエージェントを構築したとします。ターミナルコマンドを実行し、ウェブを検索し、ファイルを管理し、物事を記憶することができます。しかし、それはターミナルの中に閉じ込められています。もし、それをOpen WebUIやLobeChatのような美しいチャットインターフェースに接続できたらどうでしょう？ それがまさにAPIサーバーの役割です。

これは万能翻訳機だと考えてください。APIサーバーはHermesをOpenAI互換のHTTPエンドポイントとして公開します。つまり、「OpenAI言語」を話すフロントエンド — 何百ものアプリケーションが存在します — は、Hermesに接続して強力なバックエンドとして利用できるのです。エージェントは完全なツールセットを維持し、フロントエンドは単にそのための美しい顔になります。

さらに良いニュースは？ レスポンスをストリーミングすると、ツールの進行状況インジケーターがインラインで表示されます。つまり、ユーザーはエージェントがコマンドを実行したりウェブを検索したりするのを実際に見ることができ、点滅するカーソルをじっと見つめるだけではありません。

1つのバックエンド、フルパワー

本題に入る前に、ちょっとしたヒントです。Hermesを有用にするには、設定済みのプロバイダーとツールバックエンドが必要です。Nous Portalのサブスクリプションで両方が手に入ります — 300以上のモデルに加え、Tool Gateway経由でウェブ、画像、TTS、ブラウザツールにアクセスできます。

hermes setup --portal を一度実行するだけで、あらゆるフロントエンドに完全なツール装備のバックエンドを提供できます。始めるのに最も簡単な方法です。

クイックスタート：3つのステップ

1. APIサーバーを有効にする

~/.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統合ガイドでステップバイステップの手順を確認できます。

エンドポイント：2つの通信方法

APIサーバーは2つの主要なエンドポイントを提供します。

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と data:image/... URLの両方が機能します。アップロードされたファイルや非画像データ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はすでにサーバーサイドでそれらを実行済みです。クライアントは構造化されたツールUIをレンダリングするだけです。

マルチターンは簡単です。 レスポンスをチェーンするだけです：

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

サーバーはそれらのツール呼び出しを含む完全な会話を再構築し、中断したところから続行します。

提供開始の準備はできましたか？

APIサーバーはHermesをローカルツールから本格的なサービスへと変貌させます。Chat Completionsのシンプルさを好むか、Responsesのステートフルなパワーを好むかにかかわらず、あらゆるOpenAI互換フロントエンドのための万能バックエンドが手に入ります。ぜひ試してみてください — あなたのエージェントはサービスを提供する準備ができています。

📖 公式ドキュメント

この記事は Hermes Agent の公式ドキュメントに基づいています：公式ドキュメント › user-guide/features/api-server

← すべての記事に戻る