作为我们文档重组的一部分,此页面正在逐步淘汰。
点击此卡片跳转到包含最新信息的更新版本。
如果您在新的文档中发现任何差异或需要改进的地方,请使用页面底部的“报告问题”按钮。
工具指的是能够被 Chatflow / Workflow / Agent 类型应用所调用的第三方服务,提供完整的 API 实现能力,用于增强 Dify 应用的能力。例如为应用添加在线搜索、图片生成等额外功能。
在本文中,“工具插件” 指的是一个完整的项目,其中包含工具供应商文件、功能代码等结构。一个工具供应商内允许包含多个 Tools(可以理解为单个工具中提供的额外功能),结构如下:
本文将以 Google Search
为例,介绍如何快速开发一个工具插件。
关于如何准备插件开发的脚手架工具,详细说明请参考安装插件开发工具。
运行脚手架命令行工具,创建一个新的 dify 插件项目。
如果你已将该二进制文件重命名为 dify
并拷贝至 /usr/local/bin
路径下,可以运行以下命令创建新的插件项目:
下文将使用
dify
作为命令行示例。如遇到问题,请将dify
命令替换为命令行工具的所在路径。
脚手架工具内的所有模板均已提供完整的代码项目。在本文实例中,选择 Tool
插件。
如果你已熟悉插件开发,无需借助模板,可参考接口文档指引完成不同类型的插件开发。
插件还需读取 Dify 平台的权限,为该示例插件授予以下权限:
在终端内使用方向键选择权限,使用 “Tab” 按钮授予权限。
勾选所有权限项后,轻点回车完成插件的创建。系统将自动生成插件项目代码。
工具供应商文件为 yaml 格式文件,可以理解为工具插件的基础配置入口,用于向工具提供必要的授权信息。
前往插件模板项目中的 /provider
路径,将其中的 yaml 文件重命名为 google.yaml
。该 yaml
文件将包含工具供应商的信息,包括供应商名称、图标、作者等详情。这部分信息将在安装插件时进行展示。
示例代码
确保该文件路径位于 /tools
目录,完整的路径如下:
其中 google.yaml
文件需要使用其在插件项目的绝对路径。在本例中,它位于项目根目录。YAML 文件中的 identity 字段解释如下:identity
包含了工具供应商的基本信息,包括作者、名称、标签、描述、图标等。
_assets
文件夹下。为了便于开发,选择采用第三方服务 SerpApi
所提供的 Google Search API 。 SerpApi
要求填写 API Key 进行使用,因此需要在 yaml
文件内添加 credentials_for_provider
字段。
完整代码如下:
credentials_for_provider
的子级结构需要满足 ProviderConfig 的规范。tools/google_search.yaml
文件。google.py
中,但是暂时不实现它,而是先编写 google_search
的代码。一个工具插件下可以有多个工具功能,每个工具功能需要一个 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
两种类型。
llm
表示该参数 LLM 自行推理,form
表示要使用该工具可提前设定的参数。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 能够理解该参数。填写工具的配置信息以后,可以开始编写工具的功能代码,实现工具的逻辑目的。在/tools
目录下创建google_search.py
,内容如下:
该例子的含义为请求 serpapi
,并使用 self.create_json_message
返回一串 json
的格式化数据,如果想了解更多的返回数据类型,可以参考工具接口文档。
最后需要创建一个供应商的实现代码,用于实现凭据验证逻辑。如果凭据验证失败,将会抛出ToolProviderCredentialValidationError
异常。验证成功后,将正确请求 google_search
工具服务。
在 /provider
目录下创建 google.py
文件,代码的内容如下:
插件开发完成后,接下来需要测试插件是否可以正常运行。Dify 提供便捷地远程调试方式,帮助你快速在测试环境中验证插件功能。
前往“插件管理”页获取远程服务器地址和调试 Key。
回到插件项目,拷贝 .env.example
文件并重命名为 .env
,将获取的远程服务器地址和调试 Key 等信息填入其中。
.env
文件:
运行 python -m main
命令启动插件。在插件页即可看到该插件已被安装至 Workspace 内,团队中的其他成员也可以访问该插件。
确认插件能够正常运行后,可以通过以下命令行工具打包并命名插件。运行以后你可以在当前文件夹发现 google.difypkg
文件,该文件为最终的插件包。
恭喜,你已完成一个工具类型插件的完整开发、调试与打包过程!
如果想要将插件发布至 Dify Marketplace,请确保你的插件遵循了插件发布规范。审核通过后,代码将合并至主分支并自动上线至 Dify Marketplace。
publish-plugins
作为我们文档重组的一部分,此页面正在逐步淘汰。
点击此卡片跳转到包含最新信息的更新版本。
如果您在新的文档中发现任何差异或需要改进的地方,请使用页面底部的“报告问题”按钮。
工具指的是能够被 Chatflow / Workflow / Agent 类型应用所调用的第三方服务,提供完整的 API 实现能力,用于增强 Dify 应用的能力。例如为应用添加在线搜索、图片生成等额外功能。
在本文中,“工具插件” 指的是一个完整的项目,其中包含工具供应商文件、功能代码等结构。一个工具供应商内允许包含多个 Tools(可以理解为单个工具中提供的额外功能),结构如下:
本文将以 Google Search
为例,介绍如何快速开发一个工具插件。
关于如何准备插件开发的脚手架工具,详细说明请参考安装插件开发工具。
运行脚手架命令行工具,创建一个新的 dify 插件项目。
如果你已将该二进制文件重命名为 dify
并拷贝至 /usr/local/bin
路径下,可以运行以下命令创建新的插件项目:
下文将使用
dify
作为命令行示例。如遇到问题,请将dify
命令替换为命令行工具的所在路径。
脚手架工具内的所有模板均已提供完整的代码项目。在本文实例中,选择 Tool
插件。
如果你已熟悉插件开发,无需借助模板,可参考接口文档指引完成不同类型的插件开发。
插件还需读取 Dify 平台的权限,为该示例插件授予以下权限:
在终端内使用方向键选择权限,使用 “Tab” 按钮授予权限。
勾选所有权限项后,轻点回车完成插件的创建。系统将自动生成插件项目代码。
工具供应商文件为 yaml 格式文件,可以理解为工具插件的基础配置入口,用于向工具提供必要的授权信息。
前往插件模板项目中的 /provider
路径,将其中的 yaml 文件重命名为 google.yaml
。该 yaml
文件将包含工具供应商的信息,包括供应商名称、图标、作者等详情。这部分信息将在安装插件时进行展示。
示例代码
确保该文件路径位于 /tools
目录,完整的路径如下:
其中 google.yaml
文件需要使用其在插件项目的绝对路径。在本例中,它位于项目根目录。YAML 文件中的 identity 字段解释如下:identity
包含了工具供应商的基本信息,包括作者、名称、标签、描述、图标等。
_assets
文件夹下。为了便于开发,选择采用第三方服务 SerpApi
所提供的 Google Search API 。 SerpApi
要求填写 API Key 进行使用,因此需要在 yaml
文件内添加 credentials_for_provider
字段。
完整代码如下:
credentials_for_provider
的子级结构需要满足 ProviderConfig 的规范。tools/google_search.yaml
文件。google.py
中,但是暂时不实现它,而是先编写 google_search
的代码。一个工具插件下可以有多个工具功能,每个工具功能需要一个 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
两种类型。
llm
表示该参数 LLM 自行推理,form
表示要使用该工具可提前设定的参数。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 能够理解该参数。填写工具的配置信息以后,可以开始编写工具的功能代码,实现工具的逻辑目的。在/tools
目录下创建google_search.py
,内容如下:
该例子的含义为请求 serpapi
,并使用 self.create_json_message
返回一串 json
的格式化数据,如果想了解更多的返回数据类型,可以参考工具接口文档。
最后需要创建一个供应商的实现代码,用于实现凭据验证逻辑。如果凭据验证失败,将会抛出ToolProviderCredentialValidationError
异常。验证成功后,将正确请求 google_search
工具服务。
在 /provider
目录下创建 google.py
文件,代码的内容如下:
插件开发完成后,接下来需要测试插件是否可以正常运行。Dify 提供便捷地远程调试方式,帮助你快速在测试环境中验证插件功能。
前往“插件管理”页获取远程服务器地址和调试 Key。
回到插件项目,拷贝 .env.example
文件并重命名为 .env
,将获取的远程服务器地址和调试 Key 等信息填入其中。
.env
文件:
运行 python -m main
命令启动插件。在插件页即可看到该插件已被安装至 Workspace 内,团队中的其他成员也可以访问该插件。
确认插件能够正常运行后,可以通过以下命令行工具打包并命名插件。运行以后你可以在当前文件夹发现 google.difypkg
文件,该文件为最终的插件包。
恭喜,你已完成一个工具类型插件的完整开发、调试与打包过程!
如果想要将插件发布至 Dify Marketplace,请确保你的插件遵循了插件发布规范。审核通过后,代码将合并至主分支并自动上线至 Dify Marketplace。
publish-plugins