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 đủ (terminal, 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 tương thích OpenAI nào vào 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 - cuộc trò chuyện đầy đủ được bao gồm trong mỗi yêu cầu thông qua mảng messages.

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
}

Trả lờ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}
}

Truyền phát ( "stream": true ): Trả về 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ủa 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 , 🔍 Tài liệu Python ). These appear as inline markdown before the agent's response text, giving frontends like Open WebUI real-time visibility into tool execution.

POST /v1/responses

OpenAI Responses API format. Supports server-side conversation state via previous_response_id — the server stores full conversation history (including tool calls and results) so multi-turn context is preserved without the client managing it.

Request:

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

Response:

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

Multi-turn with previous_response_id

Chain responses to maintain full context (including tool calls) across turns:

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

The server reconstructs the full conversation from the stored response chain — all previous tool calls and results are preserved.

Named conversations

Use the hội thoại parameter instead of tracking response IDs:

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

The server automatically chains to the latest response in that conversation. Like the /title command for gateway sessions.

GET /v1/responses/{id}

Retrieve a previously stored response by ID.

DELETE /v1/responses/{id}

Delete a stored response.

GET /v1/models

Lists hermes-agent as an available model. Required by most frontends for model discovery.

GET /health

Health check. Returns {"status": "ok"}. Also available at GET /v1/health for OpenAI-compatible clients that expect the /v1/ prefix.

System Prompt Handling

When a frontend sends a hệ thống message (Chat Completions) or hướng dẫn field (Responses API), hermes-agent layers it on top of its core system prompt. Your agent keeps all its tools, memory, and skills — the frontend's system prompt adds extra instructions.

This means you can customize behavior per-frontend without losing capabilities:

• Open WebUI system prompt: "You are a Python expert. Always include type hints."
• The agent still has terminal, file tools, web search, memory, etc.

Authentication

Bearer token auth via the Ủy quyền header:

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	sai	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
• Chính sách giới thiệu: không có người giới thiệu — 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 Kiểm soát truy cập-Tuổi tối đa: 600 (10 minute cache)
• SSE streaming responses include CORS headers so browser EventSource clients work correctly
• Khóa tạm thời 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	—	Trường 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 trong các yêu cầu được chấp nhận nhưng mô hình LLM thực tế được sử dụng được định cấu hình phía máy chủ trong config.yaml.