主题
第三方服务管理
当您创建了 自定义技能 且选择「第三方服务型」时,技能被触发后需要调用**您自己的智能体(Agent)**来处理业务(如查会员积分、订单状态、售后查询、设备指令透传等)。在这里注册您的 Agent 接口信息,让平台知道:调用哪个地址、怎么鉴权、按什么协议交互。
简单来说:第三方服务 = 您的外部 Agent 在平台的"注册档案"。技能命中后,平台把用户输入 + 会话上下文 + 记忆 + RAG 结果打包透传给您的 Agent,由 Agent 以流式响应直接返回可播报的回复,平台原样透传到端侧,不再过大模型二次组织。
技术侧接口规范请参见 A2A 协议(Agent-to-Agent)。
1. 在整体链路中的位置
用户对话 ──▶ JoyInside 平台
│
│ 命中「第三方服务型」自定义技能
▼
查找该技能绑定的第三方服务(即外部 Agent)
│
│ 平台按 A2A 协议 POST(input/messages/session/RAG/记忆…)
▼
外部 Agent 处理
│
│ Agent 流式返回:Message → Instruction(可选) → Done
▼
平台原样透传到端侧(不做大模型二次改写)
│
▼
端侧 TTS 播报 / 执行指令平台侧只做通道透传、鉴权、超时、限流、格式适配;回复内容 = Agent 直接输出,平台不再调用大模型润色、总结或改写。
2. 配置规则(硬约束)
- 鉴权方式固定为 Service Token:平台不支持其他鉴权类型(如 Basic Auth / OAuth);
- Service Token 位置支持 Header 或 Query 两种:注册时二选一,与您 Agent 后端约定一致即可;
- Agent 侧必须返回流式响应:接口须按 A2A 协议流式输出,顺序为
Message → Instruction(可选) → Done,四类事件详见 A2A 协议(6.6.5); - 服务必须启用才能被技能库关联:禁用状态下,在自定义技能新建页的下拉框中不可见;
- 服务名称仅允许字母/数字/下划线:不能有空格或特殊符号,上限 20 字符。
3. 新建第三方服务
点击「+ 新建第三方服务」,需要填写:
| 配置项 | 是否必填 | 说明 |
|---|---|---|
| 第三方服务名称 | 必填 | 只能包含字母、数字和下划线,不能有空格或特殊符号(上限 20 字符) |
| 私网连接 | 必填 | 选择是否使用私网连接(默认「不使用私网连接」) |
| 技能 URL | 必填 | 您的接口地址,如 https://api.example.com/v1/data |
| Header 列表 | 选填 | 需要附带的请求头信息,可添加多组 Key-Value |
| 授权方式 | 必填 | 固定为 Service Token |
| 参数位置 | 必填 | 鉴权参数放在哪里:Header(请求头)或 Query(地址参数) |
| Parameter Name | 必填 | 鉴权参数的名称(如 Authorization) |
| Service Token | 必填 | 您的服务令牌值 |
填写完成后点击「保存并校验」,平台会尝试连接您的接口进行验证。
校验不通过无法保存
校验会实际发起一次探测请求。请确保接口地址可达、鉴权参数正确,否则无法完成注册。
4. 配置示例
假设您有一个会员积分查询接口:
| 配置项 | 值 |
|---|---|
| 服务名称 | member_points_query |
| 私网连接 | 不使用私网连接 |
| 技能 URL | https://api.yourbrand.com/v1/member/points |
| Header 列表 | User-Agent = YourBrandBot/1.0 |
| 授权方式 | Service Token |
| 参数位置 | Header |
| Parameter Name | Authorization |
| Service Token | Bearer your-token-here |
配置完成并启用后,在「技能库 → 新建自定义技能」时,就能在**「第三方服务选择」下拉**中看到这个服务。
5. 私网连接何时使用
| 部署形态 | 私网连接选项 |
|---|---|
| 接口部署在公网(可通过公网 URL 访问) | 「不使用私网连接」 |
| 接口部署在京东内网/私有网络 | 选择对应的私网连接方式 |
私网连接的部署背景
私网连接主要用于内网接口不暴露公网的场景。若您的服务已在公网可达(如公有云 API 网关),直接选「不使用私网连接」即可。
6. 注意事项
- 先创建第三方服务,再创建自定义技能:技能配置时需要选择已有的第三方服务,顺序不能反;
- 服务必须启用才能被关联:新建后如果处于禁用状态,在技能库中是看不到的;
- 校验不通过无法保存:请确保接口地址可正常访问、鉴权信息正确;
- 服务名称命名规范:只允许字母、数字和下划线,建议使用有意义的英文命名(如
order_query、member_info); - 一个技能对应一个服务:自定义技能与第三方服务是绑定关系,若接口地址变更需修改此处配置而非在技能侧维护。
7. 常见 Q&A
Q1:接口 URL 支持路径参数吗?比如 /order/{orderId}
A:不需要在 URL 上做路径参数拼接。平台按 A2A 协议 把用户原始 query(input)+ 历史消息(messages)+ 会话上下文(session_id/round_id/bot_id/app_id)+ 长短期记忆 + RAG 结果都放在 Body 里 POST 给您的 Agent,由 Agent 侧自己解析业务实体。若 Agent 是 Coze / 扣子 等工作流平台,可通过 URL 上的 workflow_id=xxx 之类的 query 参数指定工作流(参见 A2A 协议请求示例)。
Q2:Service Token 会过期吗?
A:平台侧不主动过期,过期策略取决于您的后端签发逻辑。若您的 Token 有过期机制,建议:
- 使用长期有效的 Token,或
- 在您的服务端做 Token 自动刷新,不要频繁改本页的注册值。
Q3:同一个 Agent 能被多个技能共用吗?
A:可以。一个第三方服务(即一个已注册的 Agent)注册后,可以被多个自定义技能绑定复用,无需重复注册。
Q4:调用失败,如何排查?
A:优先级从高到低:
- 服务状态:是否处于「启用」;
- 接口连通性:平台侧网络能否访问您的 Agent URL(公网 vs 私网);
- 鉴权配置:参数位置(Header / Query)、参数名、Token 值是否与您 Agent 后端约定一致;
- 响应协议:您的 Agent 返回是否满足 A2A 流式响应协议 —— 事件顺序
Message → Instruction(可选) → Done、Done必须发送、Message 事件的content字段是要输出到端侧的文本。