智能体 API | 文档中心

认证说明

所有API接口都需要在请求头中包含有效的认证令牌：

text

Authorization: Bearer <token>

获取token方式参见平台api概要

当认证失败时，请求响应状态码为200，但返回以下响应：

json

{
  "code": 401,
  "msg": "未登录",
  "data": []
}

API列表

获取用户智能体列表（支持分页）

获取当前用户的智能体列表，支持分页查询。包含智能体的基本信息和配置状态

GEThttps://xrobo.qiniu.com/xiaozhi/agent/list

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:GET

返回类型:application/json

请求参数

参数名类型必填位置说明

limitinteger否query单页数量，默认20，范围1-100

cursorstring否query游标（上页最后一条ID，32位小写hex，格式：[a-f0-9]{32}）

请求头

Header名类型必填说明

Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例

GET /xiaozhi/agent/list?limit=20&cursor=4f3a8c7e0b6f4b5c9d3d0b8a2a1f0c9d HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>

响应示例

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": "4f3a8c7e0b6f4b5c9d3d0b8a2a1f0c9d",
      "agentName": "小智助手",
      "ttsModelName": "",
      "ttsVoiceName": "豪放可爱女",
      "llmModelName": "qwen3极速版",
      "vllmModelName": "智谱视觉AI",
      "memModelId": "Memory_mem_local_short",
      "systemPrompt": "[整体人设指导]\n核心原则:你是一个名为\"{{assistant_name}}\"的AI助手，你的所有输出和行为都......",
      "summaryMemory": null,
      "lastConnectedAt": "2024-03-20 10:00:00",
      "deviceCount": 5,
      "extra": null
    }
  ],
  "nextCursor": "5a1b2c3d4e5f67890123456789abcdef"
}

状态码

0OK - 成功获取智能体列表

401Unauthorized - 未登录或token无效

分页规则说明

默认行为：

limit 和 cursor 都不传：返回全量列表（兼容旧版本），nextCursor 为 null
只传 cursor：limit 默认为 20
limit <= 0：自动修正为 20
limit > 100：自动修正为 100

游标说明：

nextCursor 为 null 表示无更多数据
游标格式为32位小写十六进制字符串（如：4f3a8c7e0b6f4b5c9d3d0b8a2a1f0c9d）

分页使用示例

示例1：获取全量列表（兼容模式）

http

GET /xiaozhi/agent/list

返回全量列表，nextCursor 为 null

示例2：首页查询

http

GET /xiaozhi/agent/list?limit=20

获取前20条记录

示例3：翻页查询

http

GET /xiaozhi/agent/list?limit=20&cursor=4f3a8c7e0b6f4b5c9d3d0b8a2a1f0c9d

从指定游标位置继续获取20条记录

示例4：参数自动修正

http

GET /xiaozhi/agent/list?limit=0
# 服务端自动修正为 limit=20

GET /xiaozhi/agent/list?limit=1000
# 服务端自动修正为 limit=100

示例5：无效游标的错误响应

http

GET /xiaozhi/agent/list?limit=20&cursor=invalid-cursor

json

{
  "code": 500,
  "msg": "无效的游标参数",
  "data": null
}

示例6：数据已全部获取

json

{
  "code": 0,
  "msg": "success",
  "data": [],
  "nextCursor": null
}

搜索智能体

按名称前缀匹配搜索智能体，当前为全量返回搜索结果

GEThttps://xrobo.qiniu.com/xiaozhi/agent/search

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:GET

返回类型:application/json

请求参数

参数名类型必填位置说明

qstring是query搜索前缀（前缀匹配，例如搜索"小智"可命中"小智助手"）

请求头

Header名类型必填说明

Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例

GET /xiaozhi/agent/search?q=小智 HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>

