定义设备智能体
设备智能体不是某一台具体设备，而是一类设备的能力入口。它定义动作、状态和事件，并为对话控制、设备接入、模拟器、SDK 和多设备绑定提供统一依据；每台真实设备仍保留自己的 ID、在线状态、遥测和事件记录。
基本概念
开始创建前，先区分三个概念：
- 设备智能体：面向用户和外部系统的智能体入口，负责理解对话、选择设备、调用命令和查询状态。
- 设备规格（DeviceSpec）：设备智能体的结构化能力定义，包含基础信息、命令、遥测和事件。
- 真实设备：接入到设备智能体下的具体硬件实例，可以通过 MQTT、SDK 或模拟器上报数据和响应命令。
创建方式
如果当前还没有设备智能体，控制台首页会直接显示创建输入框。你可以输入设备描述，也可以上传已有的设备定义文件。
如果已经创建过设备智能体，可以通过以下入口继续创建新的设备智能体：
- 点击左侧边栏的 +
- 点击首页上的 创建设备智能体
设备描述可以是一段自然语言，也可以是任何能够结构化表达设备能力的文本内容，例如 Markdown、JSON 或 YAML。查看示例 只是参考入口，你可以直接使用自己的设备说明或完整的设备规格。
点击 查看示例 会打开示例面板。示例按设备场景分组展示，选择后会把一段参考描述填入输入框；你可以在发送前继续改写，让它贴合自己的设备。
创建过程由创建智能体完成。用户负责提供设备描述，并确认或修订生成结果。
设备规格 Schema
设备规格的顶层结构固定为 name、description、commands、telemetry 和 events：
{
"name": "SmartThermostat",
"description": "智能温控器，支持温度控制、模式切换、状态上报和告警事件。",
"commands": {
"set_target_temperature": {
"description": "设置目标温度。",
"parameters": {
"value": {
"type": "float",
"description": "目标温度，单位为摄氏度。",
"required": true
}
}
}
},
"telemetry": {
"current_temperature": {
"type": "float",
"description": "当前温度，单位为摄氏度。",
"defaultValue": 26
}
},
"events": {
"over_temperature": {
"description": "当前温度超过安全阈值时上报。",
"eventType": "alert",
"outputData": {
"current_temperature": {
"type": "float",
"description": "触发告警时的温度。",
"required": true
}
}
}
}
}顶层字段说明：
| 字段 | 说明 |
|---|---|
name | 设备智能体名称，建议使用稳定、简短的英文标识 |
description | 设备智能体说明，用于帮助模型理解设备场景 |
commands | 设备可执行的命令集合 |
telemetry | 设备持续上报或可查询的状态字段 |
events | 设备主动上报的结构化事件集合 |
支持的字段类型
命令参数、遥测字段和事件数据字段都使用同一组类型：
| 类型 | 用法 |
|---|---|
string | 文本、枚举值、状态名、模式名 |
int | 整数值，例如计数、等级、步进档位 |
float | 小数或测量值，例如温度、电压、功率、比例 |
bool | 开关、在线状态、是否启用 |
json | 结构化对象，例如坐标、区域、复杂配置 |
array | 列表数据，例如检测结果列表、历史记录 |
事件类型使用 eventType 表示：
| 类型 | 用法 |
|---|---|
info | 普通通知或业务状态变化 |
alert | 需要关注的告警 |
error | 故障、离线、执行失败等错误事件 |
如何定义功能
定义设备能力时，建议按下面的顺序描述：
- 设备是什么：说明设备品类、使用场景和核心目标。
- 能执行什么命令：列出用户或智能体可以主动调用的操作，并说明每个命令需要哪些参数。
- 会上报什么状态：列出需要持续关注的遥测字段，并给出合理的初始值或默认值。
- 会产生什么事件：列出设备需要主动通知的业务变化、告警或故障，并说明事件携带的数据。
- 字段命名偏好：如果已有设备端协议或 MQTT 接入计划，可以给出期望的字段标识。
例如，可以直接输入：
定义一个智能温控器。它支持开关、设置目标温度、切换运行模式；运行模式包括 heat、cool、auto、fan_only、eco。
它需要上报当前温度、目标温度、湿度、当前模式、制热状态、制冷状态和在线状态。
当温度超过 30 度时上报 over_temperature 告警事件；当设备离线时上报 device_offline 错误事件。
请使用小写英文和下划线命名命令、遥测字段和事件。也可以上传完整 JSON 或 YAML。字段命名建议使用小写英文和下划线，例如 set_target_temperature、current_temperature、device_offline。这样后续 MQTT 接入、SDK 代码和设备端实现更稳定。
命令、遥测和事件
命令表示设备可以被调用的动作。每个命令包含 description 和 parameters。命令下发时，参数会按设备规格校验：必填参数缺失、类型不匹配或包含未知参数，都会被视为不符合当前设备规格。
{
"set_mode": {
"description": "切换运行模式。",
"parameters": {
"mode": {
"type": "string",
"description": "运行模式，可选 heat、cool、auto、fan_only、eco。",
"required": true
}
}
}
}遥测表示设备持续上报或可查询的状态。defaultValue 是可选字段，但建议为模拟器和 SDK 示例提供一个符合类型的默认值。
{
"humidity": {
"type": "int",
"description": "当前湿度百分比。",
"defaultValue": 60
}
}事件表示设备主动上报的一次性变化。每个事件包含 description、eventType 和 outputData。事件上报时，事件名和数据字段也会按设备规格校验。
{
"device_offline": {
"description": "设备离线时上报。",
"eventType": "error",
"outputData": {
"reason": {
"type": "string",
"description": "离线原因。",
"required": false
}
}
}
}生成并确认
发送设备描述后，创建智能体会生成设备规格草稿。左侧对话区用于继续沟通和修订，右侧预览面板用于确认命令、遥测和事件。
确认时重点检查：
- 命令是否覆盖用户需要执行的操作
- 命令参数是否包含
type、required和清晰的description - 遥测是否覆盖设备需要持续上报或查询的状态
- 遥测字段的
defaultValue是否符合字段类型 - 事件是否覆盖需要主动通知的异常或业务变化
- 事件是否设置了合适的
eventType和outputData - 字段命名是否稳定，是否方便后续 MQTT 接入和 SDK 接入
如果草稿不符合预期，可以直接在左侧继续要求修订，例如：
把温度设置命令改成 set_target_temperature，参数名使用 value；补充一个 device_offline 事件，eventType 使用 error。如果使用的模型能力不足，返回内容出现结构错误，预览面板会显示校验问题。你可以点击自动修正，让创建智能体按校验结果修复设备规格；也可以在左侧继续补充描述，让它重新调整。
设置版本和 A2A
在预览面板中，你还可以设置：
- 版本：用于设备和 SDK 兼容校验，格式类似
1.0、1.1或2.0.3 - A2A 协作：基于 EMQX 6.2 的 A2A over MQTT 能力，将这个设备智能体发布为可被其他 A2A 智能体发现和调用的节点
启用后，系统会根据设备规格生成 A2A 卡片，并把设备命令转换为 A2A 技能入口。其他 A2A 智能体可以通过 EMQX 发现这个智能体，并使用 MQTT 发送 A2A 请求与它通信。只有需要和其他 A2A 智能体通过 MQTT 协作时才需要开启。详细用法见 A2A 协作。
如果设备规格中没有定义命令，无法发布 A2A 卡片。
创建时，系统还会根据设备规格选择合适的侧边栏图标；如果没有可靠结果，则使用默认图标。
进入设备智能体
草稿确认无误后，点击 创建。设备智能体会出现在左侧边栏中。你可以点击 进入设备智能体，或从左侧设备智能体列表进入。
进入后可以继续完成以下操作：
- 使用浏览器模拟设备验证设备交互
- 绑定一个或多个真实设备
- 通过对话向选中的设备下发命令
- 查询设备当前状态和最近事件
- 生成或适配设备端 SDK，并接入真实硬件
对话交互会基于当前设备规格和选中的设备执行。比如用户说“把目标温度设置为 24 度”，设备智能体会选择对应命令并生成参数；用户查询状态或事件时，系统会读取该设备最近上报的数据。