75 lines
4.8 KiB
Markdown
75 lines
4.8 KiB
Markdown
---
|
||
title: "Expose hermes-agent as an OpenAI-compatible API for any frontend"
|
||
type: source
|
||
tags:
|
||
- "hermes-agent"
|
||
- "api-server"
|
||
- "openai-compatible"
|
||
- "integration"
|
||
date: 2026-04-20
|
||
---
|
||
|
||
## Source File
|
||
- [[Agent/Expose hermes-agent as an OpenAI-compatible API for any frontend]]
|
||
|
||
## 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/runs` API 通过 `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
|
||
- （暂无检测到冲突）
|