MQTTX Agent

MQTTX Agent 是内置于桌面客户端的 AI Agent，用于通过自然语言操作 MQTTX。按本文配置模型服务商、提供连接上下文，再执行 MQTT 任务并检查结果。

先完成服务商和权限设置，再按任务示例管理连接与消息、使用已提供的 MQTT 协议与设备交互、排查流量，或准备代码和消息处理逻辑。继续同一任务时，保留当前对话中的工具结果作为上下文。

配置模型服务商

1. 打开 设置 → MQTTX Agent，开启 启用 MQTTX Agent。
2. 填写服务商的 API Host、API Key 和 模型。执行 MQTTX 操作需要选择支持工具调用的模型。
3. 通过左侧栏的星形按钮打开 Agent。使用 Cmd/Ctrl + J，或连接页、脚本页的 MQTTX Agent 按钮，可打开浮窗并同时查看其他页面。
4. 先提交只读请求，例如“列出已有的 MQTTX 连接”，确认回复中出现工具结果。请求失败时，先检查服务商地址、凭据和模型的工具调用支持，再执行具体任务。

以下列出常用 API Host。具体地址和凭据以所用服务商提供的信息为准。

服务商	API Host
OpenAI	https://api.openai.com/v1
DeepSeek	https://api.deepseek.com/v1
Anthropic	https://api.anthropic.com/v1
xAI	https://api.x.ai/v1
Google	https://generativelanguage.googleapis.com/v1beta
SiliconFlow	https://api.siliconflow.cn/v1
Azure OpenAI	https://<resourceName>.openai.azure.com

选择使用方式

全屏适合集中处理较长对话，浮窗支持同时查看消息、脚本或 Dashboard。全屏对话打开后，保持活动的连接仍可接收并保存消息。

拖动浮窗标题栏可移动位置，拖动边缘或角可调整大小，MQTTX 会记住位置和大小。标题栏的展开按钮用于切换到全屏。按 Esc 关闭浮窗；全屏时按 Esc 返回浮窗。在左侧栏选择其他页面会退出全屏。

选择推理强度

在 设置 → MQTTX Agent → 推理强度 中选择模型支持的档位，或在输入框的模型菜单中、模型列表下方直接选择。

• 自动：由服务商决定。
• 关闭：不使用推理。
• 低至最高：逐步增加推理强度。

菜单只显示所选模型支持的档位。不支持调节推理强度的模型会隐藏这一项。如果新选择的模型不支持此前选定的档位，MQTTX 会使用最接近的可用档位。当前档位显示在模型名后面。

给 Agent 提供所需信息

提及连接

在输入框中输入 @，用 ↑ / ↓ 和 Enter 选择连接。正在查看的连接排在最前，已连接的条目带有绿点。Agent 会先读取被提及的连接，再处理请求。

提及连接可明确多个设备或 Broker 之间的操作对象。请求中还可包含待检查的主题、Payload 字段或预期结果。

选择 Skill

输入 /，可以选择客户端代码、测试数据、Schema 与编解码、自定义函数、MQTT/EMQX 知识、连接诊断、MQTTX CLI 或 Zero EMQX 等内置 Skill。Skill 为当前任务提供对应的知识与操作指引。

MQTTX CLI Skill 生成可由用户在终端执行的命令。桌面内置的 Agent 不执行 shell 命令。

生成的代码项目会显示为 ZIP 文件卡片，支持下载或在文件夹中显示。文件保存在应用数据目录下的 agent-files 中，删除会话时会一并删除。

添加截图或文件

粘贴截图、将文件拖入面板，或点击 📎，为请求补充相关信息。例如，提供需要解码的 Payload，或配置 TLS 连接需要使用的文件。

图片会发送给模型。文本文件以文本形式发送，超过 64 KB 的文件只发送前 64 KB。证书和私钥文件只以路径引用，文件内容不会发送给模型。Agent 可以使用这些路径配置 TLS：

使用 ca.crt 作为 CA、client.crt 作为客户端证书、client.key 作为私钥，连接到 broker.example.com 的 8883 端口。

查看并批准操作

执行任务前先选择权限模式，执行过程中检查工具步骤与结果。需要批准时，在请求卡片上允许或拒绝操作：

