功能介绍
本文档提供三个案例（音量控制、电量查询、设定闹钟），演示如何基于物联网开发平台和 TWeTalk 自定义工具的核心能力，实现设备属性控制和设备属性查询。您可以按照业务需求，参考以下实践案例进行定制改造。
实践案例
案例1：音量控制
步骤1：定义物模型行为功能
1. 进入 控制台 产品详情页的功能定义页面， 单击新增功能，定义一个“行为”功能。
2. “行为”功能调用参数说明如下：
参数名 | 类型 | 说明 |
action | 字符串 | 要控制的行为：set 表示设置具体音量，increase 表示调高音量，decrease 表示调低音量。 |
volume | 整数型 | 要设置的音量级别（范围：0-100）。 |
3. 例如，当用户说：“把音量修改为50”，设备会通过 Topic $thing/down/action/{ProductID}/{DeviceName} 收到服务端下发的 action 指令，设备按照参数完成音量调节。
下行报文示例：
{"method": "action","clientToken": "20a4ccfd-d308-****-86c6-5254008a4f10","actionId": "control_volume","timestamp": 1212121221,"params": {"action": "set","volume": 50}}
返回参数说明：
参数名 | 类型 | 说明 |
volume | 整数型 | 设备修改成功后的音量值。 |
4. 设备完成操作后，需通过 Topic$thing/up/action/{ProductID}/{DeviceName} 响应修改的结果。
步骤2：定义智能体自定义工具
1. 在 控制台 的智能体详情页面，单击创建工具。
2. 工具参数配置建议如下：
配置项 | 配置值 |
工具名称 | 和上一步定义的行为名称保持一致：control_volume。 |
工具描述 | 控制指定设备的音量。 |
参数名称 | 与物模型行为参数保持一致：string、number。 |
参数类型 | 与物模型定义保持一致：string、number。 |
参数描述 | 使用中文详细描述，有助于提高大模型意图识别的准确度。 action：要执行的音量操作（set/increase/decrease）。 volume：要设置的音量级别（0-100）。 |
枚举值 | 对 action 参数添加枚举：set、increase、decrease。 |
注意：
强烈建议使用参数英文名，且和类型与物模型行为定义保持一致，否则可能出现下发参数不准确的情况。添加合理的枚举值可以降低大模型幻觉，提高意图识别准确度。
步骤3：测试验证
重启对话，测试定义的工具是否生效。
案例2：设备电量查询
步骤1：定义物模型行为功能
区别在于：定义物模型行为的参数时，不需要定义调用参数，只需定义返回参数即可。
步骤2：定义智能体自定义工具
1. 在 控制台 的智能体详情页面，单击创建工具。
2. 工具参数配置：无需指定任何参数。
3. 设备在收到服务端下发的行为控制后，执行电量查询并返回结果，完成查询流程。
步骤3：测试验证
重启对话，测试定义的工具是否生效。
案例3：闹钟设置
步骤1：定义物模型行为功能
1. 在 控制台 产品详情页的功能定义页面，单击新增功能，定义一个设置闹钟的“行为”功能。
2. 在参数设置上，我们按照一种简单的闹钟业务逻辑来设计，即用户只需要提供以下信息或者意图，就可以设置成功。
调用参数示例：
参数名 | 类型 | 说明 |
hour | 字符串 | 闹钟小时（范围：0-23）。 |
minute | 字符串 | 闹钟分钟（范围：0-59）。 |
frequency | 字符串 | 提醒频率：once（一次）、daily（每天）、weekly（每周）。 |
day_choice | 字符串 | 提醒的具体日期，例如：“Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday, Once, Daily”。 |
产品功能的参数设置示例：
3. 此时，按照业务预期，当用户说：“设置一个每天早上7点半的闹钟”，设备会通过 Topic $thing/down/action/{ProductID}/{DeviceName} 收到服务端下发的 action 指令。
下行报文示例：
{"method": "action","clientToken": "20a4ccfd-d308-****-86c6-5254008a4f10","actionId": "set_alarm_clock","timestamp": 1212121221,"params": {"hour": "7","minute": "30","frequency": "daily","day_choice": "Daily"}}
此时，设备再按照参数完成本地的闹钟设置（本地闹钟功能需要提前完成开发）。
返回参数说明：
参数名 | 类型 | 说明 |
alarm_status | 字符串 | 设置状态描述，例如：“Alarm clock set successfully”。 |
4. 设备完成操作后，需通过 Topic $thing/up/action/{ProductID}/{DeviceName} 响应以上设置结果。
注意：
建议在物模型定义之初，就计划好返回参数，以向 LLM 说明动作的执行结果或者返回获取到的有效信息。
可以自定义回复的内容，但是建议使用字符串回复准确的执行结果（例如“Alarm clock set successfully”），以便 LLM 在回复用户时，能提供更详细的工具执行情况描述，方便信息获取和错误溯源。
步骤2：定义智能体自定义工具
1. 在 控制台 的智能体详情页面，单击创建工具。
2. 工具参数配置建议如下：
配置项 | 配置值 |
工具名称 | 和上一步定义的行为名称保持一致：set_alarm_clock。 |
工具描述 | 设置指定设备的闹钟。 |
参数名称 | 与物模型行为参数保持一致：hour、minute、frequency、day_choice。 |
参数类型 | 与物模型定义保持一致：string。 |
参数描述 | 使用中文详细描述，有助于提高大模型意图识别的准确度。 hour：闹钟的小时（0-23）。 minute：闹钟的分钟（0-59）。 frequency：提醒频率（once/daily/weekly）。 day_choice：提醒的具体日期，格式如"Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday, Once, Daily"。 |
枚举值 | 对 frequency 参数添加枚举：once,daily,weekly。 对 day_choice 参数添加枚举：Monday,Tuesday,Wednesday,Thursday,Friday, Saturday,Sunday,Once,Daily。 |
工具编辑的建议：
注意：
强烈建议使用参数英文名，且类型与物模型行为定义保持一致，否则可能出现下发参数不准确的情况。添加合理的枚举值可以降低大模型幻觉，提高意图识别准确度。
步骤3：测试验证
重启对话，测试定义的工具是否生效。测试用例示例：
“帮我设置明天早上8点的闹钟”。
“每天早上7点叫我起床”。
“设置每周一、周三、周五下午3点的闹钟”。
常见问题
智能体回复查询/控制失败，怎么处理？
1. 检查设备是否在线，以及是否订阅了 设备行为调用 的 topic。
2. 检查物模型行为调用的参数英文名是否和智能体工具中参数英文名一致。
