> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

扣子编程提供端插件功能，用于使低代码智能体直接与硬件设备进行交互，实现对硬件设备的控制和信息获取。本文介绍什么是端插件、端插件的业务流程和应用场景，帮助你了解端插件。
## 什么是端插件 {#557a2b3e}
扣⼦插件具备调⽤各类第三⽅服务的能力，以拓展智能体能力边界。端插件是扣子编程插件的一种类型，能够使低代码智能体直接与本地设备进行交互，实现对本地设备的控制和信息获取。你可根据设备所具备的能力创建对应的端插件，之后通过简单的自然语言与绑定了端插件的低代码智能体对话，便可调用设备能力。
通过端插件，你可轻松实现设备信息获取、设备行为控制等。例如，若想调慢蓝牙音响的播放语速，只需向部署了扣子编程智能体的蓝牙音箱发送指令，扣子编程便会调用端插件，使蓝牙音箱按指令放慢语速。详细流程如下图所示。
![Image=2444x905](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/de4dfffdcc0947c9a0b20fa2ccce2375~tplv-goo7wpa0wc-image.image)
## 应用场景 {#f7cc5072}
扣子编程端插件主要应用于控制设备、获取设备信息、用户 GUI 交互等场景。

* **直接控制设备**
   用户向智能体发送指令后，智能体能够直接控制外部设备执行相应操作。例如，智能体绑定了一个端插件，对应的指令为 `PlayMusic` ，且设备内置了音乐播放逻辑处理模块。当用户向智能体发送指令“播放音乐”时，设备调用对应的方法启动音乐播放功能。
* **获取设备信息**
   用户向智能体发送获取设备相关信息的请求后，智能体能够获取到设备信息并反馈给用户。例如，智能体绑定了一个端插件（`getCalendarList`）。当用户向智能体发送指令“帮我总结我今天的日程”时，设备收到`getCalendarList` 指令后，会返回手机日程给扣子编程，扣子编程据此总结并回复用户。
* **用户 GUI 交互**
   用户向智能体发送指令后，设备弹出图形界面供用户进行交互操作，智能体会根据用户操作进行相应处理。例如：
   * 讲笑话场景
      用户向智能体发送指令“可以给我讲个笑话吗”，设备随即弹出卡片供用户选择笑话类型。若用户选择了黑色幽默，智能体便会开始讲黑色幽默的笑话。
   * 播放音乐场景
      用户向智能体发送指令“可以给我播放一首音乐吗”，设备便会弹出汽水音乐授权的卡片。用户点击授权后，开始播放音乐。

## 业务流程 {#f5c2d6d2}
本文以获取手机日程为例，来阐述端插件的业务流程。
![Image=700x447](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/af09ececef2f4195922d9757a21eadbc~tplv-goo7wpa0wc-image.image)
业务流程说明如下：

1. 用户请求：用户向设备发送请求。
2. 请求转发：设备将请求转发给业务服务端。
3. 对话建立：业务服务端通过 `v3/chat` 接口与扣子编程建立对话。
4. 推理与调用：扣子编程根据对话内容进行智能推理，判断是否需要调用端插件。
5. 请求执行端插件：若需调用端插件，则向业务服务端请求执行端插件，此时对话状态流转至 `requires_action` 状态。
6. 执行端插件：业务服务端根据下发的端插件指令，向设备执行相应的业务逻辑，具体实现由业务端自己控制。
7. 返回结果：业务服务端通过扣子编程的 `submit_tool_outputs` 接口，将端插件执行结果返回给扣子编程。
8. 生成回复：扣子编程再次进行推理后，生成回复，将结果返回给业务服务端，再由业务服务端通过设备反馈给用户。

重要组件及概念说明如下：

* v3/chat：发起对话接口，用于向指定智能体发起一次对话。详细说明请参考[发起对话](/developer_guides/chat_v3)。
* v3/chat/submit_tool_outputs：提交工具执行结果接口。详细说明请参考[提交工具执行结果](/developer_guides/chat_submit_tool_outputs)。
* 消息 Chat 状态机制：
   ![Image=500x252](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/e457213cb575483ebaead79fd4ad9e67~tplv-goo7wpa0wc-image.image)
   以下是对话的运行状态及其说明：
   <!-- @cols-width: 120,593 -->
   | | | \
   |**状态名称** |**状态说明** |
   |---|---|
   | | | \
   |created |对话已创建。 |
   | | | \
   |in_progress |大模型接收消息请求后，正在处理中。 |\
   | | |\
   | |* 扣子编程完成数据处理并返回结果，对话转为 `completed` 状态。 |\
   | |* 端插件场景下，如果扣子编程判断需要调用端插件，对话转为`requires_action` 状态。 |
   | | | \
   |requires_action |端插件场景中，调用端插件时，对话转为`requires_action` 状态。业务服务端提交执行结果后，对话重新转为 `in_progress` 状态；24 小时未成功提交执行结果转为 `expired` 状态。 |
   | | | \
   |expired |`requires_action` 状态下 24 小时未成功提交端插件执行结果时，对话转为 `expired` 状态，用户需重新发起对话。 |
   | | | \
   |completed |扣子编程完成数据处理并返回结果后，对话转为 `completed` 状态。 |
   | | | \
   |failed |消息处理失败，对话转为 `failed` 状态。 |
   | | | \
   |cancelled |消息处理被取消，对话转为 `cancelled` 状态。 |


## 限制说明 {#53f95294}

* 使用方式：仅支持通过 API 方式使用端插件。智能体绑定端插件后，调用发起对话接口与智能体对话时才能正常使用端插件能力。
* 节点限制：工作流中支持添加端插件节点，但暂不支持在大模型节点中配置端插件技能。
* 调试方式：创建端插件时暂不支持在扣子编程中调试，建议先在本地设备中调试完成后再创建并使用端插件。

## 接入流程 {#58cfb010}

1. 创建端插件并绑定到智能体。具体操作可参考[创建端插件](/guides/create_local_plugin)。
2. 将智能体发布为 API 服务。
3. 调用 API 使用端插件。具体操作可参考[通过 API 使用端插件](/guides/use_local_plugin)。

## 常见问题 {#c4e9385b}
### 端插件和普通扣子编程插件的区别？ {#d9103383}
端插件和普通扣子编程插件都是智能体与外界交互的工具。

* 端插件：用于调用本地硬件能力，例如蓝牙音响、手机等。通过端插件，智能体可以直接操控本地硬件设备，实现与用户更直接的互动。
* 普通扣子编程插件：用于调用线上服务或云端 API，例如在智能体内添加新闻搜索插件后，智能体将拥有搜索新闻资讯的能力。详细说明请参考[插件介绍](/guides/plugin)。