ツールプラグイン

Google Search を例に、初期化からパッケージングまで Dify ツールプラグインを開発します

このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。

ツールは、Chatflow、Workflow、Agent アプリケーションから呼び出せるサードパーティサービスです。オンライン検索や画像生成などの機能で Dify アプリケーションを拡張します。

本ガイドにおける ツールプラグイン とは、ツールプロバイダーファイル、機能コード、および関連する構造を含む完全なプロジェクトです。ツールプロバイダーは複数のツールをまとめることができ、各ツールはそれぞれ独立した機能を提供します。

- Tool Provider
    - Tool A
    - Tool B

本ガイドでは、Google Search を例にツールプラグインの開発手順を説明します。

前提条件

• Dify プラグインスキャフォールディングツール
• Python 環境（バージョン 3.12）

スキャフォールディングツールのセットアップについては、開発ツールの初期化 を参照してください。

新しいプロジェクトの作成

スキャフォールディングコマンドラインツールを実行して、新しい Dify プラグインプロジェクトを作成します。

./dify-plugin-darwin-arm64 plugin init

バイナリファイルを dify に名前変更し、/usr/local/bin パスにコピーした場合は、以下のコマンドを実行して新しいプラグインプロジェクトを作成できます：

dify plugin init

以下の例では dify をコマンドとして使用します。問題が発生した場合は、dify をコマンドラインツールのパスに置き換えてください。

プラグインタイプとテンプレートの選択

スキャフォールディングツールの各テンプレートは、完全なコードプロジェクトです。この例では Tool プラグインを選択します。

すでにプラグイン開発に精通しており、テンプレートが不要な場合は、一般仕様 ガイドを参照して、任意のタイプのプラグインを構築できます。

プラグイン権限の設定

プラグインには、Dify プラットフォームからデータを読み取る権限も必要です。このサンプルプラグインに以下の権限を付与します：

• Tools
• Apps
• 永続ストレージを有効にし、デフォルトサイズを割り当てる
• Endpoints の登録を許可

ターミナルで矢印キーを使用して権限を選択し、Tab キーで権限を付与します。

すべての権限項目をチェックした後、Enter を押してプラグインの作成を完了します。システムが自動的にプラグインプロジェクトコードを生成します。

ツールプラグインの開発

1. ツールプロバイダーファイルの作成

ツールプロバイダーファイルは YAML ファイルで、プラグインの基本設定として機能し、ツールに必要な認証情報を提供します。

プラグインテンプレートプロジェクトの /provider ディレクトリに移動し、YAML ファイルを google.yaml に名前変更します。このファイルは、ツールプロバイダーの名前、アイコン、作者などの詳細情報を記述し、プラグインのインストール時に表示されます。

サンプルコード：

identity: # Basic information of the tool provider
    author: Your-name # Author
    name: google # Name, unique, cannot have the same name as other providers
    label: # Label, for frontend display
        en_US: Google # English label
        zh_Hans: Google # Chinese label
    description: # Description, for frontend display
        en_US: Google # English description
        zh_Hans: Google # Chinese description
    icon: icon.svg # Tool icon, needs to be placed in the _assets folder
    tags: # Tags, for frontend display
        - search

ファイルパスが /tools ディレクトリにあることを確認してください。完全なパスは以下の通りです：

plugins:
    tools:
        - 'google.yaml'

google.yaml は、プラグインプロジェクト内の絶対パスで参照する必要があります。この例では、プロジェクトのルートディレクトリに配置されています。YAML ファイル内の 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'

2. サードパーティサービス認証情報の追加

この例では、利便性のためサードパーティサービス 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: #Add credentials_for_provider field
    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: Please enter your SerpApi API key
        help:
            en_US: Get your SerpApi API key from SerpApi
            zh_Hans: Get your SerpApi API key from SerpApi
        url: https://serpapi.com/manage-api-key
tools:
    - tools/google_search.yaml
extra:
    python:
        source: google.py

• credentials_for_provider のサブレベル構造は、一般仕様 の要件を満たす必要があります。
• プロバイダーに含まれるツールを指定します。この例では、tools/google_search.yaml という 1 つのファイルのみを含みます。
• プロバイダーは基本情報のほかにコードロジックが必要なため、その実装ファイルを指定します。この例では google.py を使用しますが、ここでは実装せず、先に google_search ツールのコードを記述します。

3. ツールYAMLファイルの記入

ツールプラグインは複数のツールを含むことができ、各ツールはそれぞれの YAML ファイルで基本情報、パラメータ、出力を記述します。

引き続き GoogleSearch ツールを例として、/tools フォルダに新しい google_search.yaml ファイルを作成します。

identity:
    name: google_search
    author: Dify
    label:
        en_US: GoogleSearch
        zh_Hans: Google Search
        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: A tool for performing a Google SERP search and extracting snippets and webpages. Input should be a search query.
        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: Query string
          pt_BR: Query string
      human_description:
          en_US: used for searching
          zh_Hans: used for searching web content
          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 がパラメータを理解できるよう、できるだけ詳細に記述してください。

4. ツールコードの記述

ツールの設定が完了したら、ツールのロジックを実装するコードを記述します。/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 データを返します。返却データタイプの詳細については、プラグインのリモートデバッグ と 永続ストレージ KV を参照してください。

5. ツールプロバイダーコードの完成

最後に、プロバイダーの認証情報検証ロジックを実装します。検証が失敗した場合、コードは 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 はリモートデバッグを提供しており、テスト環境でプラグインの機能を素早く検証できます。

プラグイン管理 ページに移動して、リモートサーバーアドレスとデバッグキーを取得します。

プラグインプロジェクトに戻り、.env.example ファイルをコピーして .env に名前変更し、リモートサーバーアドレスとデバッグキーを入力します。

.envファイル：

INSTALL_METHOD=remote
REMOTE_INSTALL_URL=debug.dify.ai:5003
REMOTE_INSTALL_KEY=********-****-****-****-************

python -m main を実行してプラグインを起動します。プラグイン ページで、プラグインがワークスペースにインストールされていることを確認でき、チームの他のメンバーもアクセスできます。

プラグインのパッケージング（オプション）

プラグインが正常に動作したら、以下のコマンドでプラグインをパッケージ化して名前を付けます。実行すると、現在のフォルダに google.difypkg ファイルが生成されます。これが最終的なプラグインパッケージです。

# Replace ./google with the actual path of the plugin project

dify plugin package ./google

おめでとうございます。ツールプラグインの開発、デバッグ、パッケージングが完了しました。

プラグインの公開（オプション）

プラグインを Dify マーケットプレイスに公開するには、プラグインが Dify マーケットプレイスへの公開 の仕様に従っていることを確認してください。レビューに合格すると、コードはメインブランチにマージされ、自動的に Dify マーケットプレイス で公開されます。

全体の手順については、公開の概要 を参照してください。

さらに探索

クイックスタート

• 拡張プラグインの開発
• モデルプラグインの開発
• バンドルプラグイン：複数のプラグインのパッケージング

プラグインインターフェースドキュメント

• 一般仕様：マニフェスト構造とツール仕様。
• Endpoint：詳細な Endpoint の定義。
• リバース呼び出し：Dify 機能のリバース呼び出し。
• モデルスキーマ：モデル。
• Agent プラグイン：Agent 戦略の拡張。

次のステップ

• プラグインのリモートデバッグ：より高度なデバッグテクニックを学びます。
• 永続ストレージ：プラグインでデータストレージを使用します。
• Slack Bot プラグイン開発例：より複雑なプラグイン開発ケース。
• ツールプラグイン：ツールプラグインの高度な機能。