HTTP API 参考文档

本文档描述了硬件语音平台对外暴露的所有 HTTP API。

认证: 所有接口均需要在请求头中携带 JWT Token（通过 SSO 登录获取）。

Agent 管理

获取 Agent 列表

URL: GET /api/agents
认证: 需要

成功响应 (200):

json

{
  "agents": [
    {
      "id": 1,
      "agent_id": "my-agent",
      "name": "My Agent",
      "agent_type": "single",
      "sys_prompt": "你是一个智能助手",
      "voice_type": "zh_female_cancan",
      "welcome_message": "你好！",
      "is_custom_agent": false,
      "custom_agent_endpoint": null,
      "custom_agent_http_headers": {},
      "emqx_config_id": 1,
      "mqtt_opts": {},
      "tools": [
        {
          "name": "my-tool",
          "description": "工具描述",
          "transport": "streamable_http",
          "endpoint": "http://localhost:8080/mcp",
          "http_headers": {},
          "status": "connected"
        }
      ],
      "data_definitions": [],
      "current_clients": ["client-1"],
      "running": true,
      "inserted_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}

curl 示例:

bash

curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/api/agents'

获取单个 Agent 信息

URL: GET /api/agents/:id
认证: 需要

路径参数:

参数	类型	说明
`id`	integer	Agent 的数据库 ID

成功响应 (200): 返回单个 Agent 对象（结构同列表中的 Agent）。

失败响应:

json

// 404 - Agent 不存在
{"error": "Agent not found"}

curl 示例:

bash

curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/api/agents/1'

创建 Agent

URL: POST /api/agents
认证: 需要

请求体:

json

{
  "agent": {
    "agent_id": "my-new-agent",
    "name": "My New Agent",
    "agent_type": "single",
    "sys_prompt": "你是一个智能助手",
    "voice_type": "zh_female_cancan",
    "welcome_message": "你好！",
    "is_custom_agent": false,
    "emqx_config_id": 1,
    "mqtt_opts": {},
    "tools": [
      {
        "name": "tool-name",
        "description": "工具描述",
        "transport": "streamable_http",
        "endpoint": "http://localhost:8080/mcp",
        "http_headers": {},
        "enabled": true
      }
    ],
    "data_definitions": [
      {
        "topic_filter": "devices/{device_id}/telemetry",
        "description": "设备遥测数据",
        "data_prompts": "",
        "json_schema": {},
        "push_data_analysis_via_voice": false
      }
    ]
  }
}

字段说明:

字段	类型	必填	说明
`agent_id`	string	是	唯一标识，3-255 字符，仅允许字母、数字、下划线、连字符
`name`	string	是	Agent 名称，3-255 字符
`agent_type`	string	是	`"single"` 或 `"multi"`
`voice_type`	string	是	语音类型，最大 255 字符
`is_custom_agent`	boolean	是	是否为自定义 Agent
`sys_prompt`	string	否	系统提示词，最大 2000 字符
`welcome_message`	string	否	欢迎消息，最大 500 字符
`custom_agent_endpoint`	string	条件	自定义 Agent 时必填，需以 `ws://` 或 `wss://` 开头
`custom_agent_http_headers`	object	否	自定义 Agent 的 HTTP 请求头
`emqx_config_id`	integer	否	关联的 EMQX 配置 ID
`mqtt_opts`	object	否	MQTT 连接选项
`tools`	array	否	MCP 工具列表
`data_definitions`	array	否	MQTT 数据定义列表

成功响应 (201):

json

{
  "success": true,
  "message": "智能体创建成功"
}

失败响应 (422):

json

{
  "success": false,
  "errors": {
    "agent_id": ["has already been taken"]
  }
}

curl 示例:

bash

# 创建内置 Agent
curl -X POST -b 'sso_token=YOUR_JWT' \
  -H 'Content-Type: application/json' \
  'http://localhost:4000/api/agents' \
  -d '{
    "agent": {
      "agent_id": "smart-home-assistant",
      "name": "智能家居助手",
      "agent_type": "single",
      "sys_prompt": "你是一个智能家居助手，帮助用户控制家中的设备。",
      "voice_type": "zh_female_cancan",
      "welcome_message": "你好！我是你的智能家居助手。",
      "is_custom_agent": false,
      "emqx_config_id": 1,
      "tools": [
        {
          "name": "home-control",
          "description": "智能家居控制工具",
          "transport": "streamable_http",
          "endpoint": "http://localhost:8080/mcp",
          "enabled": true
        }
      ]
    }
  }'

# 创建自定义 Agent
curl -X POST -b 'sso_token=YOUR_JWT' \
  -H 'Content-Type: application/json' \
  'http://localhost:4000/api/agents' \
  -d '{
    "agent": {
      "agent_id": "custom-agent-1",
      "name": "自定义 Agent",
      "agent_type": "single",
      "voice_type": "zh_female_cancan",
      "is_custom_agent": true,
      "custom_agent_endpoint": "wss://my-agent.example.com/ws",
      "emqx_config_id": 1
    }
  }'

更新 Agent

URL: PUT /api/agents/:id
认证: 需要

路径参数:

参数	类型	说明
`id`	integer	Agent 的数据库 ID

请求体: 与创建相同（agent 对象），仅包含需要更新的字段。

成功响应 (200):

json

{
  "success": true,
  "message": "智能体更新成功",
  "agent": { /* Agent 对象 */ }
}

curl 示例:

bash

curl -X PUT -b 'sso_token=YOUR_JWT' \
  -H 'Content-Type: application/json' \
  'http://localhost:4000/api/agents/1' \
  -d '{
    "agent": {
      "name": "更新后的名称",
      "sys_prompt": "新的系统提示词"
    }
  }'