• 操作前询问为默认模式。读取操作自动执行；创建、连接、订阅、发布、删除、同步主题树、停止定时发布以及每次 MCP 工具调用都会等待批准。在请求卡片上选择允许一次、本次对话中始终允许这个工具或拒绝。
• 自动模式下，大多数操作无需批准。

删除、清空以及保存、测试和应用脚本始终需要逐次批准，包括自动模式。本次对话中始终允许这个工具不适用于这些操作。

在输入框的权限胶囊中切换当前会话的模式。在 设置 → MQTTX Agent → 默认权限模式 中设置新会话的默认值。第一次选择自动模式时，MQTTX 会要求确认相应风险。

达到步数上限后继续

一次回复最多执行每次回复的最大步数个工具步骤。默认值为 50，可在设置中选择 10 至 200。达到上限后，回复会暂停并显示继续，点击即可继续处理。

用对话完成 MQTTX 中的工作

管理连接与消息

通过 @ 选择已有连接；需要新建连接时，在请求中提供 Broker 地址、端口和必要的连接设置。写明要执行的操作，例如整理分组、配置 TLS、连接或断开、管理订阅和发布消息：

连接 Factory Demo，订阅 factory/+/telemetry，然后查看它最近收到的消息。

将 Factory Demo 替换为实际使用的连接。批准请求的操作后，打开连接页，核对连接状态、订阅列表和已收到的消息。后续检查配置或流量时，继续使用该连接的 @ 上下文。

通过自然语言与设备交互

查询或控制设备前，先提供设备的 MQTT 协议，写明遥测主题、控制主题与 Payload 格式，以及状态回报主题。执行后，通过设备新消息核对结果。

以下示例假设书房的温度传感器与风扇采用如下 MQTT 协议：

用途	Topic	JSON Payload
温度上报	home/study/temperature	{"temperature":29.4}
风扇控制指令	home/study/fan/set	{"power":"on","speed":2}
风扇状态回报	home/study/fan/state	{"power":"on","speed":2}

1. 将 MQTTX 连接到设备使用的 Broker，订阅 home/study/temperature 和 home/study/fan/state。
2. 确认温度和风扇状态消息已到达。在 Agent 对话中提供上述协议定义，并通过 @ 选择对应连接。
3. 提交以下请求：

查看书房温度和风扇状态；若温度高于 28°C，将风扇设为二档，并检查新的设备回报。

4. 温度条件满足时，在操作前询问模式中批准控制指令发布，检查工具结果，确认消息已发出。
5. 检查指令之后新的 home/study/fan/state 回报，确认电源与档位符合 {"power":"on","speed":2}。没有新的匹配回报时，保留“设备结果尚未确认”的结论。

以目标设备实际实现的协议为准。本例按提供的协议处理这一次请求，不配置常驻控制。

查找异常消息的线索

提及连接，描述异常现象、相关主题和预期 Payload，再请求检查所需的订阅、已保存或新到达的消息，以及日志。例如：

查看 Factory Demo 最近收到的消息，说明有哪些字段，并找出 Payload 结构与其他消息不同的记录。

对照工具返回的消息和日志核对分析结果。缺少所需消息时，先检查连接与订阅，接收新消息后再提交请求。排查 TLS 问题时，可请求检查本地证书；证书和私钥的文件内容保留在本地。

准备代码、测试数据与消息处理逻辑

在请求中说明语言或数据格式、目标主题，以及输入示例或预期输出，再请求生成客户端代码、测试消息、Protobuf 或 Avro Schema，或处理 Payload 的 JavaScript 转换函数。例如：

生成一个 Node.js MQTT 客户端，订阅 factory/+/telemetry，将收到的消息解析为 JSON 后输出。

按请求中的主题和格式检查生成的代码与数据。处理转换函数或 Schema 时，先提供有代表性的输入进行测试，核对输出，再应用结果。运行脚本测试在任何权限模式下都需要批准。应用转换函数会影响所有连接，应用前需要检查它的作用范围。

整理并展示数据

先连接并订阅相关主题，确认消息已到达。再请求构建或查看主题树、汇总消息，或为指定 Payload 字段创建 Dashboard 组件。例如，指定温度 Line 曲线与湿度 Gauge，并提供连接、主题过滤器和字段名称。

打开生成的视图，对照已收到的主题与 Payload 核对结果。手动配置组件时，按 Dashboard 指南 操作；Dashboard 可独立于 Agent 使用。

核对任务结果

回复结束后，打开对应的 MQTTX 页面，将实际结果与工具返回内容对照：

