主题
7.1 外部智能体接入
当JoyInside 系统内置技能（如闲聊、天气查询等）不够用，需要接入企业自己的智能体Agent时，可以通过「自定义技能 + A2A 协议」方式实现。
A2A 协议适用于：接入企业自有智能体Agent、复杂智能体整体接入、有声书三方内容流式输出等迁移场景（见 第2章 §2.5）。
本章节重点说明：第三方服务型自定义技能，怎样注册第三方服务、配置技能准入、采用 A2A 流式协议对接企业自有智能体Agent。
7.1.1 智能体选择与接入
JoyInside 智能体分两类：系统内置技能（勾选即用） 与 自定义技能（三方扩展）。
技能接入交互时序
系统内置技能
系统内置技能，是平台预置的标准能力（如闲聊、天气查询等），企业可直接勾选使用，支持对部分技能配置微调。
应用配置添加系统技能，在用户语音系统交互过程中，平台识别到对应意图后，会自动执行相应的系统内置技能。
配置入口：应用管理 → 应用配置详情 → 关联系统技能
自定义技能
自定义技能，包括两种类型方式定义，分别是提示词型自定义技能、第三方服务型自定义技能。
提示词型自定义技能： 仅需定义技能准入描述等提示词、知识库等相关配置，无需依赖第三方接口服务，即可完成自定义技能。
配置入口：资源管理 → 技能库 → 提示词描述
第三方服务型自定义技能： 允许企业自定义扩展第三方服务技能，下面章节将重点说明该类型自定义技能接入步骤。
接入步骤
7.1.2 注册第三方服务
在创建第三方服务型自定义技能前，必须先在「开发者中心」完成 API 注册与授权：
| 步骤 | 要点 |
|---|---|
| 填写基础信息 | API 名称（仅字母/数字/下划线，最多 20 字符，不支持中文）；私网连接（公网服务保持默认"不使用"）；技能 URL（后端完整接口地址） |
| 配置 Header | 按需新增 Header 字段（Key/Value） |
| 配置鉴权 | 固定 Service Token（目前仅支持这一种）；选 Token 放 Header 还是 Query；填系统生成的鉴权密钥 |
| 保存校验与启用 | 保存并校验后，回列表页把状态开关拨到"启"才能被技能选用 |
⚠ 安全保护：已被技能库关联的 API 不允许直接删除。
⚠ 鉴权限制：目前平台仅支持 Service Token（访问令牌）这一种鉴权方式。
配置入口：开发者中心 → 第三方服务 → 新建 API
7.1.3 配置技能准入
API服务注册启用后，在「资源管理 > 技能库」新建技能，核心是技能准入描述（告诉 AI 什么情况下触发这个技能）：
| 配置项 | 说明 |
|---|---|
| 技能名称 | 易辨识，建议含动词，企业内唯一 |
| 技能准入描述 | 意图定义 + 标准触发条件 + 不可触发条件 + 正反例 |
| 关联服务 | 选择已注册启用的 API（下拉框） |
技能准入描述示例（爆款推荐）：
- 意图定义：用户明确希望获取当前热门商品、促销活动、购物榜单或要求推荐时触发
- 标准触发条件：用户明确表达求推荐、看爆款、看榜单的意图（例："今天有什么爆款""给我推荐点好东西"）
- 不可触发条件：
- 用户询问某一个具体商品（本技能不支持提取商品名称参数）——例："帮我查一下苹果 15 多少钱"
- 用户只是泛泛表达消费情绪，未明确要求推荐——例："我今天发工资了想花钱"
- 正反示例：正例 "请给我推荐点爆款商品吧"，反例 "今天天气怎么样"
明确的准入规则能有效降低技能的误识别率。通过提供对话示例（正例 / 反例），可辅助提升模型对特定技能的识别准确率。
配置入口：资源管理 → 技能库 → 技能准入描述
7.1.4 关联自定义智能体
在应用详情页中，选择自定义技能，完成自定义意图和自定义智能体的关联。当技能触发后，平台调用关联的外部第三方API服务，接口须以流式响应返回数据。
配置入口：应用管理 → 应用配置详情 → 关联自定义技能
7.1.5 实现 A2A 接口
接口定义
| 项目 | 说明 |
|---|---|
| 请求方式 | POST |
| 请求地址 | 示例：https://api.xxx.com/v1/workflow?workflow_id=xxxx |
| 接口说明 | 响应方式为流式响应，按需添加的 query 参数需拼接在请求地址中 |
接口入参定义
Header 参数（由接口方配置）
| 参数 | 取值 | 说明 |
|---|---|---|
| token 参数名（如 Authorization） | token 值（如 Bearer $Access_Token） | 用于验证客户端身份的访问令牌 |
| Content-Type | application/json | 解释请求正文的方式 |
Body 参数（平台自动填入）
以下参数由 JoyInside 平台方自动填入，接口方按需取用。这是 A2A 接口的核心入参，包含会话上下文。
| 字段 | 类型 | 说明 |
|---|---|---|
| request_id | String | 请求 ID |
| session_id | String | 会话 ID（关联短期记忆，见 4.3 重要参数介绍） |
| round_id | String | 轮次 ID（端到端排查主键） |
| bot_id | String | 设备 ID |
| app_id | String | 应用 ID |
| lang | String | 当前对话语种 |
| long_term_memory | String | 长期记忆内容 |
| messages | List<Conversation> | 历史消息，包含当前用户轮的 input |
| input | String | 用户 query（当前轮用户输入） |
| system_time | String | 当前时间，格式 yyyy-MM-dd HH:mm:00 |
| location | String | 地点 |
| rag_recall_result | String | 检索结果 |
| ext_info | Map | 透传 server 传递的 extInfo，是平台侧内部扩展定义参数。 如需此参数，联系JoyInside 运营团队开通权限&对接上行事件消息 CLIENT_UPDATE_CHAT_CONTEXT |
扩展ext_info应用时序：
Conversation结构：
plaintext
{
String role; // 角色 "user", "assistant"
String content; // 内容
}请求示例
bash
curl --location --request POST 'https://api.xxx.com/v1/workflow?workflow_id=12345' \
--header 'Authorization: Bearer pat_fhwefweuk****' \
--header 'Content-Type: application/json' \
--data-raw '{
"parameters": {
"bot_id": "122333444",
"input": "讲个小故事"
}
}'接口返回值定义
4类响应事件协议
接口返回数据时，须先返回
Message事件，再返回Instruction事件（如有），顺序不可乱。
通用响应结构：
| 参数名 | 参数类型 | 是否必选 | 说明 |
|---|---|---|---|
| id | Integer | 是 | 此消息在接口响应中的事件 ID，ID 值自定义，建议以 0 开始，处理消息时不校验 |
| event | String | 是 | 流式返回的数据包事件：Message、Instruction、Error、Done |
| data | Object | 是 | 事件内容，各 event 类型的 data 格式不同 |
- 事件 1：Message（输出消息内容）
| 参数名 | 参数类型 | 是否必选 | 说明 |
|---|---|---|---|
| content | String | 是 | 流式输出的消息内容，将输出到终端设备 |
| node_title | String | 否 | 输出消息的节点名称 |
| node_seq_id | String | 否 | 此消息在节点中的消息 ID，从 0 开始计数 |
| node_is_finish | Boolean | 否 | 当前消息是否为此节点的最后一个数据包 |
| node_id | String | 否 | 输出消息的节点 ID |
- 事件 2：Instruction（输出指令，透传终端）
data 结构自定义，data 内容将直接透传到终端设备。
- 事件 3：Error
| 参数名 | 参数类型 | 是否必选 | 说明 |
|---|---|---|---|
| error_code | Integer | 是 | 调用状态码：0 表示成功，其他值表示失败 |
| error_message | String | 是 | 错误信息 |
- 事件 4：Done（结束标志）
全部输出结束时必须发送该事件，data 为 {}。
计数与结束规则
- 事件 ID(
id)默认从 0 开始计数，以包含event: Done的事件为结束标志 - Message 事件的消息 ID 从 0 开始计数，以包含
node_is_finish: true的事件为结束标志(可选)
流式响应时序
平台调用外部 API 后，接口须按 Message → Instruction(可选)→ Done 顺序流式返回:
Message 事件响应示例
plaintext
id: 0
event: Message
data: {"content":"msg","node_is_finish":false,"node_seq_id":"0","node_title":"Message"}
id: 1
event: Message
data: {"content":"为什么小明要带一把尺子去看电影？\n因","node_is_finish":false,"node_seq_id":"1"}
...
id: 4
event: Message
data: {"content":"坐不下！","node_is_finish":true,"node_seq_id":"4","node_title":"Message"}
id: 5
event: Done
data: {}Instruction 事件响应示例
plaintext
id: 0
event: Instruction
data: {...} // 自定义结构，透传至终端设备- Instruction事件，其
data结构自定义、直接透传到终端设备（不经平台指令集建模） - A2A 指令透传：外部智能体 → 流式
Instruction事件 →data透传终端
Error 事件响应示例
plaintext
id: 0
event: Error
data: {"error_code":4000,"error_message":"Request parameter error"}下一步
- 迁移场景：读 第2章 §2.5 —— 4 种迁移模式都依赖 外部智能体接入
- IOT 指令详解：读 6.1 指令与控制 —— 分步配置指南 + 批量测试
- 有声书三方内容：读 7.2 外部媒体资源接入 —— 三方内容资源对接