删除 Agent

URL: DELETE /api/agents/:id
认证: 需要

成功响应 (200):

json

{
  "success": true
}

curl 示例:

bash

curl -X DELETE -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/api/agents/1'

启动 Agent

启动指定的 Agent，使其开始监听 MQTT 消息并处理客户端请求。

URL: POST /api/agents/:id/start
认证: 需要

成功响应 (200):

json

{
  "success": true,
  "message": "Agent started successfully"
}

失败响应 (500):

json

{
  "success": false,
  "message": "Failed to start agent: reason"
}

curl 示例:

bash

curl -X POST -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/api/agents/1/start'

停止 Agent

URL: POST /api/agents/:id/stop
认证: 需要

成功响应 (200):

json

{
  "success": true,
  "message": "Agent stopped successfully"
}

curl 示例:

bash

curl -X POST -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/api/agents/1/stop'

查询 Agent 运行状态

URL: GET /api/agents/:id/status
认证: 需要

成功响应 (200):

json

{
  "running": true
}

curl 示例:

bash

curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/api/agents/1/status'

设备管理

获取 Agent 下的设备列表

URL: GET /api/agents/:id/devices
认证: 需要

成功响应 (200):

json

{
  "devices": [
    {
      "clientid": "device-001",
      "username": "user1",
      "ip_address": "192.168.1.100",
      "port": 1883,
      "keepalive": 60,
      "recv_msg": 42,
      "subscriptions_cnt": 3,
      "node": "emqx@127.0.0.1",
      "connected_at": "2026-01-01T00:00:00Z",
      "connected": true
    }
  ],
  "agent_name": "My Agent",
  "agent_id": "my-agent"
}

curl 示例:

bash

curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/api/agents/1/devices'

获取单个设备信息

URL: GET /api/agents/:id/devices/:client_id
认证: 需要

成功响应 (200):

json

{
  "client_info": {
    "clientid": "device-001",
    "username": "user1",
    "ip_address": "192.168.1.100",
    "port": 1883,
    "keepalive": 60,
    "recv_msg": 42,
    "subscriptions_cnt": 3,
    "node": "emqx@127.0.0.1",
    "connected_at": "2026-01-01T00:00:00Z",
    "connected": true
  }
}

curl 示例:

bash

curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/api/agents/1/devices/device-001'

踢出设备

断开指定客户端与 Agent 的连接。

URL: DELETE /api/agents/:id/devices/:client_id
认证: 需要

成功响应 (200):

json

{
  "success": true,
  "message": "客户端已踢下线"
}

curl 示例:

bash

curl -X DELETE -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/api/agents/1/devices/device-001'

语音交互

除了在设备侧通过 MQTT 协议启动和停止 RTC 会话之外，平台还提供了通过 HTTP API 启动和停止 RTC 语音会话的能力，适用于不方便使用 MQTT 协议的设备或场景。

启动语音对话

通过火山引擎 RTC 启动实时语音交互会话。

URL: POST /api/startVolcVoice
认证: 需要

请求体:

json

{
  "room_id": "room-123",
  "task_id": "task-456",
  "agent_id": "my-agent",
  "client_id": "client-001"
}

字段	类型	必填	说明
`room_id`	string	是	火山引擎 RTC 房间 ID
`task_id`	string	是	火山引擎任务 ID
`agent_id`	string	是	Agent 标识
`client_id`	string	是	客户端标识

成功响应 (200): 返回火山引擎 API 的响应数据。

失败响应:

json

// 400 - 参数错误
{"error": "Missing required params: room_id, task_id, agent_id, client_id"}

