# 使用设备智能体

设备智能体创建完成后，会进入对应的工作区。这里用于管理同一类设备：你可以用模拟设备验证交互，也可以接入真实硬件；可以查看设备状态、最近事件和可用命令，也可以通过对话控制或查询设备。

## 工作区组成

工作区主要分为三个区域：

| 区域 | 作用 |
| --- | --- |
| 设备列表 | 查看当前设备智能体下的真实设备和模拟设备，接入新设备，刷新或删除设备 |
| 设备状态 | 选中设备后查看在线状态、当前数据、可用命令和最近事件 |
| 对话区 | 通过文字、语音或多媒体输入与设备智能体交互 |

如果还没有设备，可以先从左侧接入真实设备，或启动一个浏览器模拟设备。设备出现后，选中它即可打开状态面板，后续对话也会默认围绕这台设备进行。

![设备智能体工作区概览](../images/docs/usage/use-device-agent/zh/01-workspace-overview.png)

## 接入真实设备

点击设备列表中的 **接入设备**，可以把真实硬件接入到当前设备智能体。控制台提供三种入口：

| 方式 | 适合场景 |
| --- | --- |
| SDK 工程 | 需要一个可运行的设备端工程，再补充硬件逻辑 |
| 智能体适配和增强 SDK | 基于 SDK 工程生成设备端业务逻辑，下载后继续微调或直接运行 |
| 已有设备 | 已经有固件、网关或后端服务，只需要按 MQTT 主题和消息体约定适配 |

使用 SDK 工程时，需要选择开发语言，并确认设备名称和 `deviceId`。工程会带上当前设备规格、设备身份、连接配置和基础设备端代码，适合快速启动接入。

如果设备端业务逻辑还没有写好，可以选择智能体适配和增强 SDK。你只需要描述状态上报、命令处理、事件触发等逻辑，也可以补充芯片、系统或驱动文档，设备智能体会在基础工程上生成可运行的代码包。

已有设备接入不会生成代码。控制台会给出 `productId`、`namespace`、`deviceId`、MQTT 服务地址、主题和消息体示例。已有系统按这些信息上报状态、响应命令和上报事件后，就会作为真实设备出现在设备列表中。

![SDK 接入真实设备](../images/docs/usage/use-device-agent/zh/02-sdk-access.png)

详细流程见 [SDK 接入](../device-access/sdk-generation.md) 和 [MQTT 接入](../device-access/mqtt.md)。

## 使用模拟设备

如果真实硬件还没有准备好，可以点击 **用模拟设备试试**。模拟设备运行在浏览器中，会根据当前设备规格创建一台临时设备，并连接到当前设备智能体。

模拟设备适合用来验证：

- 设备能否上线和离线
- 当前数据是否按设备规格展示
- 对话中的控制指令能否转换为设备命令
- 设备事件能否上报并出现在最近事件中

模拟设备会出现在设备列表中，并带有 **模拟** 标识。它用于概念验证、演示和调试，不能替代真实硬件接入。

更多细节见 [设备模拟器](../device-access/simulator.md)。

## 设备列表

设备列表展示当前设备智能体下的所有设备。每台设备都有自己的设备 ID、在线状态、当前数据和事件记录；它们共享同一份设备规格，可以被同一个设备智能体理解和控制。

设备列表中常用操作包括：

- **刷新**：重新加载设备列表和在线状态
- **接入设备**：打开真实设备接入入口
- **用模拟设备试试**：启动浏览器模拟设备
- **选择设备**：打开该设备的状态面板，并让后续对话默认指向它
- **删除设备**：从当前设备智能体下移除设备记录

如果当前没有选中设备，也可以直接询问设备智能体当前管理了哪些设备：

```text
当前有多少设备？分别哪些在线，哪些离线？
```

![设备列表](../images/docs/usage/use-device-agent/zh/04-device-list.png)

## 设备状态

选中设备后，状态面板会显示这台设备的运行信息：

| 内容 | 说明 |
| --- | --- |
| 设备状态 | 当前是否在线，以及最近上线或注册时间 |
| 当前数据 | 设备最近上报的状态字段，例如温度、湿度、模式、开关状态等 |
| 可用命令 | 当前设备规格中定义的命令，以及每个命令的参数数量和说明 |
| 最近上报事件 | 设备主动上报的事件，包括事件名称、类型、来源和事件内容 |

