端插件概述

扣子编程提供端插件功能，用于使低代码智能体直接与硬件设备进行交互，实现对硬件设备的控制和信息获取。本文介绍什么是端插件、端插件的业务流程和应用场景，帮助你了解端插件。

什么是端插件

扣子编程插件具备调⽤各类第三⽅服务的能力，以拓展智能体能力边界。端插件是扣子编程插件的一种类型，能够使低代码智能体直接与本地设备进行交互，实现对本地设备的控制和信息获取。你可根据设备所具备的能力创建对应的端插件，之后通过简单的自然语言与绑定了端插件的低代码智能体对话，便可调用设备能力。
通过端插件，你可轻松实现设备信息获取、设备行为控制等。例如，若想调慢蓝牙音箱的播放语速，只需向部署了扣子编程智能体的蓝牙音箱发送指令，扣子编程便会调用端插件，使蓝牙音箱按指令放慢语速。详细流程如下图所示。

应用场景

扣子编程端插件主要应用于控制设备、获取设备信息、用户 GUI 交互等场景。

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

业务流程

本文以获取手机日程为例，来阐述端插件的业务流程。

业务流程说明如下：

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

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

• v3/chat：发起对话接口，用于向指定智能体发起一次对话。详细说明请参考发起对话。
• v3/chat/submit_tool_outputs：提交工具执行结果接口。详细说明请参考提交工具执行结果。
• 消息 Chat 状态机制：
  
  以下是对话的运行状态及其说明：

  状态名称	状态说明
  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 状态。

限制说明

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

接入流程

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

常见问题

端插件和普通扣子编程插件的区别？

端插件和普通扣子编程插件都是智能体与外界交互的工具。

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