Skip to main content

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

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

ツールプラグインの例

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

ツールプラグインの構造

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

前提条件#

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

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

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

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

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

Note

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

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

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

Tip

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

プラグインタイプ：ツール

プラグイン権限の設定#

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

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

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

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

プラグイン権限

ツールプラグインの開発#

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

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

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

サンプルコード：

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

google.yaml は、プラグインプロジェクト内の絶対パスで参照する必要があります。この例では、プロジェクトのルートディレクトリに配置されています。YAML ファイル内の identity には、作者、名前、ラベル、説明、アイコンなど、ツールプロバイダーの基本情報が含まれます。

  • アイコンは添付リソースとして、プロジェクトのルートディレクトリの _assets フォルダに配置する必要があります。
  • タグは、ユーザーがカテゴリ別にプラグインを見つけるのに役立ちます。以下は現在サポートされているすべてのタグです：

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

この例では、利便性のためサードパーティサービス SerpApi が提供する Google Search API を使用します。SerpApi は API Key が必要なため、YAML ファイルに credentials_for_provider フィールドを追加します。

完全なコード：

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

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

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

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

  • identity：名前、作者、ラベル、説明などのツールの基本情報。
  • parameters：パラメータリスト。

    • name（必須）：パラメータ名。ツールのパラメータ内で一意である必要があります。

    • type（必須）：パラメータタイプ。値は次の 3 種類に分かれます。

      • 単純な値：string、number、boolean、any。
      • 選択肢：options から固定のドロップダウンを作る select、設定時にプラグインが選択肢を提供する dynamic-select、および checkbox。
      • セレクターとアップロード：
        • secret-input は機密情報に使い、暗号化入力ボックスとして表示されます。
        • file と files はファイルのアップロードに使います。
        • app-selector と model-selector はワークスペースのアプリやモデルの選択に使います。
        • date は単一の日付に使い、日付ピッカーとして表示され、値は YYYY-MM-DD 形式の文字列として渡されます。
        • date-range は開始日と終了日に使い、日付範囲ピッカーとして表示され、値は start と end の日付文字列を含むオブジェクトとして渡されます。

      このほかに array と object がありますが、これらはプラグインが宣言するパラメータではなく MCP サーバーツール向けです。system-files は非推奨です。

    • label（必須）：パラメータラベル。フロントエンドに表示されます。

    • form（必須）：フォームタイプ。llm または form のいずれか。

      • Agent アプリケーションでは、llm はパラメータを LLM が自動的に推論することを意味し、form はツールを使用する前にパラメータを事前設定できることを意味します。
      • Workflow アプリケーションでは、llm と form の両方のパラメータをフロントエンドで入力しますが、llm パラメータはツールノードの入力変数として使用されます。

    • required（任意）：パラメータが必須かどうか。

      • llm モードでは、必須パラメータは Agent が推論する必要があります。
      • form モードでは、必須パラメータは会話開始前にフロントエンドで入力する必要があります。

    • options（任意）：パラメータオプション。

      • llm モードでは、Dify はすべてのオプションを LLM に渡し、LLM がそれらに基づいて推論できます。
      • form モードでは、type が select の場合にフロントエンドがオプションを表示します。

    • multiple（任意）：select と dynamic-select パラメータで true にすると、複数のオプションを選択できます。値はオプション値のリストとして渡され、default を設定する場合はリストにする必要があります。

    • default（任意）：デフォルト値。

    • min（任意）：最小値。パラメータタイプが number の場合に適用されます。

    • max（任意）：最大値。パラメータタイプが number の場合に適用されます。

    • human_description（任意）：フロントエンドに表示される説明。複数言語をサポートします。

    • placeholder（任意）：入力フィールドのヒントテキスト。フォームタイプが form でパラメータタイプが string、number、secret-input の場合に適用されます。複数言語をサポートします。

    • llm_description（任意）：LLM に渡される説明。LLM がパラメータを理解できるよう、できるだけ詳細に記述してください。

4. ツールコードの記述#

ツールの設定が完了したら、ツールのロジックを実装するコードを記述します。/tools ディレクトリに google_search.py を作成し、以下の内容を記述します：

このコードは serpapi にリクエストを送信し、self.create_json_message を使用してフォーマットされた JSON データを返します。返却データタイプの詳細については、プラグインのリモートデバッグ と 永続ストレージ KV を参照してください。

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

最後に、プロバイダーの認証情報検証ロジックを実装します。検証が失敗した場合、コードは ToolProviderCredentialValidationError 例外を発生させます。検証が成功すると、google_search ツールサービスが正しくリクエストされます。

/provider ディレクトリに google.py ファイルを作成し、以下の内容を記述します：

プラグインのデバッグ#

開発が完了したら、プラグインが正常に動作するかどうかをテストします。Dify はリモートデバッグを提供しており、テスト環境でプラグインの機能を素早く検証できます。

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

リモートデバッグキー

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

.envファイル：

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

Python -M Mainコマンドを実行してプラグインを起動します

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

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

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

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

プラグインを Dify マーケットプレイスに公開するには、マーケットプレイス向けの準備と検証要件 を満たしていることを確認してください。レビューに合格すると、パッケージがメインブランチにマージされ、マーケットプレイスのパイプラインから公開されます。

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

さらに探索#

クイックスタート#

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

次のステップ#