EMQX Cloud

简体中文

English
日本語

简体中文

English
日本語

Appearance

联系我们

客户端 - 智能体通信协议 ​

本文档定义设备客户端与智能体之间基于 MQTT 的通信协议，消息体采用 JSON-RPC 2.0 格式。

主题约定 ​

订阅主题过滤器 ​

客户端需订阅：

  • $agent-client/{clientId}/#：接收定向发送给该客户端的消息。

智能体需订阅：

  • $agent/{agentId}/#：接收定向发送给该智能体的消息。
  • 智能体配置的所有数据主题过滤器：接收设备数据上报消息。

发布主题 ​

  • 客户端 -> 智能体：$agent/{agentId}/{clientId}
  • 智能体 -> 客户端：$agent-client/{clientId}/{agentId}
  • 设备数据上报主题：必须且只能匹配智能体已配置的数据主题过滤器之一。

会话管理 ​

初始化会话 ​

客户端上线后，需向智能体发送初始化会话请求，主题：$agent/{agentId}/{clientId}。

json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initializeSession",
    "params": {}
}

智能体回复客户端，主题：$agent-client/{clientId}/{agentId}。

json
{
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
        "status": "sessionInitialized"
    }
}

清理会话 ​

当客户端不再使用智能体时，应向智能体发送清理会话消息，主题：$agent/{agentId}/{clientId}。

json
{
    "jsonrpc": "2.0",
    "method": "destroySession",
    "params": {}
}

收到 destroySession 后，智能体会清理语音连接、大模型对话上下文等资源。

智能体也可主动发起清理会话，向客户端发送相同格式消息，主题：$agent-client/{clientId}/{agentId}。

文本消息 ​

客户端向智能体发送文本消息，主题：$agent/{agentId}/{clientId}。

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

智能体以增量方式回复，主题：$agent-client/{clientId}/{agentId}。

json
{
    "jsonrpc": "2.0",
    "method": "textTalkDelta",
    "params": {
        "taskId": "abc",
        "textDelta": "xxx"
    }
}
json
{
    "jsonrpc": "2.0",
    "method": "textTalkFinished",
    "params": {
        "taskId": "abc"
    }
}

语音消息 ​

客户端向智能体（$agent/{agentId}/{clientId}）或智能体向客户端（$agent-client/{clientId}/{agentId}）发送语音片段消息。

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

设备数据上报 ​

设备必须将数据发布到预先配置的主题。数据格式理论上可扩展，但当前仅支持 JSON。

智能体启动后会订阅所有已配置的数据主题过滤器。由于主题中包含 deviceId，设备发布数据后，智能体可根据 deviceId 找到对应 clientId，并将数据转发至该 clientId 对应的智能体会话。

对于多设备智能体，clientId 与 deviceId 的映射关系属于业务逻辑范畴，可按以下方式实现：

  • 实现 GET https://hostname:port/getDeviceInfo?clientId=xxx HTTP 回调接口。
  • 在 SaaS 服务中直接添加和管理 clientId、deviceId 与 toolType（未来可能支持）。
  • 实现用户自定义的智能体。

对于单设备智能体，clientId 与 deviceId 相同，且 toolType 在创建智能体时已确定，因此无需额外实现设备信息获取逻辑。

语音会话 ​

发起语音会话 ​

客户端可在任意时刻向智能体发起语音会话请求，主题：$agent/{agentId}/{clientId}。

json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "startVoiceChat",
    "params": {}
}

智能体回复 ​

智能体回复客户端，主题：$agent-client/{clientId}/{agentId}。

json
{
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
        "taskId": "abc",
        "appId": "xxx",
        "roomId": "xxx",
        "token": "xxx",
        "userId": "xxx",
        "targetUserId": "xxxx"
    }
}

结束语音会话 ​

客户端可在任意时刻向智能体发送结束语音会话请求，主题：$agent/{agentId}/{clientId}。

json
{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "stopVoiceChat",
    "params": {}
}

智能体回复客户端，主题：$agent-client/{clientId}/{agentId}。

json
{
    "jsonrpc": "2.0",
    "id": "2",
    "result": {
        "taskId": "abc",
        "status": "voiceChatStopped"
    }
}

在任意时刻，智能体也可能向客户端发送语音会话结束通知，主题：$agent-client/{clientId}/{agentId}。

json
{
    "jsonrpc": "2.0",
    "method": "voiceChatStopped",
    "params": {
        "taskId": "abc"
    }
}