智能体 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

请求参数

参数名类型必填位置说明

limit

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

cursor

string否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": "小智助手",
      "assistantName": "助手阿伟",
      "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
}

搜索智能体

支持按名称前缀、设备 MAC 地址或智能体 ID 搜索智能体

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

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:GET

返回类型:application/json

请求参数

参数名类型必填位置说明

q

string是query搜索关键词

type

string否query搜索类型，支持 name（智能体名称）、mac（设备 MAC 地址）、agent_id（智能体 ID）。缺省默认为 name

请求头

Header名类型必填说明

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

请求示例

// 示例 1：按名称前缀搜索（默认）
GET /xiaozhi/agent/search?q=小智&type=name HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>

// 示例 2：按设备 MAC 地址精确搜索
GET /xiaozhi/agent/search?q=AA:BB:CC:DD:EE:FF&type=mac HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>

// 示例 3：按智能体 ID 精确搜索
GET /xiaozhi/agent/search?q=4f3a8c7e0b6f4b5c9d3d0b8a2a1f0c9d&type=agent_id HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>

响应示例

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": "4f3a8c7e0b6f4b5c9d3d0b8a2a1f0c9d",
      "agentName": "小智助手",
      "assistantName": "助手阿伟",
      "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
}

状态码

0OK - 成功搜索智能体

401Unauthorized - 未登录或token无效

搜索类型与匹配规则

name（智能体名称，默认）：采用前缀匹配方式（SQL 逻辑等价于 agent_name LIKE 'q%'，例如搜索 "小智" 可命中 "小智助手"）
mac（设备 MAC 地址）：采用精确匹配，查询绑定该 MAC 设备且归属于当前用户的智能体
agent_id（智能体 ID）：采用精确匹配，按智能体 ID 查询归属于当前用户的智能体

📌 说明：搜索结果目前为全量返回，响应体中的 nextCursor 固定为 null，无需处理游标分页。

INFO

创建智能体时可指定大语言模型和意图模型；未传模型ID时使用默认模板配置，也可在创建后通过更新接口修改

创建智能体

创建一个新的智能体，可在创建时指定大语言模型和意图模型。未指定的模型使用默认模板配置，返回data为新智能体的ID，可用于更新、删除等api

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

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:POST

返回类型:application/json

请求参数

参数名类型必填位置说明

agentName

string是body智能体名称

assistantName

string是body助手昵称

langCode

string否body语言编码，不传时使用默认模板。可通过 GET /v1/languages 获取可选语言

ttsVoiceId

string否body音色ID，不传时使用系统或默认模板。可通过 GET /v1/voices 获取可选音色

systemPrompt

string否body角色设定，不传时使用默认模板配置

llmModelId

string否body大语言模型配置ID，不传时使用默认模板。DeepSeek V4 Flash（推荐）：f3626c105383d71654a57f2bb8a973f3；其他可选模型通过 GET /v1/agents/models/llm 获取

memModelId

string否body记忆模型ID，不传时使用默认模板。无记忆：Memory_nomem；长期记忆：Memory_long_term_memory

intentModelId

string否body意图模型ID，不传时使用默认模板。无意图识别：Intent_nointent；统一意图识别：Intent_function_call

请求头

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": "客服助手",
  "assistantName": "助手阿伟",
  "llmModelId": "f3626c105383d71654a57f2bb8a973f3",
  "intentModelId": "Intent_function_call"
}

响应示例

{
  "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

请求参数

参数名类型必填位置说明

id

string是path智能体ID

agentUpdateObj

AgentUpdateObj是body智能体更新对象

请求头

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",
  "assistantName": "助手阿伟",
  "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": {
    "llm": {
      "temperature": 0.7,
      "top_p": 1.0,
      "frequency_penalty": 0.0,
      "max_tokens": 500,
      "enable_search": false,
      "custom_params": {
        "body": {
          "<自定义参数key>": "<按 schema 取值>"
        }
      }
    },
    "voice": {
      "volume": 50,
      "speed": 1.0,
      "pitch": 1.0,
      "emotion": "default",
      "quality": "medium",
      "enable_tts_emotion": false
    },
    "asr": {
      "disable_emotion": false,
      "enable_auto_lang": false
    },
    "goodbye": {
      "prompt": "",
      "language": "",
      "emotion": "",
      "content": ""
    },
    "voiceprint": {
      "chat_only_enabled": false
    },
    "disabled_builtin_tools": []
  }
}

响应示例

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

状态码

0OK - 操作成功

401Unauthorized - 未登录或token无效

INFO

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

LLM 参数说明

extra.llm 下的标准参数（temperature、top_p 等）越界会被自动夹取、不报错；extra.llm.custom_params.body 下的自定义参数会按所选模型的 schema 校验，非法参数直接拒绝。支持哪些自定义参数取决于所选模型、且会随模型调整而变化，具体 key/类型请以模型 schema 查询结果为准，详见大语言模型 API 的「大模型自定义参数（custom_params）」一节。

记忆模型说明

memModelId 用于配置智能体的记忆模式。详细说明及系统行为请参见长期记忆 API。

删除智能体

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

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

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:DELETE

返回类型:application/json

请求参数

参数名类型必填位置说明

id

string是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_address

string是path设备 MAC 地址

agent_id

string是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

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

获取智能体详情

获取指定智能体的配置详情，包括基础信息、模型配置、提示词、知识库绑定、设备数量和最近连接时间

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

点击展开

基本信息

Host:https://xrobo.qiniu.com

Base Path:/xiaozhi

Method:GET

返回类型:application/json

请求参数

参数名类型必填位置说明

id

string是path智能体ID

请求头

Header名类型必填说明

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

请求示例

GET /xiaozhi/agent/xxxxxx HTTP/1.1
Host: https://xrobo.qiniu.com
Authorization: Bearer <token>

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": "xxxx",
    "agentName": "小智助手",
    "assistantName": "助手阿伟",
    "llmModelId": "LLM_AliLLM",
    "ttsVoiceId": "xxxxxxx",
    "memModelId": "Memory_mem_local_short",
    "intentModelId": "Intent_intent_llm",
    "chatHistoryConf": 1,
    "systemPrompt": "...",
    "summaryMemory": null,
    "language": "中文",
    "langCode": "zh",
    "datasetIds": [],
    "deviceCount": 5,
    "lastConnectedAt": "2026-07-09 09:00:00",
    "createdAt": "2026-07-01 12:00:00",
    "updatedAt": "2026-07-09 09:00:00"
  }
}

状态码

0OK - 成功获取智能体详情

401Unauthorized - 未授权或token无效

500Internal Server Error - 智能体不存在

认证说明 ​

API列表 ​

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

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

基本信息

请求参数

请求头

请求示例

响应示例

状态码

搜索智能体 ​

搜索智能体

基本信息

请求参数

请求头

请求示例

响应示例

状态码

创建智能体 ​

创建智能体

基本信息

请求参数

请求头

请求示例

响应示例

状态码

更新智能体 ​

更新智能体

基本信息

请求参数

请求头

请求示例

响应示例

状态码

删除智能体 ​

删除智能体

基本信息

请求参数

请求头

请求示例

响应示例

状态码

更新设备智能体 ​

更新设备智能体

基本信息

请求参数

请求头

请求示例

响应示例

状态码

获取智能体详情 ​

获取智能体详情

基本信息

请求参数

请求头

请求示例

响应示例

状态码

其他说明项 ​

认证说明

API列表

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

搜索智能体

创建智能体

更新智能体

删除智能体

更新设备智能体

获取智能体详情

其他说明项