为什么要把 Agent 变成 API？
大多数 AI Agent 设计为对话式交互——你问它答，它能调工具、写代码、执行任务。但很多场景需要的不是”工具人”，而是一个后端服务：
- 电商网站需要 AI 客服自动应答
- SaaS 产品需要智能工单回复
- 内部系统需要 RAG 问答接口
- 第三方应用需要接入 LLM 能力
如果每次都要从零搭建 LLM 后端、处理 API Key、实现流式输出，成本太高。Hermes Agent 内置了 OpenAI 兼容的 API Server，直接把 Agent 的能力暴露为标准 API，前端开箱即用。
架构一览
整个方案的架构非常简洁：
前端网页 ──→ OpenAI 格式 API ──→ Hermes API Server ──→ Hermes Agent (LLM)
(任意) localhost:8642 (已内置) (你的模型)
没有额外的中转服务，没有 FastAPI/Flask 中间层。Hermes API Server 本身就兼容 OpenAI Chat Completions 格式，支持：
POST /v1/chat/completions— 对话补全（支持流式 SSE）GET /v1/models— 模型列表POST /v1/responses— OpenAI Responses APIGET /health— 健康检查
任何 OpenAI 兼容的前端（LobeChat、Open WebUI、ChatBox、NextChat 等）都能直接连接。
第一步：配置 API Server
API Server 是 Hermes Gateway 的一部分，无需单独安装。只需要配置环境变量。
编辑 ~/.hermes/.env，添加以下内容：
# API Server 配置
API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-api-key # 自定义密钥，防止未授权访问
API_SERVER_HOST=0.0.0.0 # 监听地址，0.0.0.0 允许外部访问
API_SERVER_PORT=8642 # 端口号
API_SERVER_CORS_ORIGINS=* # CORS 跨域（开发阶段用 *，生产环境改为具体域名）
API_SERVER_MODEL_NAME=my-bot # 对外暴露的模型名
同时在 ~/.hermes/config.yaml 中确认 API Server 已启用：
gateway:
api_server_enabled: true
platform_toolsets:
api_server:
- hermes-api-server
重启 Hermes Gateway 使配置生效：
# 如果 Gateway 已在运行
hermes gateway restart
# 或者直接启动
hermes gateway run
第二步：验证 API
启动后，先验证 API 是否正常：
# 健康检查
curl http://localhost:8642/health
# 返回：{"status": "ok", "platform": "hermes-agent"}
# 列出模型（需要 API Key）
curl http://localhost:8642/v1/models \
-H "Authorization: Bearer your-secret-api-key"
# 返回：{"object": "list", "data": [{"id": "my-bot", ...}]}
然后发一条对话试试：
curl http://localhost:8642/v1/chat/completions \
-H "Authorization: Bearer your-secret-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "my-bot",
"messages": [
{"role": "system", "content": "你是一个友好的助手"},
{"role": "user", "content": "你好"}
],
"max_tokens": 100
}'
如果返回标准的 OpenAI 格式 JSON，就说明 API 完全工作了。
第三步：构建客服人设和知识库
AI 客服的核心是 system prompt + 知识库。API Server 支持通过 system 角色消息注入人设，这意味着我们不需要修改后端，只在请求中带上即可。
客服人设
const persona = `你是"云端优选电商"的AI智能客服，名叫小云。你的职责是回答顾客关于商品、订单、退换货、物流等问题。
行为准则：
1. 友好热情，用亲切的语气和顾客交流
2. 回答要准确，基于提供的知识库信息
3. 如果顾客问的问题不在知识库中，诚实说"这个问题我需要帮您确认"，并建议联系人工客服
4. 绝不编造不存在的商品、价格或政策
5. 回复简洁，一个问题控制在3-5句话
6. 适当使用表情符号增加亲和力
7. 当顾客表达不满时，先道歉再提供解决方案`;
商品知识库
知识库直接附在人设后面，作为 system prompt 的一部分：
const knowledge = `
=== 商品知识库 ===
【智能穿戴】
- 云手环 Pro：心率/血氧/睡眠监测，IP68防水，续航14天，¥299
- 云手表 Ultra：AMOLED屏，GPS导航，100+运动模式，¥1299
- 云耳 Buds：真无线降噪耳机，续航30小时，¥399
【优惠政策】
- 新用户首单立减¥30（满199可用）
- 满299免运费，不满299运费¥8
- 会员日（每月8号）全场9折
【退换货】
- 7天无理由退货（未拆封）
- 15天质量问题换货
- 1年保修（智能穿戴/智能家居类）
...`;
发送请求时，把它们组装成 messages：
const messages = [
{ role: 'system', content: persona + '\n\n' + knowledge },
...conversationHistory, // 用户和助手的对话历史
];
第四步：前端聊天组件
下面是一个完整的、可嵌入任何网站的客服组件。它支持流式输出（逐字显示）、对话记忆、快捷问题和响应式布局。
核心通信代码
// 流式请求（SSE）—— 体验比普通请求好得多
async function streamReply(userMessage) {
const response = await fetch('http://localhost:8642/v1/chat/completions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-secret-api-key',
},
body: JSON.stringify({
model: 'my-bot',
messages: [
{ role: 'system', content: persona + '\n\n' + knowledge },
...conversationHistory,
],
stream: true, // 关键：开启流式输出
max_tokens: 1024,
temperature: 0.7,
}),
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
let fullReply = '';
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split('\n');
buffer = lines.pop(); // 保留不完整的行
for (const line of lines) {
if (!line.startsWith('data: ')) continue;
const payload = line.slice(6).trim();
if (payload === '[DONE]') break;
try {
const json = JSON.parse(payload);
const delta = json.choices?.[0]?.delta?.content || '';
if (delta) {
fullReply += delta;
// 实时更新气泡内容
bubbleElement.textContent = fullReply;
}
} catch {}
}
}
return fullReply;
}
完整组件结构
组件由四部分构成：
┌─────────────────────────┐
│ 📋 在线客服 × │ ← 头部（可自定义标题）
├─────────────────────────┤
│ 🤖 欢迎语... │
│ 👤 用户消息 │ ← 消息区（自动滚动）
│ 🤖 AI 回复... │
├─────────────────────────┤
│ [产品咨询] [发货时间] │ ← 快捷问题按钮
├─────────────────────────┤
│ [请输入您的问题...] ➤ │ ← 输入区
└─────────────────────────┘
右下角有一个浮动按钮 💬，点击展开聊天窗口，关闭时收回。移动端自动全屏。
嵌入任意网站
把以下代码加到你网站的 HTML 中即可：
<!-- 在 </body> 前插入 -->
<link rel="stylesheet" href="cs-widget.css">
<script src="cs-config.js"></script>
<button id="cs-fab">💬</button>
<div id="cs-window">
<!-- 聊天窗口内容 -->
</div>
<script src="cs-widget.js"></script>
修改 cs-config.js 中的 persona、knowledge、quickQuestions 即可定制为你的业务客服。
实战效果
我搭建了一个”云端优选电商”的 Demo，来看看小云的表现：
顾客：你们卖什么产品？
你好呀！欢迎来到云端优选电商😊 我们有三大品类： 📱 智能穿戴 — 云手环 Pro ¥299，云手表 Ultra ¥1299，云耳 Buds ¥399 🏠 智能家居 — 云灯 Color ¥129，云摄 360 ¥249，云锁 S1 ¥899 🔌 数码配件 — 云充 65W ¥149，云线 ¥39…
顾客：现在有什么优惠活动吗？
我们现在有好几种优惠活动呢😊
- 新用户首单立减¥30 — 满¥199即可使用！
- 满¥299免运费
- 会员日全场9折 — 每月8号⏰ … 比如新用户买个云手环 Pro（¥299），用首单减¥30，到手才¥269，还免运费！
回答基于知识库、价格准确、语气亲切——这正是 system prompt 中约束的效果。
进阶玩法
1. 对接第三方前端
API Server 兼容 OpenAI 格式，意味着可以直接连 LobeChat、Open WebUI 等：
- LobeChat：设置 → 语言模型 → OpenAI → API 地址填
http://your-server:8642/v1 - Open WebUI：设置 → OpenAI API → Base URL 填
http://your-server:8642/v1
2. 多人隔离会话
API Server 支持通过 X-Hermes-Session-Id 头实现会话隔离。不同用户使用不同的 Session ID，Agent 会维护独立的对话上下文：
fetch('/v1/chat/completions', {
headers: {
'Authorization': 'Bearer your-secret-api-key',
'X-Hermes-Session-Id': `user-${userId}`, // 每个用户唯一
},
// ...
});
3. 部署到生产环境
关键注意事项：
| 项目 | 开发环境 | 生产环境 |
|---|---|---|
| HOST | 0.0.0.0 | 0.0.0.0 |
| CORS | * | 具体域名 |
| API Key | 简单字符串 | 随机强密码 |
| HTTPS | 不需要 | Nginx 反代 + SSL |
| API 地址 | localhost:8642 | your-domain.com/api |
推荐用 Nginx 反向代理：
location /api/ {
proxy_pass http://127.0.0.1:8642/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_buffering off; # 流式输出必须关闭缓冲
}
前端配置改为生产地址：
apiUrl: 'https://your-domain.com/api/v1/chat/completions'
4. 知识库热更新
知识库是 JavaScript 变量，修改后刷新页面即生效。也可以把知识库放到外部文件：
// 启动时从服务器加载最新知识库
const knowledge = await fetch('/knowledge-base.txt').then(r => r.text());
这样更新知识库只需替换文本文件，无需改动代码。
总结
Hermes Agent 的 API Server 把 Agent 从”聊天工具”变成了”后端服务”，一条命令开启，OpenAI 兼容，前端直连。整个客服方案的核心就三个配置：
- API_SERVER_KEY — 认证密钥
- system prompt — 人设 + 知识库
- 前端组件 — 发请求、渲染消息
不需要 FastAPI 中转，不需要额外的向量数据库，不需要 RAG 管线。对于中小规模的客服场景，这个方案够用了。当知识库大到 prompt 装不下时，再考虑引入 RAG 层。
完整的代码文件已放在 pan.baidu.com/s/1bpnJP-V_… 提取码: iduw，包括 index.html（完整组件）、cs-config.js（配置中心）和 knowledge-base.md（知识库原文）。复制到你的项目，改改人设和知识库，就能跑起来。
