Skip to content

智能体和角色管理 ​

本章回答五个问题:为什么需要多智能体、怎么管理智能体、一个角色由什么构成、怎么切换智能体与角色、怎么隔离记忆。

  • 智能体:产品之下的一层配置单元,决定「能做什么」(技能、指令、交互策略、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 识别结果或用户输入进行随动变化时,可开启语种配置。

设置步骤 ​

  1. 在角色配置区找到需要设置的角色,开启「语种配置」开关;

    语种配置入口

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

    语种配置弹窗

  3. 选择对应语种,按角色配置流程进行调试、保存与发布。

支持范围 ​

项目当前支持范围
语种选项普通话-中文、粤语、英语
支持技能闲聊、自定义闲聊、查时间、查天气

注:如需支持更多语种或更多系统技能,请联系 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 调试窗切换智能体与角色。

下一步 ​