主题
智能体和角色管理
本章回答五个问题:为什么需要多智能体、怎么管理智能体、一个角色由什么构成、怎么切换智能体与角色、怎么隔离记忆。
- 智能体:产品之下的一层配置单元,决定「能做什么」(技能、指令、交互策略、MCP 服务),拥有唯一标识 Agent ID。一个产品下可创建多个智能体,其中有且仅有一个「默认智能体」。
- 角色:智能体之下的一层配置单元,包含 人设(性格底座)、音色(声音)和语种配置(可选),并拥有唯一标识
role_code。- 人设:角色的性格提示词,自动拼接到生效智能体下所有技能的 prompt 头部。
- 音色:角色语音回复时使用的声音,涉及多来源、多优先级的生效规则。
入口:产品管理 → 点击目标产品卡片 → 智能体列表 / 角色配置区
1. 智能体管理
1.1 为什么需要多智能体
角色解决的是「用什么性格、什么声音说」,而智能体解决的是「能做什么」。当同一款硬件需要在不同场景下提供不同的能力集合时,仅靠多角色无法满足:
| 典型诉求 | 举例 |
|---|---|
| 不同场景需要不同技能组合 | 「学习模式」只开闲聊 + 百科,「家居模式」额外开 AIoT 控制 |
| 不同业务线需要独立的指令与策略 | 儿童侧与家长侧各自维护自定义指令、交互策略 |
| 不同合作方需要独立的外部能力 | 不同智能体挂载不同的 MCP 服务与知识库 |
多智能体让「技能 / 指令 / 交互策略 / MCP 服务」成为可独立维护、互不干扰的能力集合,而角色库、热词、记忆配置仍在产品层统一维护,避免重复配置。
1.2 智能体管理操作
| 操作 | 说明 |
|---|---|
| 新建智能体 | 在产品详情页的智能体区域点击新建,填写智能体名称;创建后系统自动为该智能体生成 1 个默认角色 |
| 查看智能体列表 | 产品详情页以列表形式展示该产品下所有智能体,默认智能体带有「默认」标识 |
| 编辑智能体 | 点击目标智能体进入配置详情页,配置技能、指令、交互策略、MCP 服务,并勾选该智能体启用的角色 |
| 切换默认智能体 | 将某个非默认智能体设为默认智能体 |
| 删除智能体 | 删除非默认智能体,删除后该智能体下的配置不可恢复 |
1.3 智能体规则
| 规则 | 说明 |
|---|---|
| 数量上限 | 一个产品下最多 10 个智能体(含默认智能体) |
| 默认智能体 | 有且仅有一个,不可删除;端侧未指定智能体时由它兜底 |
| 默认角色 | 每个智能体创建时自动生成 1 个默认角色,该默认角色不可删除 |
| Agent ID | 智能体唯一标识,端侧按此标识指定生效智能体 |
| AIoT 指令权限 | 只有默认智能体可以编辑 AIoT 指令,其他智能体仅可对已有指令做「开 / 关」,详见 AIoT 指令 |
1.4 切换默认智能体的影响
| 影响项 | 说明 |
|---|---|
| 存量设备需重新建联 | 切换后,已连接的设备需重新建联才会生效 |
| 配置迁移 | 原默认智能体的 AIoT 指令配置会自动迁移到新的默认智能体 |
| AIoT 编辑权限转移 | 编辑 AIoT 指令的权限随「默认」标识转移到新的默认智能体 |
| 已注册设备音色不变 | 已注册设备的设备音色不会被修改,仍保持注册当时写入的音色 |
2. 为什么需要多角色
同一台设备、同一个智能体,常常需要面对不同的使用者或不同的使用场景,而这些场景对「性格 + 声音」的要求并不相同:
| 典型诉求 | 举例 |
|---|---|
| 一台设备服务多类人群 | 儿童手表白天是「学习搭子」,晚上是「哄睡伙伴」 |
| 一个产品需要多个 IP 形象 | 同一款音箱内置「大白」「小鹿」两个 IP,用户可自由切换 |
| 不同场景需要不同口吻 | 厨房场景要简洁高效,陪伴场景要温暖啰嗦 |
| 不同角色的记忆不应串台 | 家长模式下的对话内容,不应被儿童模式引用 |
多角色管理把「人设 + 音色」独立成可复用、可切换、可隔离的配置单元:
- 可复用:角色维护在产品维度的角色库中,产品下的多个智能体都可以勾选同一个角色。
- 可切换:端侧在对话时上行
role_code,即可在运行时切换到指定角色的人设与音色,无需重新发布配置。 - 可隔离:记忆支持按
role_code区隔存储,不同角色之间的记忆互不干扰。
3. 三层结构与角色构成
3.1 三层结构
产品(Product)
├── ASR / 热词、记忆配置、角色库
└── 智能体(Agent)× N(其中 1 个为默认智能体)
├── 勾选角色 → 角色(Role)
│ ├── 人设(性格提示词)
│ ├── 音色(声音)
│ ├── 语种配置(可选,锁定回复话术及 TTS 播报语种)
│ └── role_code(角色唯一标识)
├── 技能、旧版指令、交互策略、MCP 服务
└── AIoT 指令(仅默认智能体可编辑,其他智能体仅可开 / 关)| 层级 | 承载内容 | 非默认智能体权限 | 说明 |
|---|---|---|---|
| 产品 | ASR / 热词、记忆配置、角色库 | 对所有智能体统一生效 | 热词、记忆配置、角色库均为产品维度,产品下所有智能体共享 |
| 智能体 | 技能、旧版指令、交互策略、MCP 服务 | ✅ 可独立配置 | 每个智能体独立维护自己的能力集合 |
| 智能体 | AIoT 指令 | ❌ 仅可开 / 关,不可编辑 | 仅默认智能体可编辑 AIoT 指令 |
| 智能体 | 勾选角色 | ✅ 可独立勾选 | 智能体只能勾选本产品角色库中的角色 |
| 角色 | 人设 + 音色 + 语种配置(可选)+ role_code | — | 实际决定「用什么性格、什么声音说话」的最小单元,可在支持的技能下锁定回复语种 |
3.2 角色包含什么
| 构成要素 | 作用 | 配置位置 |
|---|---|---|
| 角色名称 | 前台标识,便于识别(≤ 10 个字符) | 角色配置区 |
| 人设 | 性格底座,自动拼接到该智能体所有技能的 prompt 头部 | 角色配置区 → 人设编辑框 |
| 音色 | 该角色语音回复时使用的声音 | 角色配置区 → 音色选择器 |
| 语种配置 | 默认关闭;开启后,在支持的技能下锁定该角色的回复话术及 TTS 播报语种 | 角色配置区 → 语种配置开关 / 语种设置弹窗 |
role_code | 角色唯一标识,前台外显,供端侧上行切换角色时使用 | 系统生成,前台可查看 |
4. 角色配置
4.1 新建与配置角色
| 步骤 | 操作 |
|---|---|
| Step 1 进入产品 | 在「产品管理」中点击目标产品卡片,进入产品详情页 |
| Step 2 新建角色 | 在角色配置区新建角色,填写角色名称(≤ 10 字符);角色库为产品维度,新建后该产品下所有智能体均可勾选 |
| Step 3 编写人设 | 在人设编辑框编写角色提示词,支持 Markdown 格式 |
| Step 4 插入系统变量(可选) | 点击编辑框右上角变量按钮,选择变量,以 ${variableName} 格式插入到光标位置 |
| Step 5 选择音色 | 在音色选择器中为该角色指定音色 |
| Step 6 设置语种(可选) | 默认关闭;如需锁定回复话术及 TTS 播报语种,开启「语种配置」开关,再点击「语种配置」打开弹窗选择语种,详见 §4.4 语种设置 |
| Step 7 勾选到智能体 | 进入目标智能体的配置详情页,勾选需要启用的角色 |
| Step 8 调试验证 | 在调试窗选择该智能体与该角色,验证人设、音色及语种表现;开启语种配置后需对涉及的技能进行完整测试 |
| Step 9 保存与发布 | 「保存草稿」:保存但不生效,可在调试窗测试;「发布」:正式生效,所有绑定该产品的设备生效 |
4.2 角色规则
| 规则 | 说明 |
|---|---|
| 默认角色 | 每创建一个智能体,系统自动为其创建 1 个默认角色 |
| 角色名长度 | ≤ 10 个字符 |
| 新建数量 | 不限制新建数量 |
| 删除限制 | 已关联智能体的角色与各智能体的默认角色不可删除 |
role_code | 前台外显,端侧按此标识切换角色 |
4.3 默认角色的特殊作用
每个智能体都有自己的「默认角色」。默认角色除了是一个普通角色外,还承担两项兜底职责:
| 职责 | 说明 |
|---|---|
未传 role_code 时的兜底 | 已传 Agent ID 时,运营平台的产品使用所传智能体的默认角色,支撑平台创建的产品使用 App 绑定的角色列表中的第一个角色;若连 Agent ID 也未上行,则使用「默认智能体的默认角色」。以上情况均使用设备音色 |
| 新注册设备的音色来源 | 产品下新注册的设备,其设备音色默认填充为注册当时「默认智能体的默认角色」的音色;已注册的存量设备不受影响 |
智能体对外展示的音色,即该智能体默认角色的音色。
4.4 语种设置
语种配置属于角色级配置,默认关闭。 与角色音色一样,在角色配置区为对应角色进行设置,基于该角色的配置生效。
使用场景
当此角色需要指定并锁定回复话术及 TTS 播报语种,不随 ASR 识别结果或用户输入进行随动变化时,可开启语种配置。
设置步骤
在角色配置区找到需要设置的角色,开启「语种配置」开关;

