自定义智能体适配器协议

硬件语音平台支持用户自定义智能体，开发者可自行实现业务逻辑，以满足更复杂的应用场景。自定义智能体与硬件语音平台通过 WebSocket 进行消息交互，消息格式采用 JSON-RPC 2.0。

在创建智能体时，可选择“用户自定义智能体”类型，并填写自定义智能体的 WebSocket 服务地址（URL）。当平台收到客户端请求后，会将请求转发到该服务地址；自定义智能体处理完成后返回结果，再由平台转发给客户端。

协议约定

• clientId：客户端唯一标识（MQTT ClientID）。
• agentId：智能体唯一标识。
• 所有消息均为 JSON-RPC 2.0 格式。
• 消息体中不能包含换行符，且每条消息末尾需追加换行符 \n 作为消息结束标记。

初始化会话

会话由 clientId 和 agentId 联合标识。

当客户端向平台智能体发送初始化会话消息后，平台会在消息中补充 clientId 与 agentId 字段，并转发到自定义智能体，通知其准备接收该客户端请求。

{
    "jsonrpc": "2.0",
    "method": "initializeSession",
    "id": "1",
    "params": {
        "clientId": "xxx",
        "agentId": "xxx"
    }
}

自定义智能体收到初始化消息后，需返回会话初始化完成响应：

{
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
        "clientId": "xxx",
        "agentId": "xxx",
        "status": "sessionInitialized"
    }
}

清理会话资源

当客户端与平台智能体会话结束时，平台会向自定义智能体发送 destroySession 消息，通知其清理该会话相关资源。

{
    "jsonrpc": "2.0",
    "method": "destroySession",
    "params": {
        "clientId": "xxx",
        "agentId": "xxx"
    }
}

文本消息

客户端向平台智能体发送文本消息后，平台会在消息中补充 clientId 和 agentId 字段，并转发到自定义智能体服务地址。

{
    "jsonrpc": "2.0",
    "method": "textTalk",
    "params": {
        "clientId": "xxx",
        "agentId": "xxx",
        "taskId": "abc",
        "text": "xxx"
    }
}

自定义智能体可采用流式返回：先发送多个 textTalkDelta，最后发送一个 textTalkFinished。

{
    "jsonrpc": "2.0",
    "method": "textTalkDelta",
    "params": {
        "clientId": "xxx",
        "agentId": "xxx",
        "taskId": "abc",
        "textDelta": "xxx",
        "tts": false
    }
}

{
    "jsonrpc": "2.0",
    "method": "textTalkFinished",
    "params": {
        "clientId": "xxx",
        "agentId": "xxx",
        "taskId": "abc"
    }
}

其中，tts 字段表示是否将文本转换为语音并发送给客户端，默认值为 false。

即使未收到客户端请求，自定义智能体也可在任意时刻向平台发送文本消息，平台会将其转发给对应客户端，消息格式同上。

语音消息

在任意时刻，平台可能向自定义智能体转发来自客户端的语音消息；自定义智能体也可向平台发送相同格式的语音消息。

{
    "jsonrpc": "2.0",
    "method": "voiceTalk",
    "params": {
        "clientId": "xxx",
        "agentId": "xxx",
        "taskId": "abc",
        "audioEncoding": "pcm",
        "sampleRate": 16000,
        "audioBase64": "xxxx",
        "duration": 2023
    }
}

实现建议

建议自定义智能体实现过期会话清理机制，定期释放长时间未活动会话占用的资源，避免资源泄漏。