响应示例

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": "4f3a8c7e0b6f4b5c9d3d0b8a2a1f0c9d",
      "agentName": "小智助手",
      "ttsModelName": "",
      "ttsVoiceName": "豪放可爱女",
      "llmModelName": "qwen3极速版",
      "vllmModelName": "智谱视觉AI",
      "memModelId": "Memory_mem_local_short",
      "systemPrompt": "[整体人设指导]\n核心原则:你是一个名为\"{{assistant_name}}\"的AI助手，你的所有输出和行为都......",
      "summaryMemory": null,
      "lastConnectedAt": "2024-03-20 10:00:00",
      "deviceCount": 5,
      "extra": null
    }
  ],
  "nextCursor": null
}

前缀匹配规则

搜索采用前缀匹配方式（SQL逻辑等价于：agent_name LIKE 'q%'）

✅ 搜索 "小智" 可以命中 "小智助手"
✅ 搜索 "小" 可以命中 "小智助手"
❌ 搜索 "助手" 无法命中 "小智助手"（因为不是前缀）

使用建议：从名称开头开始搜索才能匹配到结果

搜索返回说明

当前版本搜索结果为全量返回
nextCursor 固定为 null
未来可能支持分页，届时会提供游标机制

INFO

创建智能体时只需提供名称，其他配置可后续通过更新接口修改

创建智能体

创建一个新的智能体，只需要提供智能体名称，系统会自动分配其他默认配置，返回data为新智能体的ID，可用于更新、删除等api

POSThttps://xrobo.qiniu.com/xiaozhi/agent

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:POST

返回类型:application/json

请求参数

参数名类型必填位置说明

agentNamestring是body智能体名称

请求头

Header名类型必填说明

Content-Type是请求内容类型

Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例

POST /xiaozhi/agent HTTP/1.1
Host: https://xrobo.qiniu.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "agentName": "客服助手"
}

响应示例

{
  "code": 0,
  "msg": "success",
  "data": "6f99512f6b55429f8d2e3ddd0bcbe23f"
}

状态码

0OK - 智能体创建成功，返回智能体ID

401Unauthorized - 未登录或token无效

更新智能体

更新指定智能体的配置信息，包括模型配置、系统提示词、记忆设置、插件函数等

PUThttps://xrobo.qiniu.com/xiaozhi/agent/{id}

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:PUT

返回类型:application/json

请求参数

参数名类型必填位置说明

idstring是path智能体ID

agentUpdateObjAgentUpdateObj是body智能体更新对象

agentCodestring否-智能体代号，一般不用管

agentNamestring否-智能体名称

asrModelIdstring否-语音识别模型ID

vadModelIdstring否-语音活动检测ID

llmModelIdstring否-大语言模型ID

vllmModelIdstring否-VLLM模型ID

ttsModelIdstring否-语音合成模型ID

ttsVoiceIdstring否-音色ID

chatHistoryConfinteger(int32)否-聊天记录配置（0不记录 1仅记录文本 2记录文本和语音）

memModelIdstring否-记忆模型ID

intentModelIdstring否-意图模型ID

systemPromptstring否-角色设定参数

summaryMemorystring否-总结记忆

langCodestring否-语言代码

languagestring否-语言代码对应的名称

sortinteger(int32)否-排序序号

functionsarray否-插件函数信息

pluginIdstring否-插件ID

paramInfoobject否-函数参数信息

extraobject否-额外高级配置信息

voiceobject否-语音配置

speednumber否-语速

pitchnumber否-音调

volumenumber否-音量

emotionstring否-情感

请求头

Header名类型必填说明

Content-Type是请求内容类型

Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例