开启后,点击「语种配置」打开语种设置弹窗;

选择对应语种,按角色配置流程进行调试、保存与发布。
支持范围
| 项目 | 当前支持范围 |
|---|---|
| 语种选项 | 普通话-中文、粤语、英语 |
| 支持技能 | 闲聊、自定义闲聊、查时间、查天气 |
注:如需支持更多语种或更多系统技能,请联系 JoyInside 对接人员进行测试适配。
生效范围与方言技能优先级
- 仅在当前角色下锁定语种,其他 Agent 和角色不受影响;
- 仅在上述支持的部分技能下生效,不是对该 Agent 下所有技能统一锁定;
- 开启角色语种配置后,若此 Agent 下添加了方言技能,以语种配置指定的回复语种(方言)优先,方言技能在当前角色下失效;
- 在当前角色下,不支持 ASR 方言随动、不支持「说方言对话」、不支持语音切方言功能。
开启后请完整测试
角色语种配置开启后,实际回复及播报效果仍会受到角色人设提示词、音色和技能提示词的影响。请对涉及的技能及对话场景进行完整测试,如需帮助,可联系 JoyInside 对接人员协助。
后续能力
后续会增加角色语种配置切换接口,当前尚未提供,敬请期待。
5. 人设
5.1 能力说明
人设是角色的「性格底座」。 在角色配置区编辑的人设提示词,会自动拼接到生效智能体下所有技能(系统技能 + 自定义技能)的 prompt 头部,确保智能体在任何技能场景(闲聊、查天气、AIoT 设备控制等)都保持统一的角色一致性。
| 特征 | 说明 |
|---|---|
| 作用范围 | 角色生效时,生效智能体下所有技能均自动继承该角色的人设 |
| 编辑入口 | 产品管理 → 点击目标产品卡片 → 角色配置区 |
| 变量支持 | 支持插入系统变量,对话时实时渲染 |
| 生效时机 | 保存草稿后即可在调试窗生效;正式生效需点击「发布」 |
系统变量: 在人设编辑框右上角点击变量插入按钮,可选择以下系统变量,每次对话时实时渲染,无需手动更新。
| 变量 | 格式 | 说明 |
|---|---|---|
| 系统时间 | ${systemTime} | 实时渲染为当前对话时刻的系统时间 |
| 设备位置 | ${location} | 设备端上传的地理位置或 IP 解析结果 |
| 长期记忆 | ${memoBaseContent} | 该用户与设备的长期记忆内容 |
5.2 人设撰写模板
markdown
# 角色设定
## 1. 基本信息
- 姓名:
- 背景设定:
- 身份:
- MBTI:
## 2. 性格气质
-
## 3. 语言表达风格
-
## 4. 外观与交互设定
-
## 5. 能力描述
-5.3 人设撰写要点
| 要点 | 说明 |
|---|---|
| 明确角色与设备的关系 | 角色「住在」什么设备里?如何解释自己的存在? |
| 写出行为边界 | 角色所在的设备有什么能力 |
| 结合产品场景 | 陪伴类设备偏温暖,工具类设备偏专业高效 |
| 多角色之间拉开差异 | 同一产品下的多个角色,建议在称呼、语气、话题偏好上明显区分,避免用户「听不出切换」 |
| 用系统变量增强沉浸感 | 如用 ${systemTime} 让角色感知时间(如「这么晚了还不睡?」) |
| 控制 prompt 长度 | 建议 300-800 字,过长会影响模型对核心人设的遵循度 |
5.4 使用系统变量的示例
当前时间是 ${systemTime},请根据时间段调整问候方式:
- 早上(6:00-11:00):活力开朗
- 下午(11:00-18:00):平稳温和
- 晚上(18:00-23:00):轻松舒缓
- 深夜(23:00-6:00):关心用户休息
用户所在位置:${location},可以在聊天中自然融入当地话题。6. 音色
6.1 能力说明
音色即角色语音回复时使用的声音。平台支持系统音色和自定义音色(音色复刻功能见 音色库)。每个角色绑定一个音色,一个智能体可挂多个角色,因此一个智能体可对应多个音色。
6.2 生效音色优先级
| 优先级 | 音色来源 | 说明 | 生效范围 |
|---|---|---|---|
| 第 0 层(最高) | 音色切换技能 | 用户通过对话触发「音色切换技能」,直接改变设备音色 | 仅本轮对话生效 |
| 第 1 层 | 角色音色 / 设备音色 | 按端侧上行的 Agent ID / role_code 组合决定,见下表 | 每次 query |
未触发音色切换技能时,本轮音色按下表决定:
| 上行 Agent ID | 上行 role_code | 本轮音色 |
|---|---|---|
| 不传 | 不传 | 设备音色 |
| 传 | 不传 | 设备音色 |
| 不传 | 传 | 所传角色的音色 |
| 传 | 传 | 所传角色的音色 |
⚠ 音色切换技能只能改变「设备音色」,不改角色音色。举例:
- 设备音色 A、role1 角色音色 B,用切换技能切到 C → 本轮音色为 C,此时【设备音色 = C,role1 角色音色 = B】。下次建联上行 role1 → 音色为 B;不传
role_code(无论是否传 Agent ID)→ 音色为 C。- 设备音色 A,切到 C → 本轮音色 C,此时【设备音色 = C】,下次建联若不传
role_code,音色仍为 C。
6.3 其他音色概念
| 音色 | 说明 | 作用 |
|---|---|---|
| 角色音色 | 在角色配置区的音色选择器中设置,是前台唯一可见的音色配置入口 | ① 端侧上行 role_code 时作为本轮对话音色生效;② 其中「默认智能体的默认角色」的音色作为该产品新注册设备的设备音色来源(后台自动填充) |
| 设备音色 | 设备注册时写入、可在设备管理中单独配置,详见 设备管理 | 端侧未上行 role_code 时作为本轮对话音色生效,与是否上行 Agent ID 无关;音色切换技能改变的也是这个值 |
| 设备原始音色 | 等于该设备注册时建联产品的默认智能体的默认角色的音色,在注册时独立记录 | 若未修改或切换设备音色,则设备原始音色 = 设备音色;用户要求「返回原来的音色」时,设备音色恢复为设备原始音色 |
6.4 关键规则
- 默认智能体的默认角色音色 → 新注册设备(单向、仅新注册):修改「默认智能体的默认角色」音色后,之后该产品新注册的设备,其设备音色默认填充为注册当时该角色的音色;已注册的存量设备不受影响。
- 切换默认智能体不改已注册设备的音色:切换默认智能体后,已注册设备的设备音色保持不变。
- 设备原始音色单独存储、逻辑独立:它等于设备注册时建联产品的默认智能体的默认角色的音色,不随角色音色的后续修改或设备音色的修改、切换而变化。若未修改或切换设备音色,则设备原始音色与设备音色相同;用户要求「返回原来的音色」时,设备音色恢复为该原始音色。
- 音色切换技能不改角色音色:技能只改设备音色且仅本轮生效,角色音色只能在运营平台的角色配置区修改。
7. 智能体与角色切换
7.1 智能体与角色的生效规则
智能体与角色的切换由端侧驱动:端侧在对话时上行 Agent ID / role_code,服务端据此确定本轮对话的生效智能体(决定能做什么)与生效角色(决定人设);本轮音色按下表单独确定。
| 上行 Agent ID | 上行 role_code | 生效智能体 | 生效角色(决定人设) | 本轮音色 |
|---|---|---|---|---|
| 不传 | 不传 | 默认智能体 | 默认智能体的默认角色 | 设备音色 |
| 传 | 不传 | 所传智能体 | 运营平台的产品:该智能体的默认角色;支撑平台创建的产品:App 绑定的角色列表中的第一个角色 | 设备音色 |
| 不传 | 传 | 默认智能体 | 所传角色 | 所传角色的音色 |
| 传 | 传 | 所传智能体 | 所传角色 | 所传角色的音色 |
⚠ 平台不校验
role_code与 Agent ID 的关联关系。 无论所传角色是否已勾选到所传智能体下,一律按上表生效,不会报错、也不会回落到默认值。⚠ 音色切换技能的优先级高于上表,但仅对本轮对话生效,详见 §6.2 生效音色优先级。
| 环节 | 说明 |
|---|---|
| 上行标识 | 端侧在发送 query 时携带 Agent ID / role_code |
| 服务端生效 | 服务端按 Agent ID 加载智能体配置,按 role_code 加载人设 + 音色 |
| 未传时兜底 | 两者均未上行时,使用「默认智能体的默认角色」,音色落到设备音色 |
role_code 在运营平台角色配置区外显,可直接复制给端侧 / 应用侧使用;Agent ID 与 role_code 的上传方式见 A. HTTP API 参考。
7.2 调试窗切换智能体与角色
调试窗支持选择本次调试使用的智能体与角色:
| 项 | 说明 |
|---|---|
| 智能体可选范围 | 当前产品下的所有智能体 |
| 角色可选范围 | 所选智能体已勾选的角色(切换智能体后,角色下拉框联动刷新) |
| 默认值 | 当前所选智能体的默认角色 |
| 效果 | 切换后,调试对话即使用该智能体的配置与该角色的人设、音色,可用于验证多智能体 / 多角色差异 |
入口:页面右上角「展开调试」→ 右侧「预览调试」面板 →「设备连接」→ 在「智能体」「角色」下拉框中选择。

