4.8 KiB
4.8 KiB
title, type, tags, date
| title | type | tags | date | ||||
|---|---|---|---|---|---|---|---|
| Expose hermes-agent as an OpenAI-compatible API for any frontend | source |
|
2026-04-20 |
Source File
Summary（用中文描述）
- 核心主题：hermes-agent API Server 功能 —— 将 hermes-agent 暴露为 OpenAI 兼容的 HTTP API，使任何支持 OpenAI 格式的前端都能连接使用
- 问题域：AI Agent 的可访问性问题 —— 如何让任意前端（Open WebUI、LobeChat、LibreChat 等）接入 hermes-agent
- 方法/机制：
- 通过
API_SERVER_ENABLED=true启用内建 API Server - 默认监听
127.0.0.1:8642，Bearer token 认证 - 支持 Chat Completions API（无状态）、Responses API（有状态会话）、Runs API（实时进度）、Jobs API（定时任务）
- 系统提示词分层叠加，前端提示词不会覆盖 Agent 原有工具集
- 通过
- 结论/价值：hermes-agent 可作为 OpenAI API 的直接替代品，无缝接入现有 AI 前端生态，无需修改前端代码
Key Claims（用中文描述）
- hermes-agent API Server 将 Agent 暴露为 OpenAI 兼容 HTTP 端点，任何 OpenAI 格式的前端均可直连
- 默认绑定
127.0.0.1:8642，需配置API_SERVER_KEY启用 Bearer token 认证 /v1/chat/completions为无状态接口，每次请求需传递完整对话历史/v1/responses支持服务端会话状态，通过previous_response_id链式调用保留完整上下文（含工具调用）/v1/runsAPI 通过run_id+ SSE 事件流实现长会话实时进度订阅- Jobs API 提供 CRUD 接口，支持从远程客户端管理定时/后台 Agent 任务
- 前端传入的 system prompt 在 Agent 核心提示词之上分层叠加，保留全部工具能力
- 多用户场景通过 Profiles 隔离，每个 Profile 运行独立 API Server 实例（不同端口和认证密钥）
Key Quotes
"Any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox, and hundreds more — can connect to hermes-agent and use it as a backend." — 官方文档
"Your agent handles requests with its full toolset (terminal, file operations, web search, memory, skills) and returns the final response." — 官方文档
"When a frontend sends a system message (Chat Completions) or instructions field (Responses API), hermes-agent layers it on top of its core system prompt. Your agent keeps all its tools, memory, and skills." — 官方文档
"The API server gives full access to hermes-agent's toolset, including terminal commands. When binding to a non-loopback address like 0.0.0.0, API_SERVER_KEY is required." — 官方文档安全警告
Key Concepts
- OpenAI-Compatible API：遵循 OpenAI API 格式标准的接口层，允许非 OpenAI 后端替代原生服务
- Bearer Token Authentication：通过
Authorization: Bearer <token>头部进行 API 身份验证 - System Prompt Layering：前端提示词在 Agent 核心提示词之上分层叠加，不覆盖原有工具集
- Conversation State Persistence：服务端存储完整对话历史（含工具调用），客户端无需管理上下文
- Server-Sent Events (SSE)：流式响应协议，支持 token-by-token 推送和自定义工具进度事件
- CORS Allowlist：浏览器跨域访问控制，通过白名单精确控制允许的来源
- Multi-Profile Isolation：通过 Profiles 实现多用户隔离，每个实例独立配置、内存、技能
- Background Job Scheduling：远程客户端通过 Jobs API 管理定时/后台 Agent 任务
Key Entities
- hermes-agent：主项目， NousResearch 出品的 AI 编码 Agent，配备完整工具集（终端、文件、网络搜索、记忆、Skills）
- Open WebUI：开源 AI Web UI（126k stars），有完整集成指南
- LobeChat：开源 AI 聊天前端（73k stars），自定义 Provider 接入
- LibreChat：开源多后端聊天平台（34k stars），通过 librechat.yaml 配置
- NextChat：开源 ChatGPT Web 应用（87k stars），通过 BASE_URL 环境变量接入
- ChatBox：开源 AI 客户端（39k stars），API Host 设置接入
- AnythingLLM：开源 RAG AI 应用（56k stars），Generic OpenAI Provider 接入
- Jan：开源本地 AI 应用（26k stars），Remote Model 配置接入
Connections
- hermes-agent ← exposes ← OpenAI-Compatible API
- Open WebUI ← connects_to ← hermes-agent API Server
- LobeChat ← connects_to ← hermes-agent API Server
- LibreChat ← connects_to ← hermes-agent API Server
- NextChat ← connects_to ← hermes-agent API Server
- hermes-agent ← supports ← Multi-Profile Isolation
- hermes-agent ← implements ← Background Job Scheduling
Contradictions
- （暂无检测到冲突）