PUT /xiaozhi/agent/31dad2a8042a40ec879ef92a7bc240ae HTTP/1.1
Host: https://xrobo.qiniu.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "agentCode": "AGT_1754966279238",
  "agentName": "123test",
  "asrModelId": "ASR_DoubaoASR",
  "vadModelId": "VAD_SileroVAD",
  "llmModelId": "LLM_AliLLM",
  "vllmModelId": "VLLM_QwenVLVLLM",
  "ttsModelId": "",
  "ttsVoiceId": "a5b85a7ba5b24a9a96e24aa88b500d2f",
  "chatHistoryConf": 0,
  "memModelId": "Memory_mem_local_short",
  "intentModelId": "Intent_intent_llm",
  "systemPrompt": "*新的角色介绍",
  "summaryMemory": null,
  "langCode": "zh",
  "language": "中文",
  "sort": 0,
  "functions": [
    {
      "pluginId": "SYSTEM_PLUGIN_MUSIC",
      "paramInfo": {}
    },
    {
      "pluginId": "SYSTEM_PLUGIN_NEWS_NEWSNOW",
      "paramInfo": {
        "url": "https://newsnow.busiyi.world/api/s?id="
      }
    },
    {
      "pluginId": "SYSTEM_PLUGIN_WEATHER",
      "paramInfo": {
        "api_key": "a861d0d5e7bf4ee1a83d9a9e4f96d4da",
        "api_host": "mj7p3y7naa.re.qweatherapi.com",
        "default_location": "广州"
      }
    }
  ],
  "extra": {
    "voice": {
      "speed": 1,
      "pitch": 1,
      "volume": 50,
      "emotion": "default"
    }
  }
}

响应示例

{
  "code": 0,
  "msg": "success",
  "data": null
}

状态码

0OK - 操作成功

401Unauthorized - 未登录或token无效

INFO

更新智能体时，只需传递需要修改的字段，未传递的字段可以不传

删除智能体

删除指定的智能体，此操作不可逆，请谨慎使用

DELETEhttps://xrobo.qiniu.com/xiaozhi/agent/{id}

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:DELETE

返回类型:application/json

请求参数

参数名类型必填位置说明

idstring是path要删除的智能体ID

请求头

Header名类型必填说明

Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例

DELETE /xiaozhi/agent/31dad2a8042a40ec879ef92a7bc240ae HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>

响应示例

{
  "code": 0,
  "msg": "删除成功",
  "data": {}
}

状态码

0OK - 操作成功

401Unauthorized - 未登录或token无效

WARNING

删除操作不可逆，请确认后再执行

更新设备智能体

切换指定设备绑定的智能体。接口在更新设备表 ai_device.agent_id 的同时，会将该设备在 ai_agent_chat_history 中的 agent_id 一并更新为新的智能体 ID，保证历史聊天记录与当前智能体保持一致

PUThttps://xrobo.qiniu.com/v1/devices/{mac_address}/agent/{agent_id}

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/v1

Method:PUT

返回类型:application/json

请求参数

参数名类型必填位置说明

mac_addressstring是path设备 MAC 地址

agent_idstring是path智能体 ID（32位小写hex，对应 /agent/list、/agent/search 返回的 id 字段）

请求头

Header名类型必填说明

Content-Type是请求内容类型

Authorization是用户认证令牌，格式为 Bearer + 空格 + token

请求示例

PUT /v1/devices/AA:BB:CC:DD:EE:FF/agent/4f3a8c7e0b6f4b5c9d3d0b8a2a1f0c9d HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>
Content-Type: application/json

{}

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {}
}

状态码

0OK - 操作成功

401Unauthorized - 未登录或token无效

403Forbidden - 无权限操作该设备

500Internal Server Error - 服务端异常

INFO

此接口用于将设备切换绑定到不同的智能体

认证说明 ​

API列表 ​

获取用户智能体列表（支持分页） ​

获取用户智能体列表（支持分页）

基本信息

请求参数

请求头

请求示例

响应示例

状态码

搜索智能体 ​

搜索智能体

基本信息

请求参数

请求头

请求示例

响应示例

创建智能体 ​

创建智能体

基本信息

请求参数

请求头

请求示例

响应示例

状态码

更新智能体 ​

更新智能体

基本信息

请求参数

请求头

请求示例

响应示例

状态码

删除智能体 ​

删除智能体

基本信息

请求参数

请求头

请求示例

响应示例

状态码

更新设备智能体 ​

更新设备智能体

基本信息

请求参数

请求头

请求示例

响应示例

状态码

其他说明项 ​

认证说明

API列表

获取用户智能体列表（支持分页）

搜索智能体

创建智能体

更新智能体

删除智能体

更新设备智能体

其他说明项