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

API Server — Hermes như một Dịch vụ

Hãy tưởng tượng thế này: bạn đã xây dựng một AI agent tuyệt vời với Hermes. Nó có thể chạy lệnh terminal, tìm kiếm web, quản lý file và ghi nhớ mọi thứ. Nhưng nó chỉ sống trong terminal của bạn. Nếu bạn có thể kết nối nó với một giao diện chat đẹp mắt như Open WebUI hay LobeChat thì sao? Đó chính xác là những gì API Server làm.

Hãy nghĩ về nó như một “phiên dịch viên vạn năng”. API Server phơi bày Hermes dưới dạng một HTTP endpoint tương thích OpenAI. Điều này có nghĩa là bất kỳ frontend nào “nói ngôn ngữ OpenAI” — và có hàng trăm cái như vậy — đều có thể kết nối với Hermes và sử dụng nó như một backend mạnh mẽ. Agent của bạn giữ nguyên toàn bộ bộ công cụ, và frontend chỉ đơn giản trở thành một “bộ mặt xinh đẹp” cho nó.

Phần tuyệt nhất? Khi bạn stream phản hồi, các chỉ báo tiến trình công cụ sẽ xuất hiện ngay trong luồng. Vì vậy, người dùng của bạn có thể thực sự thấy agent đang chạy lệnh hoặc tìm kiếm web, chứ không chỉ nhìn chằm chằm vào con trỏ nhấp nháy.

Một Backend, Toàn Bộ Sức Mạnh

Trước khi đi sâu, một mẹo nhanh. Hermes cần một provider và các tool backend được cấu hình để hoạt động hữu ích. Gói đăng ký Nous Portal đáp ứng cả hai — bạn có quyền truy cập vào hơn 300 mô hình cùng với các công cụ web, hình ảnh, TTS và trình duyệt thông qua Tool Gateway.

Chạy hermes setup --portal một lần, và bạn đã sẵn sàng cung cấp cho bất kỳ frontend nào một backend đầy đủ công cụ. Đó là cách dễ nhất để bắt đầu.

Bắt Đầu Nhanh: Ba Bước

1. Kích Hoạt API Server

Mở file ~/.hermes/.env của bạn và thêm các dòng sau:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Tùy chọn: chỉ cần nếu trình duyệt phải gọi trực tiếp đến Hermes
# API_SERVER_CORS_ORIGINS=http://localhost:3000

API_SERVER_KEY chính là mật khẩu của bạn. Hãy đổi nó thành một thứ gì đó an toàn!

2. Khởi Động Gateway

Chạy lệnh này:

hermes gateway

Bạn sẽ thấy một thông báo như:

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

Vậy là xong. Agent của bạn giờ đã trở thành một dịch vụ.

3. Kết Nối Frontend

Trỏ bất kỳ client tương thích OpenAI nào tới http://localhost:8642/v1. Hãy thử nghiệm với 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!"}]}'

Hoặc kết nối Open WebUI, LobeChat, hoặc bất kỳ frontend nào khác. Xem hướng dẫn tích hợp Open WebUI để biết các bước chi tiết.

Các Endpoint: Hai Cách Giao Tiếp

API Server cung cấp hai endpoint chính.

POST /v1/chat/completions

Đây là định dạng Chat Completions chuẩn của OpenAI. Nó không trạng thái — bạn gửi toàn bộ lịch sử hội thoại trong mỗi yêu cầu thông qua mảng messages.

Đây là một yêu cầu đơn giản:

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

Và phản hồi:

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

Hỗ trợ hình ảnh nội tuyến. Bạn có thể gửi hình ảnh như một phần của nội dung tin nhắn:

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

Cả URL từ xa và URL data:image/... đều hoạt động. Lưu ý rằng các file đã tải lên và data URL không phải hình ảnh sẽ trả về lỗi 400 unsupported_content_type.

Streaming chính là nơi phép màu xảy ra. Đặt "stream": true và bạn sẽ nhận được Server-Sent Events (SSE) với phản hồi từng token một. Đối với Chat Completions, bạn sẽ thấy các sự kiện chat.completion.chunk chuẩn cùng với sự kiện tùy chỉnh hermes.tool.progress. Điều này cho phép frontend hiển thị hoạt động của công cụ mà không làm nhiễu văn bản trợ lý cuối cùng.

POST /v1/responses

Đây là định dạng mới hơn của OpenAI Responses API. Điểm khác biệt lớn? Nó hỗ trợ trạng thái hội thoại phía máy chủ thông qua previous_response_id. Máy chủ lưu trữ toàn bộ lịch sử hội thoại, bao gồm cả các lệnh gọi công cụ và kết quả, để ngữ cảnh nhiều lượt được giữ nguyên mà client không cần quản lý.

Đây là một yêu cầu:

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

Phản hồi hiển thị các lệnh gọi công cụ đã được thực thi:

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

Chú ý cách các lệnh gọi công cụ có "status": "completed". Hermes đã chạy chúng ở phía máy chủ. Client chỉ cần hiển thị giao diện công cụ có cấu trúc.

Nhiều lượt thật dễ dàng. Chỉ cần nối chuỗi các phản hồi:

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

Máy chủ tái tạo toàn bộ cuộc hội thoại, bao gồm tất cả các lệnh gọi công cụ đó, và tiếp tục từ nơi bạn dừng lại.

Sẵn Sàng Phục Vụ?

API Server biến Hermes từ một công cụ cục bộ thành một dịch vụ hoàn chỉnh. Dù bạn thích sự đơn giản của Chat Completions hay sức mạnh trạng thái của Responses, giờ bạn đã có một backend phổ quát cho bất kỳ frontend tương thích OpenAI nào. Hãy thử ngay — agent của bạn đã sẵn sàng phục vụ.