8. 记忆隔离
8.1 为什么要隔离记忆
多个智能体、多个角色共用一份记忆时,会出现「串台」:用户在 A 角色下说过的内容,被 B 角色引用;在「学习模式」智能体下的对话,被「家居模式」智能体引用。按维度隔离后,各自维护独立记忆,人格与场景更稳定。
8.2 记忆配置方案
记忆配置属于产品维度(在产品层统一设置,对产品下所有智能体生效),可按「智能体」和「角色」两个维度组合区隔记忆存储,共 4 种方案:
| 区隔维度 | 适用场景 | 效果 |
|---|---|---|
| 不区隔 | 希望所有智能体、所有角色共享同一份用户画像 | 全部共用一份记忆 |
| 仅按智能体区隔 | 多智能体、场景差异大,但同一智能体内的角色需共享记忆 | 每个智能体一份独立记忆,智能体内的角色共享 |
| 仅按角色区隔 | 以角色(IP 形象)为主要区分维度 | 每个角色一份独立记忆,跨智能体的同一角色共享 |
| 按智能体 + 角色区隔 | 智能体与角色都需要完全独立的人格 | 每个「智能体 + 角色」组合一份独立记忆,隔离粒度最细 |
⚠ 不同的记忆配置方案会产生不同的记忆存储,他们之间并不互通,请谨慎修改。
记忆配置在产品维度统一设置,调整后请同步评估对线上存量用户的影响。

