定义设备智能体
设备智能体不是某一台具体设备，而是一类设备的能力入口。它定义动作、状态和事件，并为对话控制、设备接入、模拟器、SDK 和多设备绑定提供统一依据；每条设备记录仍保留自己的 ID、在线状态、属性和事件记录。
基本概念
开始创建前，先区分三个概念：
- 设备智能体：面向用户和外部系统的智能体入口，负责理解对话、选择设备、调用命令和查询状态。
- 设备模型：当前接入方式使用的原生能力定义，描述状态、动作和事件。由 Device Agent 直接管理的设备使用 DeviceSpec，已有 IoT 平台沿用自己的物模型。
- 设备记录：设备智能体下具有独立 ID 的实例。它既可以使用临时浏览器模拟会话，也可以由显式配置的 SDK 或 MQTT 客户端接入；真实硬件和业务逻辑运行在设备端。
确认接入方式
创建前先确认设备将通过已有 IoT 平台接入，还是使用 SDK / MQTT 直连。在 设置 → 平台接入 → IoT 平台 中配置接入方式，再按当前平台的模型规则建模。
已有物模型时，可以提供原生定义和设备说明，保留字段标识、读写约束和服务语义。自然语言建模会按当前接入方式生成并校验模型。平台同步得到的设备智能体应按其管理入口和同步规则修改，避免本地修改与平台侧定义不一致。接入流程见IoT 平台集成。
保留原生字段与约束
原生模型可以包含结构化字段、数组、枚举以及取值约束，支持范围由当前 IoT 平台决定。提供已有模型时，说明每个字段的用途，并保留：
- 结构与数组：子字段名称、数组项类型和层级关系，例如电池组数据中的电压、温度和各电芯列表。
- 枚举：实际取值和对应显示名称，例如
0表示待机、1表示运行。修改显示名称时，保持设备协议使用的值一致。 - 约束：读写性、必填项、单位、最小值、最大值和步长，避免生成设备无法接受的操作。
生成后，在能力预览中核对这些定义。模型、模拟行为和 SDK 应使用相同的字段含义；需要改变设备协议时，同时调整设备端实现。下面的 DeviceSpec 类型表用于由 Device Agent 直接管理的设备；已有平台继续沿用其原生物模型的类型规则。
创建方式
如果当前还没有设备智能体，控制台首页会直接显示创建输入框。你可以输入设备描述，也可以上传已有的设备定义文件。
如果已经创建过设备智能体，可以通过以下入口继续创建新的设备智能体：
- 点击左侧边栏的 +
- 点击首页上的 创建设备智能体
设备描述可以是一段自然语言，也可以是任何能够结构化表达设备能力的文本内容，例如 Markdown、JSON 或 YAML。查看示例 只是参考入口，你可以直接使用自己的设备说明或完整的设备规格。
点击 查看示例 会打开示例面板。示例按设备场景分组展示，选择后会把一段参考描述填入输入框；你可以在发送前继续改写，让它贴合自己的设备。
能源场景提供光伏逆变器和储能系统参考：
| 示例 | 可参考的能力 |
|---|---|
| 光伏逆变器 | 并网启停、功率限值和运行模式，以及发电量、电网参数和温度上报 |
| 储能系统 | 工作模式、充放电控制、功率限值和备用电量，以及电池电量、健康状态和温度上报 |
选择参考后，补充实际设备的参数、单位、范围和事件。例如储能系统是否支持离网模式、允许的充放电功率，应以设备自身能力为准。
向创建智能体发送设备描述，然后检查或修订生成的模型。
如何定义功能
定义设备能力时，建议按下面的顺序描述：
- 设备是什么：说明设备品类、使用场景和核心目标。
- 能执行什么命令：列出用户或智能体可以主动调用的操作，并说明每个命令需要哪些参数。
- 会上报什么状态：列出需要持续关注的属性字段，并给出合理的初始值或默认值。
- 会产生什么事件：列出设备需要主动通知的业务变化、告警或故障，并说明事件携带的数据。
- 字段命名偏好：如果已有设备端协议或 MQTT 接入计划，可以给出期望的字段标识。
例如，可以直接输入：
定义一个智能温控器。它支持开关、设置目标温度、切换运行模式；运行模式包括 heat、cool、auto、fan_only、eco。
它需要上报当前温度、目标温度、湿度、当前模式、制热状态、制冷状态和在线状态。
当温度超过 30 度时上报 over_temperature 告警事件；当设备离线时上报 device_offline 错误事件。
请使用小写英文和下划线命名命令、属性字段和事件。也可以上传完整 JSON 或 YAML，格式参见DeviceSpec 模型示例。字段命名建议使用小写英文和下划线，例如 set_target_temperature、current_temperature、device_offline。这样后续 MQTT 接入、SDK 代码和设备端实现更稳定。
生成并确认
发送设备描述后，创建智能体会生成设备模型草稿。左侧对话区用于继续沟通和修订，右侧预览面板用于确认命令、属性和事件。
Workspace 的 AI 流程会在每次生成有效设备模型时，单独生成与之对应的浏览器行为模拟。如果继续要求修改并重新生成能力模型，保存前也会基于新模型重新生成行为模拟。
确认时重点检查：
- 命令是否覆盖用户需要执行的操作
- 命令参数是否包含
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 智能体通过 MQTT 协作时开启。模型保存或平台同步带来能力变化后，已发布的卡片会更新；可以到 A2A 工作区核对最新技能。详细用法见 A2A 多智能体协作。
发布前确认当前模型能生成可调用的 A2A 技能；没有可发布技能时，按界面提示补充设备能力。
创建时，系统还会根据设备模型选择合适的侧边栏图标；如果没有可靠结果，则使用默认图标。
进入设备智能体
草稿确认无误后，点击 创建。设备智能体会出现在左侧边栏中。你可以点击 进入 Agent，或从左侧设备智能体列表进入。
进入后可以继续完成以下操作：
- 选择或接入当前平台允许访问的设备；需要模拟验证时，使用适合测试的设备记录
- 为一条或多条设备记录配置并运行 SDK 或 MQTT 客户端
- 通过对话向选中的设备下发命令
- 查询设备当前状态和最近事件
- 生成或适配设备端 SDK，并接入真实硬件
对话交互会基于当前设备模型和选中的设备执行。比如用户说"把目标温度设置为 24 度"，设备智能体会选择对应命令并生成参数；用户查询状态或事件时，系统会读取该设备最近上报的数据。
DeviceSpec 模型示例
以下 DeviceSpec 示例适用于由 Device Agent 直接管理的设备。已有 IoT 平台使用其原生模型，不需要统一改写成这个结构。DeviceSpec 的顶层结构为 name、description、commands、properties 和 events：
{
"name": "SmartThermostat",
"description": "智能温控器，支持温度控制、模式切换、状态上报和告警事件。",
"commands": {
"set_target_temperature": {
"description": "设置目标温度。",
"parameters": {
"value": {
"type": "float",
"description": "目标温度，单位为摄氏度。",
"required": true
}
}
}
},
"properties": {
"current_temperature": {
"type": "float",
"description": "当前温度，单位为摄氏度。",
"defaultValue": 26
},
"target_temperature": {
"type": "float",
"description": "已设置的目标温度，单位为摄氏度。",
"defaultValue": 24
}
},
"events": {
"over_temperature": {
"description": "当前温度超过安全阈值时上报。",
"eventType": "alert",
"outputData": {
"current_temperature": {
"type": "float",
"description": "触发告警时的温度。",
"required": true
}
}
}
}
}顶层字段说明：
| 字段 | 说明 |
|---|---|
name | 设备智能体名称，建议使用稳定、简短的英文标识 |
description | 设备智能体说明，用于帮助模型理解设备场景 |
commands | 设备可执行的命令集合 |
properties | 设备持续上报或可查询的状态字段 |
events | 设备主动上报的结构化事件集合 |
DeviceSpec 字段类型
命令参数、属性字段和事件数据字段都使用同一组类型：
| 类型 | 用法 | 示例值 |
|---|---|---|
string | 文本、状态名、模式名 | "warm"、"idle" |
int | 整数值，例如计数、等级 | 80、0 |
float | 小数或测量值，例如温度、电压、功率、比例 | 22.5 |
bool | 开关、在线状态、是否启用 | true、false |
json | 结构化对象，例如坐标、区域、复杂配置 | { "mode": "eco" } |
array | 列表数据，例如检测结果列表、历史记录 | ["a", "b"] |
enum | 取值限定在必填 enum 列表内的字符串 | "auto" |
DeviceSpec JSON 必须使用以上准确类型名称。数值枚举使用 int 或 float，并在 enum 列表中填写对应类型的数值。string 也可以声明 enum 列表；只在描述中列出可选值不会约束实际取值。
DeviceSpec 支持 type、description 和 enum；命令与事件字段还需要 required，属性可以提供 defaultValue。它不接受 min、max、step、读写标记或嵌套字段定义等原生平台字段。由 Device Agent 直接管理的设备，其额外限制应在说明中告知 Agent，并由设备端代码校验。已有平台保留其支持的原生约束。
事件类型使用 eventType 表示：
| 类型 | 用法 |
|---|---|
info | 普通通知或业务状态变化 |
alert | 需要关注的告警 |
error | 故障、离线、执行失败等错误事件 |
DeviceSpec 模型的命令、属性和事件
命令表示设备可以被调用的动作。每个命令包含 description 和 parameters。命令下发时，参数会按设备规格校验：必填参数缺失、类型不匹配或包含未知参数，都会被视为不符合当前设备规格。
{
"set_mode": {
"description": "切换运行模式。",
"parameters": {
"mode": {
"type": "string",
"description": "运行模式，可选 heat、cool、auto、fan_only、eco。",
"required": true,
"enum": ["heat", "cool", "auto", "fan_only", "eco"]
}
}
}
}属性表示设备持续上报或可查询的状态。defaultValue 是可选字段，但建议为模拟器和 SDK 示例提供一个符合类型和枚举范围的默认值。
{
"humidity": {
"type": "int",
"description": "当前湿度百分比。",
"defaultValue": 60
}
}事件表示设备主动上报的一次性变化。每个事件包含 description、eventType 和 outputData。事件上报时，事件名和数据字段也会按设备规格校验。
{
"device_offline": {
"description": "设备离线时上报。",
"eventType": "error",
"outputData": {
"reason": {
"type": "string",
"description": "离线原因。",
"required": false
}
}
}
}