状态面板用于确认设备交互是否生效。比如你通过对话切换运行模式后，可以在 **当前数据** 中确认字段是否变化；如果设备上报告警，可以在 **最近上报事件** 中查看事件详情。

如果选中的是模拟设备，状态面板顶部还会提供连接和断开操作，方便测试上线、离线和重连流程。

![设备状态面板](../images/docs/usage/use-device-agent/zh/05-device-status.png)

## 通过对话控制设备

对话区会结合设备规格和目标设备理解用户请求。

选中设备后，可以直接输入控制类请求：

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

设备智能体会选择合适的命令，生成参数，并下发到当前设备。

也可以输入查询类请求：

```text
查看当前设备状态，并告诉我最近有没有上报事件。
```

这类请求会读取设备最近上报的状态和事件，不会重新定义设备能力。

如果没有选中设备，适合先做设备范围内的查询：

```text
列出当前设备智能体下的设备，并按在线和离线分组。
```

## 定时任务

需要未来执行或周期执行的检查、提醒、汇总和设备操作时，可以直接在对话中说明任务和时间。例如：

```text
1 分钟后把当前温控器的目标温度设为 24 度。
```

设备智能体会创建内置定时任务，并在到期后由网关运行时唤起独立执行。测试执行结果时，以 [日志](../operate-reference/logs.md) 中的 `Timer` 模块记录为准。详细说明见 [定时任务](./scheduled-tasks.md)。

## 指定目标设备

当一个设备智能体下接入了多台设备时，有两种方式指定目标设备：

| 方式 | 适合场景 |
| --- | --- |
| 在左侧选择设备 | 后续对话默认围绕这台设备执行 |
| 在输入框中使用 `@` | 临时指定某台设备，或在多台设备之间快速切换 |

输入 `@` 后，可以从设备列表中选择目标设备。你也可以直接输入完整设备名称或设备 ID，例如：

```text
@thermostat-01 查看当前温度和湿度。
```

```text
@thermostat-02 把目标温度设置为 23 度。
```

如果同时选中了设备，又在消息中指定了另一台设备，设备智能体会把这些设备都作为本次请求的目标，用于查询、比较或分别下发控制。

## 语音、摄像头和模拟显示器

选中设备后，如果相关能力已经开启，对话区会出现更多交互入口。这些能力可以在控制台中体验，也可以通过设备端 SDK 接入真实设备。

- **语音**：通过麦克风向设备智能体发起语音对话，也可以接入设备端语音交互。
- **摄像头**：给当前设备提供图像信息，例如拍照识别、画面理解，或让设备基于画面执行操作；真实设备可以通过 SDK 上传图像帧。
- **模拟显示器**：用于查看或模拟设备的可视化输出。设备智能体可以生成控制面板、状态面板、扩展内容，或模拟一块设备屏幕。

这些能力都作用于当前选中的设备。配置和开启方式见 [配置](../operate-reference/configuration.md)，使用说明见 [语音交互](./voice.md)、[摄像头与视觉识别](./multimedia.md) 和 [模拟显示器](./simulated-display.md)；设备端代码生成见 [SDK 接入](../device-access/sdk-generation.md)。

![语音、摄像头和模拟显示器入口](../images/docs/usage/use-device-agent/zh/03-device-media-display.png)

## 技能与工具

设备规格定义的是设备本身的命令、状态和事件。技能与工具用于扩展设备智能体可以调用的外部能力，例如读取业务系统数据、触发外部服务、封装一段操作流程。

当一个能力属于设备本身，应该放在设备规格里；当一个能力依赖外部系统或业务流程，更适合放在技能与工具里。

详细说明见 [技能与工具](./tools.md)。

## 建议流程

第一次使用设备智能体时，可以按下面的顺序推进：

1. 先启动模拟设备，验证命令、状态和事件是否符合预期。
2. 再通过 SDK 接入或 MQTT 接入真实设备。
3. 在设备列表中选择真实设备，确认在线状态和当前数据。
4. 通过对话下发控制命令，并在状态面板中确认结果。
5. 如需连接外部系统，再配置技能与工具。