9. Q&A
Q1:角色和智能体是什么关系? A:角色是智能体的下一层级。智能体负责「能做什么」(技能、指令、交互策略、MCP 服务),角色负责「用什么性格、什么声音说」(人设 + 音色)。一个产品下可以有多个智能体,一个智能体可以勾选多个角色。
Q2:角色库是智能体维度还是产品维度? A:产品维度。角色统一维护在产品的角色库中,产品下的每个智能体从角色库中勾选自己要启用的角色,不能勾选其他产品的角色。
Q3:一个产品可以建几个智能体? A:最多 10 个,含默认智能体。默认智能体有且仅有一个,不可删除,可以切换到其他智能体。
Q4:为什么非默认智能体改不了 AIoT 指令? A:AIoT 指令的编辑入口统一收口在默认智能体。其他智能体可以看到已有的 AIoT 指令,并对其做「开 / 关」,但不能新增或编辑指令内容。
Q5:切换默认智能体会发生什么? A:三点变化:① 原默认智能体的 AIoT 指令配置会自动迁移到新的默认智能体,编辑权限随之转移;② 存量设备需重新建联才生效;③ 已注册设备的设备音色不会被修改。
Q6:产品刚创建时有智能体和角色吗? A:有。产品创建时系统自动生成 1 个默认智能体,并为其自动创建 1 个默认角色,原有的人设与音色配置即落在这个默认角色上。
Q7:可以建多少个角色?角色名有限制吗? A:新建数量不限;角色名称长度 ≤ 10 个字符。
Q8:为什么有的角色删不掉? A:两类角色不可删除:已关联智能体的角色(请先在智能体中取消勾选)和各智能体的默认角色。删除角色属于不可逆操作,需二次确认。
Q9:端侧不传 role_code 会用哪个角色? A:未传 role_code 时,所有产品均使用设备音色。角色分两种情况:① 传了 Agent ID → 运营平台的产品使用该智能体的默认角色,支撑平台创建的产品使用 App 绑定的角色列表中的第一个角色;② Agent ID 也没传 → 使用「默认智能体的默认角色」。详见 §7.1 智能体与角色的生效规则。
Q10:上行的 role_code 不属于所传 Agent ID,会报错吗? A:不会。平台不校验 role_code 与 Agent ID 的关联关系,一律按上行值生效:智能体取所传 Agent ID,人设与音色取所传 role_code。
Q11:人设修改后,是否需要重新发布才能生效? A:是的。修改后需点击「发布」才正式生效。只点「保存草稿」时,修改仅在调试窗可见,不影响线上设备。
Q12:人设会拼接到所有技能中吗?包括自定义技能? A:是的,生效角色的人设会自动拼接到生效智能体下所有技能(系统技能 + 自定义技能)的 prompt 头部。
Q13:人设可以写多长?有字数限制吗? A:平台暂无硬性字数上限,但建议控制在 300-800 字。过长可能导致模型对核心设定的遵循度下降,且占用上下文窗口。
Q14:能在调试窗里测试角色切换功能吗? A:不能。调试窗无法测试角色切换功能——即无法通过对话或上行 role_code 观察角色实时切换。如果需要测试不同角色的对话效果,需要在调试窗设置中切换智能体与角色(「预览调试」→「设备连接」),每次切换后分别对话验证。详见 §7.2 调试窗切换智能体与角色。