• 修改连接或订阅后，检查连接状态与订阅列表。
• 发布消息后，检查发布结果；任务需要设备响应时，继续检查新收到的回报。
• 生成代码、Schema 或脚本后，对照提供的示例检查输出，并在使用前核对测试结果。
• 创建数据视图后，将字段与读数同选定连接实际收到的消息对照。

某个步骤失败或缺少所需依据时，在下一次请求中附上该结果，明确继续检查的内容，保留尚未确认的结论。

在同一段对话中继续排查

会话历史保存此前的问题和工具结果，支持后续查看和继续排查。全屏模式下会话列表在左侧；浮窗中可通过标题栏的历史按钮打开。全屏时双击会话标题，或使用 ··· 菜单，可修改名称。删除会话时，消息和生成的文件会一并删除。

对话较长时，MQTTX Agent 会自动将较早的内容整理为摘要，并使用摘要继续对话。点击已压缩之前的对话分隔线可查看摘要。摘要准备过程中，面板会显示正在压缩对话…。

输入框下方的上下文栏显示当前模型上下文窗口的占用情况。悬停可查看 token 数量和自动压缩临界点。来自上一次回复的数值是实际值，带 ~ 的数值为估算值。

使用 MCP 服务器提供的工具

MCP 支持将外部系统的工具接入当前对话。在 设置 → MQTTX Agent → MCP 服务器配置 中配置服务器，支持 Streamable HTTP 和 SSE URL：

{
  "mcpServers": {
    "weather": { "url": "http://127.0.0.1:8000/mcp" },
    "legacy": { "url": "http://127.0.0.1:8001/sse" }
  }
}

保存配置后，请求执行某个服务器支持的操作，并检查工具结果。可执行的外部操作由已配置的服务器决定。在操作前询问模式下，每次 MCP 工具调用都需要批准。

能力参考

Agent 可以：

• 读取连接配置、TLS 证书信息和分组，创建、修改、删除连接。
• 创建免费的临时 Zero EMQX Broker，并保存连接。
• 连接与断开、订阅与取消订阅，发布 Plaintext、JSON、Base64 或 Hex 消息。
• 开始和停止定时发布、读取已保存的消息、等待新消息，以及清空某个连接的消息。
• 在本地检查证书和私钥，文件内容不会发送给模型。
• 编写、测试和应用转换函数与 Schema，生成客户端代码和测试数据。
• 构建和读取主题树，创建 Dashboard 和组件，以及调整组件的网格位置和大小。
• 读取日志、修改支持的应用设置，以及调用已配置的 MCP 工具。

消息历史与隐私

连接与订阅保持有效时，MQTTX 可以继续接收并保存消息，包括离开连接页面之后。可查看的历史取决于 MQTTX 实际收到并保存了哪些消息。

对话和工具结果会发送给已配置的模型服务商。工具读取连接时，会遮盖已保存的密码；证书和私钥文件只返回路径，不返回文件内容。在对话中直接输入的文字会原样发送，因此应将凭据保留在相应的配置中。

示例：把 MQTT 操作与数据展示连起来

1. 完成模型服务商配置并打开 Agent，输入 /，选择 Zero EMQX Skill。
2. 提交以下请求：

创建一个 Zero EMQX 临时 Broker，将连接保存为 Factory Demo 并连接，订阅 factory/+/telemetry。向 factory/line-01/telemetry 逐条发送 12 条包含 deviceId、temperature、humidity、pressure 且数值有变化的 JSON 消息，再创建名为 Factory Overview 的 Dashboard：显示温度、湿度和压力读数，并放一张温度趋势图，最后打开面板。

3. 在操作前询问模式中，检查并批准创建、连接、订阅、发布和 Dashboard 操作。保存连接与连接到 Broker 是两个步骤，上面的请求包含两者。
4. 打开 Factory Demo，确认连接成功、订阅存在，并且指定主题上收到了逐条发送的 JSON 消息。
5. 打开 Factory Overview，将当前读数与最新收到的消息对照，再选择覆盖这些消息的历史时间范围，检查温度趋势。

Zero EMQX Broker 免费且隔离，会按服务返回的生命周期到期，适合测试；使用时检查返回的生命周期。密码保存在连接中，不会返回给模型。Dashboard 展示连接已收到的数据。手动配置方式和数据源选项请参阅 Dashboard。