快速体验

安装并启动 Device Agent 后，用温控器描述创建设备智能体，再添加设备记录并连接浏览器模拟器，验证命令下发、状态上报和对话控制。本例由 Device Agent 直接管理设备，无需真实硬件；已有 IoT 平台设备按IoT 平台集成连接后，在工作区验证查询与控制。

开始前

macOS 和 Linux 可以直接执行下面的命令完成安装，并在首次启动时配置 MQTT 和大模型：

curl -fsSL https://emqx.sh/device-agent | sh

ZERO_EMQX_ENABLED=true \
LLM_PROVIDER=openai \
LLM_MODEL=gpt-5.5 \
OPENAI_API_KEY=sk-... \
device-agent

ZERO_EMQX_ENABLED=true 会在启动时自动创建临时 Zero EMQX Broker，并写入 MQTT 配置。已有 MQTT Broker 时，按 准备 MQTT Broker 配置连接信息。

启动后打开 http://127.0.0.1:3000。Windows 安装方式见 下载安装。 大模型也可以在控制台 设置 → 模型 中修改；字段和可用服务商见 大模型配置。

1. 输入设备描述

如果当前还没有设备智能体，控制台首页会直接显示输入框，你可以输入或上传设备描述。如果已经创建过设备智能体， 可以点击左侧边栏的 +，或首页上的 创建设备智能体 按钮进入创建流程。

设备描述可以是一段文本，也可以是 JSON、YAML 或 Markdown 文件，只要能描述设备的命令、属性和事件即可。 查看示例 只是可选参考入口，你也可以直接输入自己的设备描述。

本次快速体验直接复制以下描述并发送：

智能温控器，支持开关、目标温度设定和运行模式切换（制热、制冷、自动、仅送风、节能），并上报当前温度、湿度和制热/制冷状态；当温度超过 30 度或设备离线时，上报告警事件。
使用 set_target_temperature(value) 更新 target_temperature，使用 set_mode(mode) 更新 mode。
模式枚举值为 heat、cool、auto、fan_only、eco。模拟这两项状态变化。

点击发送按钮后，系统会生成一份设备规格（DeviceSpec）草稿。

2. 确认设备能力

在右侧预览面板中确认大模型生成的命令、属性和事件是否覆盖预期。结果会随输入变化；上面的温控器描述可能生成：

• 命令：开关、目标温度设置、运行模式切换
• 属性：当前温度、目标温度、湿度、运行模式、制热/制冷状态、在线状态
• 事件：温度过高、设备离线等告警事件

在 模拟行为 中确认两个设置命令会更新 target_temperature 和 mode。映射缺失或不符合预期时，在创建对话中补充动作效果，再确认重新生成的结果。校验失败时，先点击 修复模拟器行为，修复后再保存。

能力和模拟行为都符合预期后，点击 创建。创建完成后，可以点击完成页上的 进入 Agent，也可以从左侧设备智能体列表中点击刚创建的设备智能体进入。保存前修改能力模型时，模拟行为也会基于新模型重新生成。

3. 将设备连接到浏览器模拟器

进入设备智能体后，左侧是 设备 面板。点击 接入设备，填写设备名称和设备 ID，再点击 创建设备。

在列表中选中新设备，再点击状态面板中的 模拟连接。浏览器模拟器会用该设备 ID 连接 MQTT 并开始上报状态。 断开浏览器会话后，可以再为同一条设备记录配置并显式启动 SDK 或 MQTT 客户端。

连接成功后，状态面板会显示：

• 设备状态
• 当前数据
• 可用操作
• 最近上报事件

4. 控制设备并查询状态和事件

保持已连接浏览器模拟器的设备处于选中状态，先在对话框中输入控制请求：

把目标温度设置为 24 度，并切换到自动模式。

设备智能体会基于当前设备规格和选中的设备调用对应命令。浏览器模拟器收到命令后，会执行生成的行为模拟。 有状态映射的命令会更新当前数据并继续上报。本例中，明确声明为空效果的命令会成功返回但不改变状态；未声明模拟行为的命令会返回不支持。

然后可以继续查询当前状态和最近事件：

查看当前设备状态，包括当前温度、目标温度、湿度和运行模式；同时查看最近有没有上报事件，如果有，请按时间列出来。

在状态面板中确认 target_temperature 和 mode 是否更新。 模拟器不会自动产生阈值或离线事件。需要验证模型事件时，按设备模拟器使用 模拟上报 → 上报事件。尚未上报事件时，对话会返回当前没有可用事件。

体验结果

完成以上步骤后，你已经验证了设备智能体的几个核心能力：

• 用文本、JSON、YAML 或 Markdown 设备描述生成设备规格草稿。
• 确认设备规格中的命令、属性和事件。
• 创建普通设备记录，并将它连接到浏览器模拟器。
• 通过对话向设备下发控制命令，并查询设备状态和事件。

下一步

• 阅读 定义设备智能体，了解设备智能体、设备规格和真实设备的关系。
• 阅读 MQTT 接入，将真实设备接入设备智能体。
• 阅读 SDK 接入，了解如何生成或适配设备端接入工程。