// 500 - 服务端错误
{"error": "Failed to start voice chat: reason"}

curl 示例:

bash

curl -X POST -b 'sso_token=YOUR_JWT' \
  -H 'Content-Type: application/json' \
  'http://localhost:4000/api/startVolcVoice' \
  -d '{
    "room_id": "room-123",
    "task_id": "task-456",
    "agent_id": "my-agent",
    "client_id": "client-001"
  }'

停止语音对话

URL: POST /api/stopVolcVoice
认证: 需要

请求体:

json

{
  "room_id": "room-123",
  "task_id": "task-456",
  "agent_id": "my-agent",
  "client_id": "client-001"
}

成功响应 (200): 返回火山引擎 API 的响应数据。

curl 示例:

bash

curl -X POST -b 'sso_token=YOUR_JWT' \
  -H 'Content-Type: application/json' \
  'http://localhost:4000/api/stopVolcVoice' \
  -d '{
    "room_id": "room-123",
    "task_id": "task-456",
    "agent_id": "my-agent",
    "client_id": "client-001"
  }'

EMQX 配置管理

获取所有 EMQX 配置

URL: GET /cloudapi/sys-configs/emqx
认证: 需要

查询参数（可选，用于过滤单条记录）:

参数	类型	说明
`name`	string	按名称精确查询
`deployment_id`	string	按 deployment_id 查询

成功响应 (200):

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "default-emqx",
      "deployment_id": "dep-001",
      "mqtt_broker": {
        "websocket_uri": "ws://broker.emqx.io:8083/mqtt",
        "mqtt_uri": "mqtt://broker.emqx.io:1883"
      },
      "emqx_api": {
        "uri": "http://broker.emqx.io:18083",
        "api_key": "admin",
        "secret_key": "public"
      },
      "mcp_bridge": {
        "streamable_http_uri": "http://localhost:8080/mcp",
        "sse_uri": null
      },
      "inserted_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}

curl 示例:

bash

# 列出所有
curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/cloudapi/sys-configs/emqx'

# 按名称查询
curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/cloudapi/sys-configs/emqx?name=default-emqx'

# 按 deployment_id 查询
curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/cloudapi/sys-configs/emqx?deployment_id=dep-001'

获取单个 EMQX 配置（按 ID）

URL: GET /cloudapi/sys-configs/emqx/:id
认证: 需要

curl 示例:

bash

curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/cloudapi/sys-configs/emqx/1'

获取单个 EMQX 配置（按 deployment_id）

URL: GET /cloudapi/sys-configs/emqx/by-deployment/:deployment_id
认证: 需要

curl 示例:

bash

curl -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/cloudapi/sys-configs/emqx/by-deployment/dep-001'

创建 EMQX 配置

URL: POST /cloudapi/sys-configs/emqx
认证: 需要

请求体:

json

{
  "name": "my-emqx-config",
  "deployment_id": "dep-002",
  "mqtt_broker": {
    "websocket_uri": "ws://broker.emqx.io:8083/mqtt",
    "mqtt_uri": "mqtt://broker.emqx.io:1883"
  },
  "emqx_api": {
    "uri": "http://broker.emqx.io:18083",
    "api_key": "admin",
    "secret_key": "public"
  },
  "mcp_bridge": {
    "streamable_http_uri": "http://localhost:8080/mcp"
  }
}

字段	类型	必填	说明
`name`	string	是	配置名称，3-255 字符，全局唯一
`deployment_id`	string	否	部署 ID，全局唯一
`mqtt_broker`	object	是	MQTT Broker 连接配置
`mqtt_broker.websocket_uri`	string	是	WebSocket 连接 URI
`mqtt_broker.mqtt_uri`	string	是	MQTT TCP 连接 URI
`emqx_api`	object	否	EMQX REST API 配置
`mcp_bridge`	object	否	MCP Bridge 配置

成功响应 (201):

json

{
  "success": true,
  "data": { /* EMQX 配置对象 */ }
}

curl 示例:

bash

curl -X POST -b 'sso_token=YOUR_JWT' \
  -H 'Content-Type: application/json' \
  'http://localhost:4000/cloudapi/sys-configs/emqx' \
  -d '{
    "name": "production-emqx",
    "deployment_id": "dep-prod-001",
    "mqtt_broker": {
      "websocket_uri": "wss://mqtt.example.com:8084/mqtt",
      "mqtt_uri": "mqtts://mqtt.example.com:8883"
    },
    "emqx_api": {
      "uri": "https://mqtt.example.com:18083",
      "api_key": "your-api-key",
      "secret_key": "your-secret-key"
    }
  }'

更新 EMQX 配置（按 ID）

