Tool 插件

Tool 工具插件是能够被 Chatflow / Workflow / Agent 应用类型所引用的外部工具，用于增强 Dify 应用的能力。例如为应用添加在线搜索能力、图片生成能力等。工具插件能够提供完整的工具集和 API 实现能力。

同时，工具插件允许包含多个 Action（可以理解为工具中的各个功能），结构如下：

- 工具供应商
    - Action A
    - Action B

Tool structure

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

前置准备

• Dify 插件脚手架工具

• Python 环境，版本号 ≥ 3.12

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

选择插件类型和模板

插件分为三种类型：工具、模型和扩展。脚手架工具内的所有模板均已提供完整的代码项目。出于演示说明，本文将以 Tool 类型插件模板作为示例。

对于已熟悉插件的开发者而言，无需借助模板，可参考接口文档指引完成不同类型的插件开发。

Plugins type: tool

配置插件权限

插件还需要读取 Dify 平台的权限才能正常连接。需要为该示例工具插件授予以下权限：

• Tools

• Apps

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

• 允许注册 Endpoint

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

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

Plugins permissions

开发工具插件

1. 创建工具供应商 yaml 文件

工具供应商文件可以理解为工具插件的基础配置入口，用于向工具提供必要的授权信息。本章节将演示如何填写该 yaml 文件。

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

示例代码

identity: # 工具供应商的基本信息
  author: Your-name # 作者
  name: google # 名称，唯一，不允许和其他供应商重名
  label: # 标签，用于前端展示
    en_US: Google # 英文标签
    zh_Hans: Google # 中文标签
  description: # 描述，用于前端展示
    en_US: Google # 英文描述
    zh_Hans: Google # 中文描述
  icon: icon.svg # 图标，需要放置在 _assets 文件夹下
  tags: # 标签，用于前端展示
    - search

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

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

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

  • class ToolLabelEnum(Enum):
      SEARCH = 'search'
      IMAGE = 'image'
      VIDEOS = 'videos'
      WEATHER = 'weather'
      FINANCE = 'finance'
      DESIGN = 'design'
      TRAVEL = 'travel'
      SOCIAL = 'social'
      NEWS = 'news'
      MEDICAL = 'medical'
      PRODUCTIVITY = 'productivity'
      EDUCATION = 'education'
      BUSINESS = 'business'
      ENTERTAINMENT = 'entertainment'
      UTILITIES = 'utilities'
      OTHER = 'other'

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

plugins:
  tools:
    - "google.yaml"

其中 google.yaml 文件需要使用其在插件项目的绝对路径。

• 补全第三方服务凭据

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

完整代码如下：

identity:
  author: Dify
  name: google
  label:
    en_US: Google
    zh_Hans: Google
    pt_BR: Google
  description:
    en_US: Google
    zh_Hans: GoogleSearch
    pt_BR: Google
  icon: icon.svg
  tags:
    - search
credentials_for_provider: #添加 credentials_for_provider 字段
  serpapi_api_key:
    type: secret-input
    required: true
    label:
      en_US: SerpApi API key
      zh_Hans: SerpApi API key
    placeholder:
      en_US: Please input your SerpApi API key
      zh_Hans: 请输入你的 SerpApi API key
    help:
      en_US: Get your SerpApi API key from SerpApi
      zh_Hans: 从 SerpApi 获取您的 SerpApi API key
    url: https://serpapi.com/manage-api-key
tools:
  - tools/google_search.yaml
extra:
  python:
    source: google.py

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

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

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

2. 填写工具 yaml 文件

一个工具供应商下可以有多个工具，每个工具都需要一个 yaml 文件进行描述，该文件包含了工具的基本信息、参数、输出等。

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

identity:
  name: google_search
  author: Dify
  label:
    en_US: GoogleSearch
    zh_Hans: 谷歌搜索
    pt_BR: GoogleSearch
description:
  human:
    en_US: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query.
    zh_Hans: 一个用于执行 Google SERP 搜索并提取片段和网页的工具。输入应该是一个搜索查询。
    pt_BR: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query.
  llm: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query.
parameters:
  - name: query
    type: string
    required: true
    label:
      en_US: Query string
      zh_Hans: 查询语句
      pt_BR: Query string
    human_description:
      en_US: used for searching
      zh_Hans: 用于搜索网页内容
      pt_BR: used for searching
    llm_description: key words for searching
    form: llm
extra:
  python:
    source: tools/google_search.py

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

• parameters 参数列表

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

  • type （必填）参数类型，目前支持string、number、boolean、select、secret-input 五种类型，分别对应字符串、数字、布尔值、下拉框、加密输入框，对于敏感信息，请使用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 能够理解该参数

3. 准备工具代码

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

from collections.abc import Generator
from typing import Any

import requests

from dify_plugin import Tool
from dify_plugin.entities.tool import ToolInvokeMessage

SERP_API_URL = "https://serpapi.com/search"

class GoogleSearchTool(Tool):
    def _parse_response(self, response: dict) -> dict:
        result = {}
        if "knowledge_graph" in response:
            result["title"] = response["knowledge_graph"].get("title", "")
            result["description"] = response["knowledge_graph"].get("description", "")
        if "organic_results" in response:
            result["organic_results"] = [
                {
                    "title": item.get("title", ""),
                    "link": item.get("link", ""),
                    "snippet": item.get("snippet", ""),
                }
                for item in response["organic_results"]
            ]
        return result

    def _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]:
        params = {
            "api_key": self.runtime.credentials["serpapi_api_key"],
            "q": tool_parameters["query"],
            "engine": "google",
            "google_domain": "google.com",
            "gl": "us",
            "hl": "en",
        }

        response = requests.get(url=SERP_API_URL, params=params, timeout=5)
        response.raise_for_status()
        valuable_res = self._parse_response(response.json())
        
        yield self.create_json_message(valuable_res)

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

4. 完成工具供应商代码

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

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

from typing import Any

from dify_plugin import ToolProvider
from dify_plugin.errors.tool import ToolProviderCredentialValidationError
from tools.google_search import GoogleSearchTool

class GoogleProvider(ToolProvider):
    def _validate_credentials(self, credentials: dict[str, Any]) -> None:
        try:
            for _ in GoogleSearchTool.from_credentials(credentials).invoke(
                tool_parameters={"query": "test", "result_type": "link"},
            ):
                pass
        except Exception as e:
            raise ToolProviderCredentialValidationError(str(e))

调试插件

接下来需测试插件是否可以正常运行。Dify 提供远程调试方式，前往“插件管理”页获取调试 Key 和远程服务器地址。

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

.env 文件

INSTALL_METHOD=remote
REMOTE_INSTALL_HOST=localhost
REMOTE_INSTALL_PORT=5003
REMOTE_INSTALL_KEY=****-****-****-****-****

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

打包插件

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

dify plugin package ./google

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

发布插件

现在可以将它上传至 Dify Plugins 代码仓库来发布你的插件了！上传前，请确保你的插件遵循了插件发布规范。审核通过后，代码将合并至主分支并自动上线至 Dify Marketplace。

探索更多

快速开始：

• 开发 Extension 类型插件

• 开发 Model 类型插件

• Bundle 类型插件：将多个插件打包

插件接口文档：

• Manifest 结构

• Endpoint 详细定义

• 反向调用 Dify 能力

• 工具

• 模型

• 扩展 Agent 策略