Máy chủ API

Máy chủ API hiển thị hermes-agent dưới dạng điểm cuối HTTP tương thích với OpenAI. Bất kỳ giao diện người dùng nào sử dụng định dạng OpenAI — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox và hàng trăm giao diện khác — đều có thể kết nối với hermes-agent và sử dụng nó làm phụ trợ.

Tác nhân của bạn xử lý các yêu cầu bằng bộ công cụ đầy đủ (thiết bị đầu cuối, thao tác tệp, tìm kiếm trên web, bộ nhớ, kỹ năng) và trả về phản hồi cuối cùng. Khi phát trực tuyến, các chỉ báo tiến trình của công cụ xuất hiện nội tuyến để giao diện người dùng có thể hiển thị những gì tổng đài viên đang làm.

Bắt đầu nhanh

1. Kích hoạt máy chủ API

Thêm vào ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Optional: only if a browser must call Hermes directly
# API_SERVER_CORS_ORIGINS=http://localhost:3000

2. Khởi động cổng

hermes gateway

Bạn sẽ thấy:

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

3. Kết nối giao diện người dùng

Trỏ bất kỳ ứng dụng khách nào tương thích với OpenAI tại http://localhost:8642/v1:

# Test with 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ỳ giao diện người dùng nào khác — xem Hướng dẫn tích hợp Open WebUI để biết hướng dẫn từng bước.

Điểm cuối

BÀI ĐĂNG /v1/chat/hoàn thành

Định dạng hoàn thành trò chuyện OpenAI tiêu chuẩn. Không trạng thái - toàn bộ cuộc hội thoại được bao gồm trong mỗi yêu cầu thông qua mảng message.

Lời yêu cầu:

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

Phản ứng:

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

Truyền phát ("stream": true): Trả về các Sự kiện do máy chủ gửi (SSE) với các đoạn phản hồi theo từng mã thông báo. Khi tính năng phát trực tuyến được bật trong cấu hình, mã thông báo sẽ được phát trực tiếp khi LLM tạo chúng. Khi bị tắt, phản hồi đầy đủ sẽ được gửi dưới dạng một đoạn SSE.

Tiến trình công cụ trong luồng: Khi tác nhân gọi các công cụ trong yêu cầu phát trực tuyến, các chỉ báo tiến trình ngắn gọn sẽ được đưa vào luồng nội dung khi các công cụ bắt đầu thực thi (ví dụ: `💻 pwd`, `🔍 Python docs`). Chúng xuất hiện dưới dạng đánh dấu nội tuyến trước văn bản phản hồi của tác nhân, cung cấp cho các giao diện người dùng như khả năng hiển thị thời gian thực của Open WebUI trong quá trình thực thi công cụ.

POST /v1/phản hồi

Định dạng API phản hồi OpenAI. 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 lệnh gọi công cụ và kết quả) để bối cảnh nhiều lượt được giữ nguyên mà không cần khách hàng quản lý.

Lời 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 ứng:

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

Nhiều lượt với previous_response_id

Chuỗi phản hồi để duy trì bối cảnh đầy đủ (bao gồm cả các lệnh gọi công cụ) qua các lượt:

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

Máy chủ xây dựng lại toàn bộ cuộc hội thoại từ chuỗi phản hồi được lưu trữ — tất cả các lệnh gọi và kết quả công cụ trước đó đều được giữ nguyên.

Cuộc trò chuyện được đặt tên

Sử dụng tham số conversation thay vì theo dõi ID phản hồi:

{"input": "Hello", "conversation": "my-project"}
{"input": "What's in src/?", "conversation": "my-project"}
{"input": "Run the tests", "conversation": "my-project"}

Máy chủ tự động liên kết với phản hồi mới nhất trong cuộc trò chuyện đó. Giống như lệnh /title cho các phiên cổng.

NHẬN /v1/responses/{id}

Truy xuất phản hồi được lưu trữ trước đó bằng ID.

XÓA /v1/responses/{id}

Xóa phản hồi đã lưu.

NHẬN /v1/model

Liệt kê hermes-agent làm mẫu có sẵn. Được yêu cầu bởi hầu hết các giao diện người dùng để khám phá mô hình.

