Tool 插件

工具指的是能够被 Chatflow / Workflow / Agent 类型应用所调用的第三方服务，提供完整的 API 实现能力，用于增强 Dify 应用的能力。例如为应用添加在线搜索、图片生成等额外功能。

在本文中，“工具插件” 指的是一个完整的项目，其中包含工具供应商文件、功能代码等结构。一个工具供应商内允许包含多个 Tools（可以理解为单个工具中提供的额外功能），结构如下：

- 工具供应商
    - Tool A
    - Tool B
工具插件结构

本文将以 Google Search 为例，介绍如何快速开发一个工具插件。

前置准备

  • Dify 插件脚手架工具

  • Python 环境，版本号 ≥ 3.12

关于如何准备插件开发的脚手架工具，详细说明请参考初始化开发工具。

创建新项目

运行脚手架命令行工具，创建一个新的 dify 插件项目。

如果你已将该二进制文件重命名为 dify 并拷贝至 /usr/local/bin 路径下，可以运行以下命令创建新的插件项目：

下文将使用 dify 作为命令行示例。如遇到问题，请将 dify 命令替换为命令行工具的所在路径。

选择插件类型和模板

脚手架工具内的所有模板均已提供完整的代码项目。在本文实例中，选择 Tool 插件。

如果你已熟悉插件开发，无需借助模板，可参考接口文档指引完成不同类型的插件开发。

插件类型：工具

配置插件权限

插件还需读取 Dify 平台的权限，为该示例插件授予以下权限：

  • Tools

  • Apps

  • 启用持久化存储 Storage，分配默认大小存储

  • 允许注册 Endpoint

在终端内使用方向键选择权限，使用 “Tab” 按钮授予权限。

勾选所有权限项后，轻点回车完成插件的创建。系统将自动生成插件项目代码。

插件权限

开发工具插件

1. 创建工具供应商文件

工具供应商文件为 yaml 格式文件，可以理解为工具插件的基础配置入口，用于向工具提供必要的授权信息。

前往插件模板项目中的 /provider 路径，将其中的 yaml 文件重命名为 google.yaml。该 yaml 文件将包含工具供应商的信息，包括供应商名称、图标、作者等详情。这部分信息将在安装插件时进行展示。

示例代码

确保该文件路径位于 /tools 目录，完整的路径如下：

其中 google.yaml 文件需要使用其在插件项目的绝对路径。在本例中，它位于项目根目录。YAML 文件中的 identity 字段解释如下：identity 包含了工具供应商的基本信息，包括作者、名称、标签、描述、图标等。

  • 图标需要属于附件资源，需要将其放置在项目根目录的 _assets 文件夹下。

  • 标签可以帮助用户通过分类快速找到插件，以下是目前所支持的所有标签。

2. 补全第三方服务凭据

为了便于开发，选择采用第三方服务 SerpApi 所提供的 Google Search API 。 SerpApi 要求填写 API Key 进行使用，因此需要在 yaml 文件内添加 credentials_for_provider 字段。

完整代码如下：

  • 其中 credentials_for_provider 的子级结构需要满足 ProviderConfig 的规范。

  • 需要指定该供应商包含了哪些工具。本示例仅包含了一个 tools/google_search.yaml 文件。

  • 作为供应商，除了定义其基础信息外，还需要实现一些它的代码逻辑，因此需要指定其实现逻辑，在本例子中，将功能的代码文件放在了 google.py 中，但是暂时不实现它，而是先编写 google_search 的代码。

3. 填写工具 yaml 文件

一个工具插件下可以有多个工具功能，每个工具功能需要一个 yaml 文件进行描述，包含工具功能的基本信息、参数、输出等。

仍以 GoogleSearch 工具为例，在 /tools文件夹内新建一个 google_search.yaml 文件。

  • identity 包含了工具的基本信息，包括名称、作者、标签、描述等。

  • parameters 参数列表

    • name （必填）参数名称，唯一，不允许和其他参数重名。

    • type （必填）参数类型，目前支持string、number、boolean、select、secret-input、file、files、model-selector、app-selector 九种类型，分别对应字符串、数字、布尔值、下拉框、加密输入框、文件、文件集、模型选择、应用选择，对于敏感信息，请使用secret-input类型。

    • label（必填）参数标签，用于前端展示。

    • form （必填）表单类型，目前支持llm、form两种类型。

      • 在 Agent 应用中，llm 表示该参数 LLM 自行推理，form 表示要使用该工具可提前设定的参数。

      • 在 Workflow 应用中，llm和form 均需要前端填写，但 llm 的参数会做为工具节点的输入变量。

    • required 是否必填

      • 在 llm 模式下，如果参数为必填，则会要求 Agent 必须要推理出这个参数。

      • 在 form 模式下，如果参数为必填，则会要求用户在对话开始前在前端填写这个参数。

    • options 参数选项

      • 在 llm 模式下，Dify 会将所有选项传递给 LLM，LLM 可以根据这些选项进行推理。

      • 在 form 模式下，type 为 select 时，前端会展示这些选项。

    • default 默认值。

    • min 最小值，当参数类型为number时可以设定。

    • max 最大值，当参数类型为number时可以设定。

    • human_description 用于前端展示的介绍，支持多语言。

    • placeholder 字段输入框的提示文字，在表单类型为form，参数类型为string、number、secret-input时，可以设定，支持多语言。

    • llm_description 传递给 LLM 的介绍。为了使得 LLM 更好理解这个参数，请在这里写上关于这个参数尽可能详细的信息，以便 LLM 能够理解该参数。

4. 准备工具代码

填写工具的配置信息以后，可以开始编写工具的功能代码，实现工具的逻辑目的。在/tools目录下创建google_search.py，内容如下：

该例子的含义为请求 serpapi，并使用 self.create_json_message 返回一串 json 的格式化数据，如果想了解更多的返回数据类型，可以参考工具接口文档。

4. 完成工具供应商代码

最后需要创建一个供应商的实现代码，用于实现凭据验证逻辑。如果凭据验证失败，将会抛出ToolProviderCredentialValidationError异常。验证成功后，将正确请求 google_search 工具服务。

在 /provider 目录下创建 google.py 文件，代码的内容如下：

调试插件

插件开发完成后，接下来需要测试插件是否可以正常运行。Dify 提供便捷地远程调试方式，帮助你快速在测试环境中验证插件功能。

前往“插件管理”页获取远程服务器地址和调试 Key。

回到插件项目，拷贝 .env.example 文件并重命名为 .env，将获取的远程服务器地址和调试 Key 等信息填入其中。

.env 文件：

运行 python -m main 命令启动插件。在插件页即可看到该插件已被安装至 Workspace 内，团队中的其他成员也可以访问该插件。

打包插件（可选）

确认插件能够正常运行后，可以通过以下命令行工具打包并命名插件。运行以后你可以在当前文件夹发现 google.difypkg 文件，该文件为最终的插件包。

恭喜，你已完成一个工具类型插件的完整开发、调试与打包过程！

发布插件（可选）

如果想要将插件发布至 Dify Marketplace，请确保你的插件遵循了插件发布规范。审核通过后，代码将合并至主分支并自动上线至 Dify Marketplace。

发布插件

探索更多

快速开始：

插件接口文档：

Previous初始化开发工具NextModel 插件

Last updated