URL: PUT /cloudapi/sys-configs/emqx/:id
认证: 需要

注意: deployment_id 字段不可更新。

curl 示例:

bash

curl -X PUT -b 'sso_token=YOUR_JWT' \
  -H 'Content-Type: application/json' \
  'http://localhost:4000/cloudapi/sys-configs/emqx/1' \
  -d '{
    "name": "updated-emqx-config",
    "mqtt_broker": {
      "websocket_uri": "wss://new-broker.example.com:8084/mqtt",
      "mqtt_uri": "mqtts://new-broker.example.com:8883"
    }
  }'

更新 EMQX 配置（按 deployment_id）

URL: PUT /cloudapi/sys-configs/emqx/by-deployment/:deployment_id
认证: 需要

curl 示例:

bash

curl -X PUT -b 'sso_token=YOUR_JWT' \
  -H 'Content-Type: application/json' \
  'http://localhost:4000/cloudapi/sys-configs/emqx/by-deployment/dep-001' \
  -d '{
    "name": "updated-config-name",
    "mqtt_broker": {
      "websocket_uri": "wss://new-broker.example.com:8084/mqtt",
      "mqtt_uri": "mqtts://new-broker.example.com:8883"
    }
  }'

删除 EMQX 配置

支持按 ID、名称、或 deployment_id 删除。

URL: DELETE /cloudapi/sys-configs/emqx/:id — 按 ID 删除
URL: DELETE /cloudapi/sys-configs/emqx?name=xxx — 按名称删除
URL: DELETE /cloudapi/sys-configs/emqx/by-deployment/:deployment_id — 按 deployment_id 删除
认证: 需要

成功响应 (200):

json

{
  "success": true,
  "message": "EMQX config deleted"
}

curl 示例:

bash

# 按 ID 删除
curl -X DELETE -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/cloudapi/sys-configs/emqx/1'

# 按名称删除
curl -X DELETE -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/cloudapi/sys-configs/emqx?name=my-emqx-config'

# 按 deployment_id 删除
curl -X DELETE -b 'sso_token=YOUR_JWT' \
  'http://localhost:4000/cloudapi/sys-configs/emqx/by-deployment/dep-001'

创建专有版部署

扩展认证

扩展授权

单点登录 (SSO)

告警

告警处理指南

CoAP 协议网关

规则

硬件语音

消息协议

基于 LLM 的 MQTT 数据处理

Schema 管理

平台 API

部署 API

Serverless 部署 API

HTTP API 参考文档

Agent 管理

获取 Agent 列表

获取单个 Agent 信息

创建 Agent

更新 Agent

删除 Agent

启动 Agent

停止 Agent

查询 Agent 运行状态

设备管理

获取 Agent 下的设备列表

获取单个设备信息

踢出设备

语音交互

启动语音对话

停止语音对话

EMQX 配置管理

获取所有 EMQX 配置

获取单个 EMQX 配置（按 ID）

获取单个 EMQX 配置（按 deployment_id）

创建 EMQX 配置

更新 EMQX 配置（按 ID）

更新 EMQX 配置（按 deployment_id）

删除 EMQX 配置

告警处理指南

Serverless 部署 API

HTTP API 参考文档 ​

Agent 管理 ​

获取 Agent 列表 ​

获取单个 Agent 信息 ​

创建 Agent ​

更新 Agent ​

删除 Agent ​

启动 Agent ​

停止 Agent ​

查询 Agent 运行状态 ​

设备管理 ​

获取 Agent 下的设备列表 ​

获取单个设备信息 ​

踢出设备 ​

语音交互 ​

启动语音对话 ​

停止语音对话 ​

EMQX 配置管理 ​

获取所有 EMQX 配置 ​

获取单个 EMQX 配置（按 ID） ​

获取单个 EMQX 配置（按 deployment_id） ​

创建 EMQX 配置 ​

更新 EMQX 配置（按 ID） ​

更新 EMQX 配置（按 deployment_id） ​

删除 EMQX 配置 ​

HTTP API 参考文档

Agent 管理

获取 Agent 列表

获取单个 Agent 信息

创建 Agent

更新 Agent

删除 Agent

启动 Agent

停止 Agent

查询 Agent 运行状态

设备管理

获取 Agent 下的设备列表

获取单个设备信息

踢出设备

语音交互

启动语音对话

停止语音对话

EMQX 配置管理

获取所有 EMQX 配置

获取单个 EMQX 配置（按 ID）

获取单个 EMQX 配置（按 deployment_id）

创建 EMQX 配置

更新 EMQX 配置（按 ID）

更新 EMQX 配置（按 deployment_id）

删除 EMQX 配置