NHẬN /sức khỏe

Kiểm tra sức khỏe. Trả về {"trạng thái": "ok"}. Cũng có sẵn tại GET /v1/health dành cho các máy khách tương thích với OpenAI yêu cầu tiền tố /v1/.

Xử lý dấu nhắc hệ thống

Khi giao diện người dùng gửi thông báo hệ thống (Hoàn thành trò chuyện) hoặc trường hướng dẫn (API phản hồi), hermes-agent sẽ xếp nó lên trên lời nhắc hệ thống cốt lõi của nó. Tác nhân của bạn giữ lại tất cả các công cụ, bộ nhớ và kỹ năng của nó — lời nhắc hệ thống của giao diện người dùng sẽ bổ sung thêm các hướng dẫn bổ sung.

Điều này có nghĩa là bạn có thể tùy chỉnh hành vi trên mỗi giao diện người dùng mà không mất khả năng:

• Mở lời nhắc hệ thống WebUI: "Bạn là chuyên gia Python. Luôn bao gồm các gợi ý về loại."
• Agent vẫn có thiết bị đầu cuối, công cụ tập tin, tìm kiếm trên web, bộ nhớ, v.v.

Xác thực

Xác thực mã thông báo mang thông qua tiêu đề Ủy quyền:

Authorization: Bearer ***

Configure the key via API_SERVER_KEY env var. If you need a browser to call Hermes directly, also set API_SERVER_CORS_ORIGINS to an explicit allowlist.

Security

The API server gives full access to hermes-agent's toolset, including terminal commands. If you change the bind address to 0.0.0.0 (network-accessible), always set API_SERVER_KEY and keep API_SERVER_CORS_ORIGINS narrow — without that, remote callers may be able to execute arbitrary commands on your machine.

The default bind address (127.0.0.1) is for local-only use. Browser access is disabled by default; enable it only for explicit trusted origins.

Configuration

Environment Variables

Variable	Default	Description
API_SERVER_ENABLED	false	Enable the API server
API_SERVER_PORT	8642	HTTP server port
API_SERVER_HOST	127.0.0.1	Bind address (localhost only by default)
API_SERVER_KEY	(none)	Bearer token for auth
API_SERVER_CORS_ORIGINS	(none)	Comma-separated allowed browser origins

config.yaml

# Not yet supported — use environment variables.
# config.yaml support coming in a future release.

Security Headers

All responses include security headers:

• X-Content-Type-Options: nosniff — prevents MIME type sniffing
• Referrer-Policy: no-referrer — prevents referrer leakage

CORS

The API server does not enable browser CORS by default.

For direct browser access, set an explicit allowlist:

API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

When CORS is enabled:

• Preflight responses include Access-Control-Max-Age: 600 (10 minute cache)
• SSE streaming responses include CORS headers so browser EventSource clients work correctly
• Idempotency-Key is an allowed request header — clients can send it for deduplication (responses are cached by key for 5 minutes)

Most documented frontends such as Open WebUI connect server-to-server and do not need CORS at all.

Compatible Frontends

Any frontend that supports the OpenAI API format works. Tested/documented integrations:

Frontend	Stars	Connection
Open WebUI	126k	Full guide available
LobeChat	73k	Custom provider endpoint
LibreChat	34k	Custom endpoint in librechat.yaml
AnythingLLM	56k	Generic OpenAI provider
NextChat	87k	BASE_URL env var
ChatBox	39k	API Host setting
Jan	26k	Remote model config
HF Chat-UI	8k	OPENAI_BASE_URL
big-AGI	7k	Custom endpoint
OpenAI Python SDK	—	OpenAI(base_url="http://localhost:8642/v1")
curl	—	Direct HTTP requests

Limitations

• Response storage — stored responses (for previous_response_id) are persisted in SQLite and survive gateway restarts. Max 100 stored responses (LRU eviction).
• No file upload — vision/document analysis via uploaded files is not yet supported through the API.
• Model field is cosmetic — the model field in requests is accepted but the actual LLM model used is configured server-side in config.yaml.