主题
工具配置
「工具」是执行层提示词可以主动调用的外部能力——当模型仅靠对话无法完成任务(如查询设备实时状态、下发结构化指令)时,就需要调用对应的工具来「做事」。
本页说明:什么是工具、什么时候需要调用工具、如何在页面右上角管理工具、以及如何在 执行层提示词 中告诉模型「何时调用哪个工具」。
1. 什么是工具
模型本身只能「理解语言、生成文本」。要让它真正操作设备、读取实时数据,就必须借助工具:
- 有了工具,模型可以在对话过程中「跳出文本」,去执行一个真实动作(如下发一条 AIOT 控制指令、查询当前亮度);
- 没有工具,模型只能「说」,不能「做」——它可以回答「我帮你关灯」,但灯不会真的灭。
因此,执行层提示词中每一个「要落地为动作」的意图,背后都对应着一个已配置的工具。
⚠️ 重要:只有执行层提示词可以调用工具。 意图层(接不接)、规划层(怎么做)只做判断与拆解,不直接调用工具;真正「出参数、下发动作、读取现状」的落地环节,统一由执行层提示词调用工具完成。
2. 什么时候需要调用工具
判断依据是:这一步是否需要产生「文本之外」的真实效果。
| 场景 | 是否需要工具 | 说明 |
|---|---|---|
| 用户闲聊、追问、澄清 | ❌ 不需要 | 纯对话,模型直接文本回复即可 |
| 控制设备(开关、调节参数) | ✅ 需要 | 需调用「AIOT 控制指令」类工具下发协议 |
| 查询设备实时状态 | ✅ 需要 | 需调用「状态查询」类工具读取当前值 |
| 时间差计算、复杂校验(如剩余时长、参数合法性、数值换算) | ✅ 需要 | 光靠模型自行推算容易出错,应交由专门工具精确计算与校验 |
💡 一个经验法则:凡是「出参数、下发动作、读取现状、精确计算/校验」的步骤,都需要调用工具;凡是「解释、安抚、追问」的步骤,都不需要。 尤其涉及时间差、数值换算、参数合法性等模型不擅长、易算错的环节,建议交给工具处理。
3. 各平台 / 端侧设备可用的工具及能力边界
不同 IoT 平台与端侧设备,可用的工具范围不同。下表梳理各类工具的适用范围、能力与边界,供在「添加工具」和编写执行层提示词时对照选择。
3.1 通用工具(任何 IoT 平台与端侧设备皆可用)
| 工具 | 能力 | 关键边界 |
|---|---|---|
local_command_control | 本地指令控制,支持多指令批量下发 | 同一轮多条指令必须合并进一个 instructions 数组,严禁拆成多次调用;action 只能用 PE 清单声明的 command_code/intentCode 或派生 action,严禁自造;含时间触发词须改用派生 action(_add/_query/_delete) |
device_status_from_jimdb | 通过 JIMDB 查询端侧设备状态 | 查询类指令配置请查看：查询指令 |
duration_parse_tool | 时长解析:自然语言时长 → 小时/分钟(如「两个半小时」→ 2.5h/150min) | 支持 秒/分/刻/小时/天/周;不支持 月/季度/年(长度不固定,避免近似误差) |
time_diff_tool | 时间差计算(起止时间差,可返回 秒/分/时/天) | 入参为 YYYY-MM-DD HH:MM:SS 格式 |
3.2 小家 IoT 可用工具
| 工具 | 能力 | 关键边界 |
|---|---|---|
iot_do_batch_domain_intent | 设备控制指令下发(支持批量 intent) | 顶层必填 intents(List[Dict]);单条也须写成 {"intents":[{...}]};严禁把 intent/domain/value 等平铺到顶层;定时类 intent 的 domain 固定为「设备定时」,真实品类写进 deviceTimerBody |
iot_get_device_shadow | 获取小家iot设备影子状态 | 需传 request_id/vendor_id/bot_id/did/device_token |
3.3 集贤IoT可用工具
| 工具 | 能力 | 关键边界 |
|---|---|---|
jxcloud_send_device_commands | 发送设备控制命令(支持一个或多个) | commands 必传,每条含 name/value |
jxcloud_get_device_detail | 获取设备最新状态详情 | 需传 device_id/product_id |
jxcloud_save_timer | 保存或更新定时任务(有 id 则更新,无则创建) | timeConfig 必填,timerType 为 repeat/once;hour/minute/zoneOffset 必填 |
jxcloud_get_timers | 查询设备所有定时任务 | 需传 device_id |
jxcloud_cancel_next_timer | 取消定时任务的下次执行(不影响后续) | 需传 task_id |
jxcloud_delete_timer | 删除指定定时任务 | 需传 task_id |
💡 如何选择:先确认当前设备接入的平台(通用 / 小家 IoT / 集贤云),再从对应表中选取工具。通用工具在所有平台都可用;平台专属工具只能用于对应平台的设备。
4. 在页面中管理工具
在提示词编辑页面的右上角,可以查看和管理当前智能体在用的工具。
4.1 查看当前已用工具(请勿随意删除)
点击右上角的 「工具配置」,展示的是当前产品已经在用的工具列表。
📌 列表如何初始化:创建产品时选择了端侧或 IoT 平台之后,进入产品详情并打开 AIoT 指令,「工具配置」列表会自动初始化出当前 IoT 平台或端侧设备控制所必须的工具。这些工具是 IoT 设备控制的强依赖,其使用逻辑已在系统提示词中写明、无需手动编写,也不能删除。
4.2 添加新工具
如果在已初始化工具之外,还需要让模型具备新的能力:
- 点击右上角的 「添加工具」;
- 在弹出的工具列表中选择要添加的工具(可对照 第 3 节 确认平台可用范围);
- 确认后,该工具即被加入「工具配置」列表;
- 在执行层提示词中写明:什么时候用这个工具、怎么用(详见第 5 节)。
💡 区别:系统初始化的工具——逻辑已在系统提示词内,只需保留不删;手动添加的新工具——必须自己在执行层提示词中补写调用逻辑。
5. 在执行层提示词中指定调用时机
基本写法:先声明触发条件,再说明入参怎么填。例如:
text
当用户表达「控制设备」意图(如开关、调节参数)时,调用【AIOT 控制指令】工具下发协议;
当用户询问「设备当前状态」时,先调用【状态查询】工具读取现状,再作答;
其余闲聊、追问场景,直接文本回复,不调用任何工具。一段真实示例——为「按摩 X 分钟后自动关闭」这类需求新增 duration_parse_tool(时长解析)与 time_diff_tool(时间差计算)后,在执行层提示词中写明:
text
# 新增工具调用逻辑
当用户说「按摩两个半小时」「再按一刻钟」等自然语言时长时:
1. 先调用 duration_parse_tool,把时长描述转成分钟数
(如「两个半小时」→ {"hour":2.5,"minutes":150});
2. 用解析出的分钟数作为定时时长,再调用 AIOT 控制指令工具下发。
当需要计算「距离下一次定时还剩多久」时:
调用 time_diff_tool,传入 start_time=当前时间、end_time=定时时间、
unit="minute",用返回结果作答,严禁自行心算。⚠️ 前提:提示词中引用的工具必须已经被添加到「工具配置」列表中。如果提示词让模型调用一个未配置的工具,该调用不会生效。二者必须一一对应:
- 提示词里要用的工具 → 先在右上角「添加工具」加入列表;
- 列表里已有的工具 → 才能在提示词里被安全引用。
6. 相关链接
- 上级导航:AIOT 指令总览
- 前置概念:提示词编写 · 执行层 · 工具执行
- 联动主题:定时指令 · 静默指令 · 查询指令