主题
技能库 - 自定义技能
和 系统技能 并列的一类技能。 系统技能由平台内置(查天气、闲聊、AIoT 指令控制…),自定义技能由企业自己创建、只对本企业可见,用来定义品牌方专属的对话能力——既可以接入企业已有的后台服务(会员系统、售后系统、设备接口…),也可以只用一段提示词让平台内置大模型直接完成回复。
1. 什么是自定义技能
除了平台提供的系统技能,JoyInside 支持您创建专属于自己品牌的技能。
典型例子:
- 写提示词就能上线的技能: 为陪伴玩具创建一个「情感安慰」技能,只需编写一段提示词描述"温柔共情、100 字以内",触发后由平台内置大模型直接生成回复,无需任何后端开发。
- 接后端服务的技能: 为智能设备创建一个「查询会员积分」技能——用户问"我还有多少积分",AI 识别后调用您的会员系统接口返回积分余额。
关键特性:
- 企业隔离: 自定义技能仅对您的企业账号可见,不影响其他企业
- 需启用才生效: 创建后需要在「产品管理 - 技能配置」中勾选启用,才会在对应智能体中生效
- 两种技能类型: 根据您的业务是"轻量场景 / 角色扮演"还是"接入后端服务",可选择「自定义提示词型」或「第三方服务型」(见 §2)
2. 核心概念:技能类型
创建自定义技能时,首先要选择技能类型——这决定了这个技能如何被执行、需要填写哪些字段。
| 技能类型 | 谁来生成回复 | 是否需要后端开发 | 典型场景 |
|---|---|---|---|
| 自定义提示词型(默认) | 平台内置大模型,按您写的提示词生成 | 否,只需写提示词 | 角色扮演、故事续写、情感安慰、风格化问答等轻量、创意、语义驱动的场景 |
| 第三方服务型 | 外部 Agent 直接回复(平台调用您注册的 Agent API,原样返回,不再过大模型) | 是,需先在开发者中心注册外部 Agent 的 API | 查会员积分、查保修、下单、设备指令透传等由品牌方 Agent 自行处理的场景 |
2.1 两种类型的核心差异
| 维度 | 自定义提示词型 | 第三方服务型 |
|---|---|---|
| 执行方式 | 平台内置大模型直接推理生成 | 转发到外部 Agent 的 API,由 Agent 直接返回回复(不再过大模型二次组织) |
| 意图识别 | 基于「技能准入描述 + 示例」进行意图匹配(两者相同) | 基于「技能准入描述 + 示例」进行意图匹配(两者相同) |
| 触发方式 | 仅支持意图触发 | 支持意图触发和优先触发两种 |
| 专属配置 | 技能提示词、拼接全局人设、系统变量、关联知识库 | 第三方服务选择 |
| 典型能力 | 情感陪伴、角色扮演、故事讲解、风格化闲聊 | 会员积分、售后查询、设备下单、指令透传 |
⚠ 类型创建后不可修改。 技能创建成功后,「技能类型」字段在编辑页面锁定不可变更;若需切换类型,只能删除后重建。这是为了防止执行逻辑与配置数据发生冲突。
2.2 本期约束与边界
| 约束项 | 说明 |
|---|---|
| 不支持混合模式 | 一个技能只能是自定义提示词型或第三方服务型,不支持同时写提示词又挂第三方接口 |
| 提示词型不支持槽位提取 | 提示词型仅做「意图触发 + 提示词驱动回复」,本期不做结构化参数(slot)提取 |
| 提示词长度上限 | 技能提示词最多 7000 字符(与系统技能闲聊的提示词上限对齐) |
3. 自定义提示词型
核心机制: 命中意图后,平台把您编写的「技能提示词」拼装进大模型上下文,由平台内置模型直接生成自然语言回复,全程不调用任何外部接口。适合角色扮演、情感陪伴、故事续写等语义驱动的技能。
3.1 公共字段(所有自定义技能都要填)
| 字段 | 是否必填 | 字数限制 | 说明 |
|---|---|---|---|
| 技能名称 | 是 | ≤ 20 字符,企业内唯一 | 简短清晰地描述技能功能,如"情感安慰""睡前故事" |
| 技能准入描述 | 是 | ≤ 2000 字符 | 告诉 AI "什么情况下应该触发这个技能"(意图定义 / 标准触发 / 不可触发) |
| 示例 | 是 | ≤ 1000 字符 | 正反例 Few-shot,辅助模型判断意图边界 |
| 技能类型 | 是 | 单选,创建后不可改 | 本节场景固定为「自定义提示词型」 |
技能准入描述与示例的撰写建议,详见 §5「意图识别配置指引」。
3.2 自定义提示词型专属字段
| 字段 | 是否必填 | 说明 | 限制 |
|---|---|---|---|
| 技能提示词 | 是 | 技能命中后,大模型用于生成回复的核心 Prompt。定义该技能"做什么、怎么做" | ≤ 7000 字符 |
| 自动拼接全局人设 | 否 | 勾选后,系统在执行时自动把全局人设 Prompt 拼接到技能提示词头部,保持人设一致性 | 默认勾选 |
| 插入系统变量 | 否 | 支持在提示词中插入 ${systemTime}、${location} 等系统变量,由平台在运行时自动替换为实际值 | 语法同系统技能编辑能力 |
| 关联知识库 | 否 | 挂载企业知识库,配置召回数量与匹配阈值,让大模型在回复前先检索知识库 | 语法同系统技能「闲聊」的知识库关联能力 |
3.3 技能提示词撰写建议
一段好的技能提示词通常包含 4 部分:
- 明确角色:你是一位 XXX(如"专业营养师""温柔的故事讲述者")
- 定义任务:当用户 XXX 时,你需要 XXX
- 约束输出:回复控制在 XXX 字以内,语气保持 XXX
- 补充规则:不可以 XXX、必须 XXX
示例:「儿童睡前故事」技能提示词
你是一位儿童睡前故事讲述者。当用户说"讲个故事"或提到一个主题时,请根据主题即兴创作一个 3-5 句话的短故事,语气温柔、节奏舒缓,适合 3-6 岁儿童。故事结尾需引导孩子入睡,如"月亮也困了,我们一起闭上眼睛吧"。当前时间是 ${systemTime},可根据早晚气氛调整用词。3.4 触发方式限定 —— 仅意图触发
自定义提示词型只能选择「意图触发」,不支持「优先触发」。
原因: 提示词型的定位是"AI 理解用户意图后再进入",没有精准的指令词直连关系;优先触发则要求"用户所有输入 100% 先给该技能",两者不匹配。
流程:
用户说话
↓
AI 意图识别(基于准入描述 + 示例)
↓
命中提示词型技能
↓
拼装:[全局人设(可选)] + [技能提示词] + [知识库检索结果(可选)] + [系统变量替换]
↓
平台内置大模型直接生成自然语言回复
↓
TTS 输出给用户3.5 与「全局人设」「事件反馈」的关系
| 场景 | 变量注入方 | 语法 | 说明 |
|---|---|---|---|
| 自定义提示词技能 | 平台内置自动注入 | ${systemTime}、${location} | 系统内置变量,运行时平台自动替换 |
| 事件反馈 | 端侧通过 CLIENT_UPDATE_CHAT_CONTEXT 上报 | ${(extInfo.字段名)!""} | 由端侧上报后再注入 Prompt |
| A2A 调用透传 | 集成侧调用时传入 | 详见开放接口 ext_info 字段 | A2A 接口调用生效 |
📌 注意区分:自定义提示词技能里的
${systemTime}/${location}是系统内置变量,无需端侧上报;而事件反馈里的${(extInfo.xxx)!""}是端侧上报的业务字段,两者机制不同,不要混用。
4. 第三方服务型
核心机制: 命中意图后,平台把请求转发到您在开发者中心注册的外部 Agent 的 API(即「第三方服务」),由 Agent 自行处理并直接返回自然语言回复,平台不再过大模型做二次组织,拿到什么回什么(仅做必要的通道透传与格式适配)。适合需要由业务方 Agent 自行执行并组织话术的技能(如查会员积分、查保修、下单、设备指令透传)。
4.1 公共字段
同 §3.1(所有自定义技能都要填的字段一致)。
4.2 第三方服务型专属字段
| 字段 | 是否必填 | 说明 |
|---|---|---|
| 第三方服务选择 | 是 | 从「开发者中心 · 第三方服务管理」已注册且启用的 API 列表中选择 |
术语澄清:「第三方服务」在平台语境里本质是外部 Agent 的 API,双方按 A2A(Agent-to-Agent)协议通信。技能命中后,平台把用户输入 + 会话上下文 + 长短期记忆 + RAG 结果打包透传给该 Agent,Agent 以流式响应直接返回可播报的自然语言回复,平台原样透传给端侧,不再调用大模型做二次改写、总结或润色。协议细节见 A2A 流式响应协议(6.6.5)。
平台侧 ↔ Agent 侧职责边界:
| 谁负责 | 具体职责 |
|---|---|
| 平台侧 | 通道透传、鉴权、超时、限流、格式适配;把 input/messages/session_id/long_term_memory/rag_recall_result/ext_info 等打包 POST 给 Agent |
| Agent 侧 | ① 自己组织好话术(长度、语气、TTS 友好度);② 按 A2A 协议流式返回 4 类事件(Message → Instruction 可选 → Done;失败发 Error);③ 自己处理失败降级(只有 Agent 明确返回失败时,平台才会回落到其他技能) |
Agent 侧必须遵守的 A2A 协议核心约束(简介):
- 必须流式:HTTP 流式响应,不能一次性返回整块 JSON;
- 事件顺序:
Message(输出内容) →Instruction(可选,自定义结构,直接透传终端) →Done(结束标志,data: {}); - 失败处理:异常时发
Error事件(含error_code/error_message); - Done 必须发:平台以
Done事件作为整轮结束标志,漏发会导致端侧超时。
完整字段定义、请求示例、Message/Instruction/Error/Done 结构见 §6.6 A2A 技能协议。
4.3 触发方式(意图触发 / 优先触发,二选一)
第三方服务型支持两种触发方式,决定"AI 什么时候把用户的话交给这个技能":
| 触发方式 | 说明 | 适用场景 |
|---|---|---|
| 意图触发 | AI 先理解用户意图,判断"用户想做什么",再决定是否进入该技能 | 大多数场景。例如「查积分」「查保修」等需要 AI 理解语义的技能 |
| 优先触发 | 用户的每一句话 100% 先分给该技能处理,不经过 AI 意图判断;只有当该技能返回失败时,才会继续走其他技能的正常流程 | 品牌方已有成熟服务系统,希望优先使用自家服务响应,自己搞不定时再交给平台其他技能兜底 |
简单理解:
- 意图触发 = AI 先"想一想"用户在说什么,再决定交给谁处理
- 优先触发 = 所有用户输入 100% 先给该技能,处理不了再兜底给其他技能
4.3.1 优先触发的典型场景
某品牌已经有一套完善的智能客服系统,能处理大部分用户问题。选择「优先触发」后:
用户说话
↓
优先调用品牌自有客服接口
↓
┌─ 品牌接口成功响应 → 直接返回结果给用户
└─ 品牌接口无法处理(返回失败)
↓
自动流转到平台其他技能(闲聊、查天气…)兜底这样既能发挥品牌方已有服务的优势,又能借助平台能力做兜底,不会让用户"问了没人答"。
⚠ 优先触发意味着所有用户输入 100% 都会先经过该技能,不做 AI 意图判断。请确保您关联的第三方服务能在处理不了时正确返回失败状态,以便系统将请求顺利流转到其他技能。
4.3.2 意图触发 vs 优先触发的字段差异
| 配置项 | 意图触发 | 优先触发 |
|---|---|---|
| 技能名称 | 必填 | 必填 |
| 技能准入描述 | 必填 | 不必填(优先触发跳过意图判断) |
| 示例 | 必填 | 不必填 |
| 第三方服务选择 | 必填 | 必填 |
4.4 关联第三方服务
第三方服务需要提前在开发者中心 → 第三方服务中创建。创建后的第三方服务会出现在技能配置的「第三方服务选择」下拉列表中,供技能关联使用。
第三方服务的详细创建方法,请参见「开发者中心 · 第三方服务管理」说明。
5. 意图识别配置指引(两种类型通用)
「技能准入描述」和「示例」是意图识别的核心输入,不管选哪种技能类型,都建议按下述方法撰写。
5.1 技能准入描述撰写建议
一个好的准入描述应该包含三部分:
- 意图定义: 这个技能是做什么的
- 标准触发条件: 什么样的用户表述应该触发
- 不可触发条件: 什么情况不应该触发(避免误判)
示例:为「查会员积分」技能撰写准入描述
当用户明确表达查询自己的会员积分、余额、等级时,应进入该技能。
标准触发条件:
- 用户询问积分余额:如"我还有多少积分""查一下我的积分"
- 用户询问会员等级:如"我现在是什么级别""我的会员等级"
- 用户询问积分用途:如"积分能换什么""积分怎么用"
不可触发条件:
- 用户只是在闲聊中提到了"积分",但并非查询自己的信息,
如"积分制度是什么""你们的积分好不好用"
- 用户要求增加或修改积分,如"给我加点积分""我要兑换积分"5.2 示例撰写建议
提供正例(应该触发)和反例(不应该触发),帮助 AI 理解典型边界:
正例:
- "我有多少积分"
- "查一下余额"
- "我的会员等级是多少"
反例:
- "积分制度怎么回事" → 应走知识问答
- "帮我把积分用掉" → 应走闲聊或其他技能📌 经验值: 准入描述越精准、反例越充分,AI 判断意图的准确率越高,误触发越少。
6. 完整使用流程
6.1 自定义提示词型(轻量,无需后端开发)
1. 创建自定义技能(资源管理 → 技能库 → + 新建技能)
↓
2. 选择「自定义提示词型」→ 填写名称/准入描述/示例
↓
3. 撰写技能提示词(必填,最多 7000 字符)
↓
4. (可选)勾选拼接全局人设 / 插入系统变量 / 关联知识库
↓
5. 在智能体中启用(产品管理 → 智能体配置 → 勾选该技能)
↓
6. 用户对话时,AI 识别意图后自动进入,平台大模型按提示词生成回复6.2 第三方服务型(需接入后端 API)
1. 创建第三方服务(开发者中心 → 第三方服务 → 新建)
↓
2. 创建自定义技能(资源管理 → 技能库 → + 新建技能)
↓
3. 选择「第三方服务型」→ 选择触发方式 → 关联第三方服务
↓
4. 意图触发需填写准入描述与示例;优先触发无需填写
↓
5. 在智能体中启用(产品管理 → 智能体配置 → 勾选该技能)
↓
6. 用户对话时,AI 识别意图后触发,调用您的接口获取数据并组织回复7. 使用场景举例
| 场景 | 技能名称 | 技能类型 | 触发方式 | 说明 |
|---|---|---|---|---|
| 陪伴玩具情感陪伴 | 情感安慰 | 自定义提示词型 | 意图触发 | 用户表达负面情绪时,平台大模型按"温柔共情"提示词生成回复,无需后端 |
| 睡前故事讲解 | 睡前故事 | 自定义提示词型 | 意图触发 | 用户说"讲个故事",大模型按提示词即兴创作 3-5 句短故事 |
| 品牌角色扮演 | 皮卡丘互动 | 自定义提示词型 | 意图触发 | 大模型扮演特定 IP 角色,风格化回复,无需接口 |
| 用户查询会员信息 | 查会员积分 | 第三方服务型 | 意图触发 | 识别到用户询问积分/等级后,调用品牌方会员系统 API 返回结果 |
| 用户查询设备保修 | 查保修 | 第三方服务型 | 意图触发 | 用户问"我的设备还在保修期吗"时触发,调用售后系统查询 |
| 硬件设备指令透传 | 设备指令透传 | 第三方服务型 | 优先触发 | 特定格式指令直接透传到您的 Agent,由 Agent 按 A2A 协议流式返回;Instruction 事件的 data 结构自定义,直接透传到终端,不经平台大模型改写、也不走系统指令集建模 |
8. 注意事项
- 技能类型创建后不可修改: 需切换类型只能删除后重建
- 提示词型必须写提示词: 提示词是提示词型技能的执行核心,不填等于"空壳技能"
- 提示词型走平台默认模型: 生成质量与平台内置模型能力相关,复杂业务逻辑请选第三方服务型
- 知识库为选填增强: 提示词型可以不挂知识库,只用提示词也能工作;挂知识库后大模型会先检索再生成
- 准入描述越精准越好: 描述越清晰、边界越明确,AI 判断意图的准确率越高
- 善用反例: 在示例中加入"不应该触发"的反例,能有效减少误触发
- 创建后记得启用: 技能创建完成后,需要到「产品管理 - 技能配置」中勾选,才会在对应智能体中生效
- 仅企业内可见: 自定义技能只有您的企业账号下可见和使用,不会影响其他企业
9. 与系统技能的关系
| 维度 | 系统技能 | 自定义技能(本篇) |
|---|---|---|
| 谁提供 | 平台内置 | 企业自己创建 |
| 可见范围 | 所有企业 | 仅本企业 |
| 是否需要接后端 | 否(部分需硬件适配) | 提示词型:否;服务型:是 |
| 触发方式 | 平台调度(意图 + 兜底) | 提示词型:仅意图触发;服务型:意图 / 优先二选一 |
| 典型场景 | 查天气、闲聊、AIoT 指令、视觉问答… | 提示词型:情感安慰、故事讲解、角色扮演;服务型:查积分、查保修、设备透传… |
共存关系: 一个应用可以同时启用系统技能和自定义技能;当自定义技能选择「优先触发」时(仅服务型可选),它会排在所有系统技能之前;其他情况下与系统技能一起参与 AI 意图路由。