快速开始

本文将介绍如何通过 EMQX Broker、MCP Bridge 和在线设备模拟，快速完成一个硬件语音智能体的创建与验证。

本文以下步骤以 EMQX Broker 专有版为例进行说明。

如果您还没有开通硬件语音智能体部署，可先参考创建和管理硬件语音智能体部署 完成申请和创建。

前置准备

在开始前，请先确认以下条件：

1. 您已创建 EMQX Broker 专有版，并联系技术支持为您配置 MCP Bridge。
2. 您已创建硬件语音智能体部署。

为避免混淆，建议在操作前先区分以下三类连接信息和凭证：

类型	用途
Broker 连接地址	用于 Agent 和在线设备模拟连接 MQTT / WebSocket 服务
API Key / Secret Key	用于智能体访问 EMQX 的 MCP 服务
MQTT 用户名 / 密码	用于 Broker 客户端认证

步骤 1：准备 EMQX Broker 与 MCP Bridge

在 EMQX Broker 专有版中完成以下准备工作：

1. 进入目标 Broker 的概览页面，记录部署连接信息。 您需要获取以下内容：
   • Broker 地址
   • MQTT 的 TLS 端口
   • WebSocket 的 TLS 端口
   • API 地址
   • MCP Bridge 的 Streamable HTTP 地址和 SSE 地址（Broker 专有版示例）：
     • MCP：{API 地址}/agent/mcp
     • SSE：{API 地址}/agent/sse
2. 在部署概览页面中创建一组 API Key 和 Secret Key，用于智能体访问 EMQX 的 MCP 服务。 创建 API Key 时，请选择智能体权限，并勾选以下 8 个 API 权限：
   • GET /agent/mcp
   • POST /agent/mcp
   • PUT /agent/mcp
   • DELETE /agent/mcp
   • GET /agent/sse
   • POST /agent/sse
   • PUT /agent/sse
   • DELETE /agent/sse
3. 在左侧菜单中进入访问控制 > 客户端认证，为后续 Agent 和在线设备模拟配置默认用户名和密码。

完成上述配置后，您就具备了创建 Agent 所需的 Broker 地址、API 凭证和客户端认证信息。

步骤 2：创建硬件语音智能体 Agent

1. 进入硬件语音智能体部署的部署概览页面，点击进入 Dashboard。

2. 在 Dashboard 中点击创建 Agent。

3. 在弹出的 Agent 类型选择窗口中，选择单设备 Agent。

4. 在基本信息区域填写以下内容：

   • Agent ID
   • 名称
   • 系统提示词
   • 声音
   • 欢迎消息

5. 在EMQX 连接配置区域中，选择对应的 EMQX 部署实例。

   如需补充部署实例的连接信息，点击实例选择框右侧的齿轮按钮，在实例管理页面中编辑填写：

   • MQTT Broker 地址
   • WebSocket 地址
   • API 地址
   • MCP Bridge 地址
   • API Key 和 Secret Key
   

6. 返回 Agent 创建页面后，继续填写用户名和密码。这里使用的就是 Broker 中访问控制 > 客户端认证创建的认证信息。

7. 创建 Agent 后，继续为 Agent 配置 MCP 工具。点击添加工具，填写以下信息：

   • 工具名称和描述
   • 传输类型：选择 Streamable HTTP
   • 端点：选择 EMQX MCP，并填写 MCP Bridge 地址
   • 保持工具处于已启用状态。

   点击保存完成添加。

   

8. 点击保存完成 Agent 创建。

步骤 4：在线设备模拟与验证

完成 Agent 和 MCP 工具配置后，可以通过在线设备模拟验证控制流程。

1. 返回 Agent 列表，点击目标 Agent 右侧的在线设备模拟。
2. 在右侧工具区域点击添加工具。
3. 在工具类型中选择灯，确认工具名称和描述后点击保存。
4. 点击页面右上角的齿轮按钮，打开连接配置。
5. 在连接配置中填写以下信息：
   • EMQX 服务器地址：填写 Broker 的 WSS 地址
   • 客户端 ID
   • 用户名
   • 密码
6. 点击测试连接。看到“连接测试成功”后，点击保存并连接。
7. 在聊天输入框中发送“开灯”。
8. 观察右侧工具面板中灯的状态变化，确认其显示为已开，即表示 Agent 已经通过 MCP 工具完成设备控制。

下一步

完成上述步骤后，您已经验证了硬件语音智能体与 EMQX Broker、MCP Bridge 以及在线设备模拟之间的基本联动流程。

后续您可以继续：

• 查看部署信息和运行状态。
• 接入真实硬件设备，替换在线设备模拟环境。
• 为 Agent 扩展更多 MCP 工具，以支持更丰富的设备控制和业务集成能力。