API Server — Hermes sebagai Layanan

API Server — Hermes sebagai Layanan

Bayangkan ini: kamu sudah membangun agen AI yang luar biasa dengan Hermes. Ia bisa menjalankan perintah terminal, mencari di web, mengelola file, dan mengingat berbagai hal. Tapi ia hanya hidup di terminal kamu. Bagaimana kalau kamu bisa menyambungkannya ke antarmuka chat yang indah seperti Open WebUI atau LobeChat? Justru itulah yang dilakukan API Server.

Anggap saja ini sebagai penerjemah universal. API Server mengekspos Hermes sebagai endpoint HTTP yang kompatibel dengan OpenAI. Artinya, frontend apa pun yang “berbicara bahasa OpenAI” — dan ada ratusan frontend seperti itu — bisa terhubung ke Hermes dan menggunakannya sebagai backend yang powerful. Agen kamu tetap memiliki seluruh perangkat tool-nya, dan frontend hanya menjadi tampilan cantik untuknya.

Bagian terbaiknya? Saat kamu melakukan streaming respons, indikator progres tool muncul secara inline. Jadi pengguna kamu benar-benar bisa melihat agen menjalankan perintah atau mencari di web, bukan hanya menatap kursor yang berkedip.

Satu Backend, Kekuatan Penuh

Sebelum kita masuk lebih dalam, ada tips singkat. Hermes membutuhkan provider yang terkonfigurasi dan backend tool agar berguna. Langganan Nous Portal menangani keduanya — kamu mendapatkan akses ke 300+ model plus tool web, gambar, TTS, dan browser melalui Tool Gateway.

Jalankan hermes setup --portal sekali saja, dan kamu siap memberikan backend lengkap dengan tool ke frontend mana pun. Ini cara termudah untuk memulai.

Mulai Cepat: Tiga Langkah

1. Aktifkan API Server

Buka file ~/.hermes/.env kamu dan tambahkan baris-baris ini:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Opsional: hanya jika browser harus memanggil Hermes secara langsung
# API_SERVER_CORS_ORIGINS=http://localhost:3000

API_SERVER_KEY adalah kata sandi kamu. Ganti dengan sesuatu yang aman!

2. Mulai Gateway

Jalankan perintah ini:

hermes gateway

Kamu akan melihat pesan seperti:

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

Itu saja. Agen kamu sekarang sudah menjadi sebuah layanan.

3. Hubungkan Frontend

Arahkan klien apa pun yang kompatibel dengan OpenAI ke http://localhost:8642/v1. Mari kita uji dengan 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!"}]}'

Atau hubungkan Open WebUI, LobeChat, atau frontend lainnya. Lihat panduan integrasi Open WebUI untuk petunjuk langkah demi langkah.

Endpoint: Dua Cara Berkomunikasi

API Server menawarkan dua endpoint utama.

POST /v1/chat/completions

Ini adalah format standar OpenAI Chat Completions. Endpoint ini stateless — kamu mengirim seluruh riwayat percakapan di setiap permintaan melalui array messages.

Berikut contoh permintaan sederhana:

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

Dan responsnya:

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

Gambar inline didukung. Kamu bisa mengirim gambar sebagai bagian dari konten pesan:

{
  "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 jarak jauh dan URL data:image/... sama-sama berfungsi. Perhatikan bahwa file yang diunggah dan data URL non-gambar akan mengembalikan error 400 unsupported_content_type.

Streaming adalah tempat keajaiban terjadi. Atur "stream": true dan kamu akan mendapatkan Server-Sent Events (SSE) dengan respons token demi token. Untuk Chat Completions, kamu akan melihat event standar chat.completion.chunk plus event khusus hermes.tool.progress. Ini memungkinkan frontend menampilkan aktivitas tool tanpa mengotori teks akhir asisten.

POST /v1/responses

Ini adalah format OpenAI Responses API yang lebih baru. Perbedaan besarnya? Endpoint ini mendukung state percakapan di sisi server melalui previous_response_id. Server menyimpan seluruh riwayat percakapan, termasuk panggilan tool dan hasilnya, sehingga konteks multi-putaran tetap terjaga tanpa harus dikelola oleh klien.

Berikut contoh permintaannya:

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

Responsnya menunjukkan panggilan tool yang sudah dieksekusi:

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

Perhatikan bagaimana panggilan tool memiliki "status": "completed". Hermes sudah menjalankannya di sisi server. Klien hanya perlu merender UI tool yang terstruktur.

Multi-putaran itu mudah. Cukup rangkai respons:

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

Server menyusun ulang seluruh percakapan, termasuk semua panggilan tool tersebut, dan melanjutkan dari titik terakhir kamu berhenti.

Siap Melayani?

API Server mengubah Hermes dari tool lokal menjadi layanan yang lengkap. Baik kamu lebih suka kesederhanaan Chat Completions atau kekuatan stateful dari Responses, sekarang kamu memiliki backend universal untuk frontend apa pun yang kompatibel dengan OpenAI. Cobalah — agen kamu siap melayani.