Hermes Agent HTTP API

认证方式

所有 API 请求均需通过 API 密钥进行身份验证。请将密钥包含在请求头中：

Authorization: Bearer your_api_key_here

备选请求头格式：

X-API-Key: abk_xxxxxxxxxxxx

API 密钥请在 WebUI → 设置中创建您的 API 密钥

核心接口

POST /api/v1/chat

发送聊天消息，返回 SSE 流。当 session_id 省略时，服务器自动生成 UUID。

GET /api/v1/chat/sessions

获取指定用户名下的会话列表，支持分页。

POST /api/v1/chat/new_session

为用户创建一个新的聊天会话。

POST /api/v1/chat/batch_delete_sessions

批量删除多个聊天会话。

GET /api/v1/configs

获取可用的配置文件列表。

POST /api/v1/file

上传聊天上下文所需的附件文件。

即时通讯 (UMO)

POST /api/v1/im/message

通过统一消息接口发送主动消息。

GET /api/v1/im/bots

获取已连接的机器人/平台 ID 列表。

插件与扩展 API

GET /api/v1/plugin/get

获取已安装的插件列表。

GET /api/v1/plugin/detail

根据插件名称获取插件详细信息。

GET /api/v1/plugin/market_list

获取插件市场中可用的插件列表。

POST /api/v1/plugin/install

安装新插件。

POST /api/v1/plugin/uninstall

卸载指定插件。

POST /api/v1/plugin/update

将插件更新至最新版本。

工具调用

工具调用使 Agent 能够与外部系统进行交互。工具通过注册表模式自动发现，并可在对话过程中被调用。

terminal

在主机系统上执行 Shell 命令，适用于系统管理任务。

file

读取、写入和管理文件，支持带安全验证的路径操作。

web

网络搜索和内容获取，提供强大的搜索与研究能力。

code

Python 代码解释器，用于动态计算和数据分析。

工具 Schema 格式

{
  "name": "web_search",
  "description": "Search the web for information",
  "parameters": {
    "query": {
      "type": "string",
      "description": "Search query"
    }
  }
}
            

会话管理

会话用于跟踪对话历史，支持自动压缩和智能截断。每个用户拥有独立的会话上下文。

请求参数

参数	类型	必填	说明
`username`	string	*	用于会话作用域的用户标识符
`session_id`	string (UUID)		指定要继续的会话 ID，如省略则自动生成
`message`	string	*	要发送的消息内容
`stream`	boolean		启用 SSE 流式响应（默认值：true）

创建新会话

# 创建一个新的聊天会话
curl -X POST 'http://localhost:6185/api/v1/chat/new_session' \
  -H 'Authorization: Bearer your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"username": "alice", "session_id": "optional-existing-id"}'
            

Provider 配置

配置多个 LLM 后端。Hermes Agent 通过统一的 Provider 接口支持 OpenAI、Anthropic、Gemini、MiniMax、GLM、Ollama 等多种模型。

Provider 管理器

{
  "providers": [
    {
      "name": "openai",
      "provider": "OpenAI",
      "model": "gpt-4o",
      "api_key": "sk-...",
      "base_url": "https://api.openai.com/v1"
    },
    {
      "name": "claude",
      "provider": "Anthropic",
      "model": "claude-sonnet-4-20250514",
      "api_key": "sk-ant-..."
    }
  ]
}
            

Provider 类型

OpenAI 兼容

OpenAI、SiliconFlow、302.AI、NewAPI 及任何 OpenAI 兼容 API。

Anthropic

通过 Anthropic API 调用 Claude 模型，支持工具调用。

Google Gemini

通过 Google AI 使用 Gemini Pro 和 Ultra 模型。

本地模型

使用 Ollama、LM Studio 进行自托管模型推理。

代码示例

发送聊天消息 (Python)

import requests
import json

# 发送聊天消息并获取流式响应
url = "http://localhost:6185/api/v1/chat"
headers = {
    "Authorization": "Bearer your_api_key",
    "Content-Type": "application/json"
}
payload = {
    "message": "Hello, list my files in /tmp",
    "username": "alice"
}

response = requests.post(url, headers=headers, json=payload, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))
            

cURL 示例

# 获取用户会话列表
curl -X GET 'http://localhost:6185/api/v1/chat/sessions?username=alice' \
  -H 'Authorization: Bearer your_api_key'

# 发送聊天消息
curl -N 'http://localhost:6185/api/v1/chat' \
  -H 'Authorization: Bearer your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Hello","username":"alice"}'
            

主动消息推送 (JavaScript)

// 通过 UMO 向用户发送主动消息
const response = await fetch('http://localhost:6185/api/v1/im/message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    platform: 'telegram',
    user_id: '123456789',
    message: 'Hello from Hermes Agent!'
  })
});
            

ACP 协议

Agent 通信协议 (ACP) 是 Hermes Agent 用于在客户端与 Agent 运行时之间进行结构化通信的消息格式。

ACP 消息结构

{
  "acp_version": "1.0",
  "type": "chat.request" | "chat.response" | "tool.call" | "tool.result",
  "payload": {
    "session_id": "uuid",
    "message": "user input",
    "context": {}
  },
  "metadata": {
    "timestamp": "ISO8601",
    "user_id": "string"
  }
}
            

消息类型

chat.request

用户消息，包含可选的会话上下文，用于继续对话。

chat.response

Agent 响应，包含文本内容及可选的工具调用。

tool.call

执行已注册工具的请求，包含相关参数。

tool.result

工具执行结果，返回给 Agent 进行综合处理。

HTTP API 文档