# IoT 平台集成

Device Agent 可以在已有 IoT 平台上增加自然语言设备查询、状态解释、控制及围绕设备上报的自动化能力。已有平台继续管理设备和原生物模型，Device Agent 按适配后的能力查询与执行；没有 IoT 平台的设备可通过 SDK 或 MQTT 直连，由 Device Agent 管理设备模型、设备记录和上报状态。两种方式都可在设备智能体工作区中使用。

## 选择接入路径

| 现有情况 | 接入方式 | 需要准备 |
| --- | --- | --- |
| 设备已接入 IoT 平台，希望增加 AI 查询与控制 | 经 IoT 平台接入 | 原生物模型、平台接口、访问凭证和设备范围 |
| 新设备或设备端服务，希望直接接入 Device Agent | SDK 或 MQTT 直连 | 设备能力描述、设备身份和 MQTT 连接信息 |
| 硬件尚未就绪，希望先验证交互 | 浏览器模拟器 | 已定义的设备能力，以及允许用于测试的设备记录 |

平台适配决定设备能力如何执行。例如同样是设置目标温度，某个平台通过命令执行，另一个平台通过写入期望状态执行。Device Agent 会按当前适配方式选择对应操作，并返回执行结果。

## 沿用原生物模型

物模型描述设备能做什么。不同平台可能使用属性、服务、动作或设备影子来描述同一项能力，字段结构和读写规则也可能不同。

完成适配后，Device Agent 会根据原生模型识别：

- **状态**：设备当前上报的温度、模式等信息，以及平台支持的期望状态。
- **动作**：设备可执行的命令、服务或可写状态，以及它们的参数要求。
- **事件**：设备主动上报的告警、故障和业务变化。

建模和修改时，沿用对应平台的字段标识、取值范围和读写约束。Device Agent 会校验模型和操作参数。查询历史数据、批量任务等能力取决于当前平台适配，不能仅凭物模型中存在某个字段就认为这些操作可用。

<a id="thingsneural-平台契约示例"></a>

## ThingsNeural 平台示例

以下以 IoT 平台 **ThingsNeural** 为例。Device Agent 已内置对该平台的集成，可沿用其现有设备和原生物模型，提供 AI 查询、设备控制和自动化能力。

在 **设置 → 平台接入 → 平台提供商** 中选择 **ThingsNeural**，即可查看 **物模型**、**主题模板** 和 **载荷示例**。物模型展示基础结构，具体属性、服务和事件由实际设备模型定义；主题模板和载荷示例用于了解 MQTT 消息的主题与数据格式。

![ThingsNeural 物模型骨架示例](../images/docs/operate-reference/configuration/zh/07-platform-contract-model.png)

![ThingsNeural 主题模板示例](../images/docs/operate-reference/configuration/zh/08-platform-contract-topics.png)

![ThingsNeural 属性上报载荷示例](../images/docs/operate-reference/configuration/zh/09-platform-contract-payloads.png)

Device Agent 支持集成自建及第三方 IoT 平台。集成所需资料参见[接入新的 IoT 平台](#接入新的-iot-平台)；有关集成方案，请[联系我们](mailto:contact@emqx.io)。

## 配置平台连接

集成 IoT 平台时，登录鉴权和 API 访问授权采用平台支持的方式。例如，SSO 可用于 Device Agent 登录鉴权，AK/SK 等凭证可用于平台 API 访问授权。相关配置参见[平台提供商](../operate-reference/configuration/settings-ui.md#平台提供商)。

## 同步与使用设备

完成平台连接后，可将原生物模型同步到 Device Agent，生成或更新对应的设备智能体。以 ThingsNeural 为例，该操作通过 **同步产品** 完成。

工作区沿用平台提供的设备和状态数据。选择设备后，Device Agent 根据其物模型和访问权限，通过平台接口查询状态或执行控制。具体操作参见[使用设备智能体](../usage/use-device-agent.md)。

## 复用设备能力

接入验证通过后，可以继续使用同一批设备能力：

| 需求 | 功能 |
| --- | --- |
| 查询状态、解释事件、执行控制 | [使用设备智能体](../usage/use-device-agent.md) |
| 到指定时间检查设备或执行操作 | [定时任务](../usage/scheduled-tasks.md) |
| 收到状态或事件后自动处理 | [工作流](../usage/workflows.md) |
| 让多个设备智能体协作 | [A2A 多智能体协作](../usage/a2a.md) |
| 对接业务系统、知识服务和通知渠道 | [技能与工具](../usage/tools.md)、[Webhook](../integrations/webhooks.md) |
| 开发或改造设备端程序 | [SDK 接入](../device-access/sdk-generation.md)、[MQTT 接入](../device-access/mqtt.md) |

这些功能使用当前可用的设备能力和权限范围。自动化执行时，目标设备和依赖的平台服务仍需可用。

## 接入新的 IoT 平台

内置列表中没有目标平台时，需要先完成平台适配，再配置连接。接入评估建议准备以下资料：

| 资料 | 需要说明 |
| --- | --- |
| 原生物模型 | 状态、动作、事件的定义，以及类型和读写约束 |
| 平台接口与认证 | 设备列表、状态查询、控制与回执接口，访问范围和授权方式 |
| 消息协议 | MQTT 主题、状态与事件消息、关联请求和响应的方式 |
| 验证场景 | 一次状态查询、一项控制动作，以及设备上报后的预期结果 |

适配会把这些差异连接到 Device Agent 的设备能力，后续对话和自动化沿用通用操作流程。新设备直连时，还可以根据适配后的物模型和协议生成 SDK 与浏览器模拟行为。

如需接入自有 IoT 平台，或希望在生产环境部署并运行大规模 Agent，可通过[平台概览](../platform/overview.md#获取部署方案)中的联系方式与我们联系。IoT 平台集成负责连接已有设备系统，商业化平台提供生产部署与运行管理能力。