# 定义设备智能体

设备智能体不是某一台具体设备，而是一类设备的能力入口。它定义动作、状态和事件，并为对话控制、设备接入、模拟器、SDK 和多设备绑定提供统一依据；每台真实设备仍保留自己的 ID、在线状态、遥测和事件记录。

## 基本概念

开始创建前，先区分三个概念：

- **设备智能体**：面向用户和外部系统的智能体入口，负责理解对话、选择设备、调用命令和查询状态。
- **设备规格（DeviceSpec）**：设备智能体的结构化能力定义，包含基础信息、命令、遥测和事件。
- **真实设备**：接入到设备智能体下的具体硬件实例，可以通过 MQTT、SDK 或模拟器上报数据和响应命令。

## 创建方式

如果当前还没有设备智能体，控制台首页会直接显示创建输入框。你可以输入设备描述，也可以上传已有的设备定义文件。

如果已经创建过设备智能体，可以通过以下入口继续创建新的设备智能体：

- 点击左侧边栏的 **+**
- 点击首页上的 **创建设备智能体**

设备描述可以是一段自然语言，也可以是任何能够结构化表达设备能力的文本内容，例如 Markdown、JSON 或 YAML。**查看示例** 只是参考入口，你可以直接使用自己的设备说明或完整的设备规格。

点击 **查看示例** 会打开示例面板。示例按设备场景分组展示，选择后会把一段参考描述填入输入框；你可以在发送前继续改写，让它贴合自己的设备。

![查看示例面板](../images/docs/usage/create-agent/zh/01-view-examples.png)

创建过程由创建智能体完成。用户负责提供设备描述，并确认或修订生成结果。

## 设备规格 Schema

设备规格的顶层结构固定为 `name`、`description`、`commands`、`telemetry` 和 `events`：

```json
{
  "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` | 故障、离线、执行失败等错误事件 |

## 如何定义功能

定义设备能力时，建议按下面的顺序描述：

1. **设备是什么**：说明设备品类、使用场景和核心目标。
2. **能执行什么命令**：列出用户或智能体可以主动调用的操作，并说明每个命令需要哪些参数。
3. **会上报什么状态**：列出需要持续关注的遥测字段，并给出合理的初始值或默认值。
4. **会产生什么事件**：列出设备需要主动通知的业务变化、告警或故障，并说明事件携带的数据。
5. **字段命名偏好**：如果已有设备端协议或 MQTT 接入计划，可以给出期望的字段标识。

例如，可以直接输入：

```text
定义一个智能温控器。它支持开关、设置目标温度、切换运行模式；运行模式包括 heat、cool、auto、fan_only、eco。
它需要上报当前温度、目标温度、湿度、当前模式、制热状态、制冷状态和在线状态。
当温度超过 30 度时上报 over_temperature 告警事件；当设备离线时上报 device_offline 错误事件。
请使用小写英文和下划线命名命令、遥测字段和事件。
```

也可以上传完整 JSON 或 YAML。字段命名建议使用小写英文和下划线，例如 `set_target_temperature`、`current_temperature`、`device_offline`。这样后续 MQTT 接入、SDK 代码和设备端实现更稳定。

## 命令、遥测和事件

**命令**表示设备可以被调用的动作。每个命令包含 `description` 和 `parameters`。命令下发时，参数会按设备规格校验：必填参数缺失、类型不匹配或包含未知参数，都会被视为不符合当前设备规格。

```json
{
  "set_mode": {
    "description": "切换运行模式。",
    "parameters": {
      "mode": {
        "type": "string",
        "description": "运行模式，可选 heat、cool、auto、fan_only、eco。",
        "required": true
      }
    }
  }
}
```

**遥测**表示设备持续上报或可查询的状态。`defaultValue` 是可选字段，但建议为模拟器和 SDK 示例提供一个符合类型的默认值。

```json
{
  "humidity": {
    "type": "int",
    "description": "当前湿度百分比。",
    "defaultValue": 60
  }
}
```

**事件**表示设备主动上报的一次性变化。每个事件包含 `description`、`eventType` 和 `outputData`。事件上报时，事件名和数据字段也会按设备规格校验。

```json
{
  "device_offline": {
    "description": "设备离线时上报。",
    "eventType": "error",
    "outputData": {
      "reason": {
        "type": "string",
        "description": "离线原因。",
        "required": false
      }
    }
  }
}
```

## 生成并确认

发送设备描述后，创建智能体会生成设备规格草稿。左侧对话区用于继续沟通和修订，右侧预览面板用于确认命令、遥测和事件。

![创建设备智能体并预览设备规格](../images/docs/usage/create-agent/zh/02-create-agent-preview.png)

确认时重点检查：

- 命令是否覆盖用户需要执行的操作
- 命令参数是否包含 `type`、`required` 和清晰的 `description`
- 遥测是否覆盖设备需要持续上报或查询的状态
- 遥测字段的 `defaultValue` 是否符合字段类型
- 事件是否覆盖需要主动通知的异常或业务变化
- 事件是否设置了合适的 `eventType` 和 `outputData`
- 字段命名是否稳定，是否方便后续 MQTT 接入和 SDK 接入

如果草稿不符合预期，可以直接在左侧继续要求修订，例如：

```text
把温度设置命令改成 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.md)。

如果设备规格中没有定义命令，无法发布 A2A 卡片。

创建时，系统还会根据设备规格选择合适的侧边栏图标；如果没有可靠结果，则使用默认图标。

## 进入设备智能体

草稿确认无误后，点击 **创建**。设备智能体会出现在左侧边栏中。你可以点击 **进入设备智能体**，或从左侧设备智能体列表进入。

进入后可以继续完成以下操作：

- 使用浏览器模拟设备验证设备交互
- 绑定一个或多个真实设备
- 通过对话向选中的设备下发命令
- 查询设备当前状态和最近事件
- 生成或适配设备端 SDK，并接入真实硬件

对话交互会基于当前设备规格和选中的设备执行。比如用户说“把目标温度设置为 24 度”，设备智能体会选择对应命令并生成参数；用户查询状态或事件时，系统会读取该设备最近上报的数据。

## 下一步

- 阅读 [设备模拟器](../device-access/simulator.md)，在没有真实硬件时验证交互流程。
- 阅读 [MQTT 接入](../device-access/mqtt.md)，将真实设备接入设备智能体。