ツール型プラグイン
Last updated
Last updated
Tool（ツール）プラグインは、チャットフロー、ワークフロー、エージェントといったアプリタイプから参照できる外部ツールであり、Difyアプリの機能を拡張するために使用されます。例えば、アプリにオンライン検索機能や画像生成機能を追加するといったことが可能です。ツールプラグインは、包括的なツールセットとAPI実装機能を提供します。
本篇では、「ツールプラグイン」とは、ツールプロバイダーファイル、機能コード、およびその他の関連コンポーネントを含む、一揃いのプロジェクトを指します。ツールプロバイダーは複数のツール（これは、単一のツールが提供する追加機能と解釈できます）を含むことがあり、以下の構造で構成されます。
この記事では、GoogleSearchを例に、ツールプラグインを迅速に開発する方法をご紹介します。
Dify プラグインの Scaffolding（スキャフォールディング）ツール
Python 環境 (バージョン 3.12 以上)
Scaffoldingのコマンドラインツールを実行し、新しいDifyプラグインプロジェクトを作成します。
バイナリファイルの名前を dify に変更し、/usr/local/bin ディレクトリにコピーした場合は、次のコマンドを実行して新しいプラグインプロジェクトを作成できます。
以下、コマンドラインツール
difyを使用します。もし問題が発生した場合は、difyコマンドを、お使いのツールの実行パスに置き換えてください。
プラグインには、ツール、モデル、そしてエクステンションの3種類があります。SDK内のすべてのテンプレートには、完全なコードプロジェクトが付属しています。以下の部分では、ツールプラグインテンプレートを例として使用します。
プラグインを正常に接続するには、Difyプラットフォームの権限を読み取る必要があります。このサンプルツールプラグインには、以下の権限を付与する必要があります。
ツール
アプリ
永続的ストレージジストレージの有効化、デフォルトサイズのストレージの割り当て
エンドポイントの登録許可
ターミナルで方向キーを使って権限を選択し、"タグ"のブタンで権限を付与してください。
すべての権限項目にチェックを入れたら、Enterキーを押してプラグインの作成を完了させてください。システムが自動的にプラグインプロジェクトのコードを生成します。
ツールプロバイダーファイルは、ツールプラグインの基本的な設定ファイルとして機能し、ツールが利用するために必要な認証情報を提供します。このセクションでは、この yaml ファイルの記述方法について説明します。
/provider ディレクトリに移動し、その中にある yaml ファイルの名前を google.yaml に変更します。この yaml ファイルには、プロバイダー名、アイコン、作成者など、ツールプロバイダーに関する情報が含まれます。これらの情報は、プラグインのインストール時に表示されます。
サンプルコード
identity には、作成者、名前、ラベル、説明、アイコンなど、ツールプロバイダーの基本的な情報が含まれます。
アイコンは添付ファイルとして扱い、プロジェクトのルートディレクトリにある _assets フォルダに配置する必要があります。
タグは、ユーザーがプラグインをカテゴリ別にすばやく検索するのに役立ちます。現在サポートされているすべてのタグは以下のとおりです。
ファイルパスが /tools ディレクトリにあることを確認してください。完全なパスは次のようになります。
ここで、google.yaml ファイルのパスは、プラグインプロジェクト内の絶対パスで指定する必要があります。
サードパーティサービスの認証情報を設定する
開発を容易にするため、サードパーティサービスである SerpApi が提供する Google Search API を利用することにしました。SerpApi を使用するには API キーが必要となるため、yaml ファイルに credentials_for_provider フィールドを追加する必要があります。
完全なコードは次のとおりです。
このプロバイダーに含まれるツールを指定する必要があります。この例では、tools/google_search.yaml ファイルが 1 つだけ含まれています。
プロバイダーは、基本情報を定義するだけでなく、コードによるロジックの実装も必要です。そのため、実装ロジックを指定する必要があります。この例では、機能のコードファイルは google.py に配置されていますが、ここではまだ実装せず、先に google_search のコードを作成します。これは、google_search の機能が google.py の実装に依存するためです。
1つのツールベンダーが複数のツールを提供することがあります。各ツールは、その基本的な情報、パラメータ、出力などを記述した yaml ファイルによって定義される必要があります。
ここでは、GoogleSearch ツールを例にとり、/tools フォルダに新しい google_search.yaml ファイルを作成する手順を見ていきましょう。
identity: ツールの名前、作成者、ラベル、説明といった基本的な情報が含まれます。
parameters: パラメータに関する設定項目です。各項目の詳細は以下の通りです。
name (必須): パラメータ名。一意である必要があり、他のパラメータ名との重複は許容されません。
type (必須): パラメータの型。string (文字列)、number (数値)、boolean (真偽値)、select (選択式ドロップダウン)、secret-input (暗号化入力フィールド)、file (ファイル)、files (ファイルセット)、model-selector (モデル選択)、app-selector (アプリケーション選択) の9種類がサポートされています。機密性の高い情報を取り扱う場合は、必ず secret-input 型を使用してください。
label (必須): パラメータのラベル。フロントエンドに表示される際に用いられます。
form (必須): フォームの種類。llm と form の2種類がサポートされています。
Agentアプリケーションにおいて、llm はパラメータがLLMによって推論されることを意味し、form はツールを使用する前にユーザーが設定できるパラメータを意味します。
ワークフローアプリケーションにおいては、llm と form の両方のパラメータに対してフロントエンドでの入力が求められます。ただし、llm パラメータはツールノードの入力変数として機能します。
required: 必須項目であるかどうかを示すフラグです。
llm モードの場合、required が true に設定されたパラメータは、Agentが推論によって値を決定する必要があります。
form モードの場合、required が true に設定されたパラメータは、ユーザーが会話を開始する前にフロントエンドで値を入力する必要があります。
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がパラメータの内容をより深く理解できるよう、できる限り詳細な情報を提供してください。
ツールの設定情報を入力したら、ツールの機能コードを記述し、ツールのロジックを実装します。 /tools ディレクトリに google_search.py を作成し、以下の内容を記述します。
最後に、プロバイダーのコードを実装します。これは、プロバイダーの認証情報を検証するために使用されます。認証情報の検証に失敗すると、ToolProviderCredentialValidationError 例外が発生します。検証に成功すると、google_search ツールサービスが正常にリクエストされます。
/provider ディレクトリに google.py ファイルを作成し、以下のコードを記述します。
プラグインが正常に動作するかテストします。Dify はリモートデバッグをサポートしています。「プラグイン管理」ページで、デバッグキーとリモートサーバーアドレスを取得してください。
プラグインプロジェクトに戻り、.env.example ファイルをコピーして .env にリネームし、取得したリモートサーバーアドレスとデバッグキーを入力します。
.env ファイル
python -m main コマンドを実行してプラグインを起動します。プラグインページで、プラグインがワークスペースにインストールされていることを確認できます。これで、他のチームメンバーもこのプラグインを使用できます。
プラグインが正常に動作することを確認したら、以下のコマンドラインツールを使用してプラグインをパッケージ化し、名前を付けます。実行後、現在のフォルダに google.difypkg ファイルが作成されます。これがプラグインの最終的なパッケージです。
おめでとうございます。これで、ツールタイプのプラグインの開発、デバッグ、パッケージ化の全プロセスが完了しました。
クイックスタート:
プラグインインターフェースドキュメント:
プラグイン開発用のScaffoldingツールの準備方法については、をご参照ください。
プラグイン開発に精通されている方は、各種プラグインの実装にあたり、をご参照ください。
credentials_for_provider の子構造は、 の仕様に準拠する必要があります。
この例では、serpapi にリクエストを送信し、self.create_json_message を使用して json 形式のデータを返しています。その他の戻り値の型については、を参照してください。
にアップロードして、プラグインを公開しましょう。アップロードする前に、プラグインがに準拠していることを確認してください。レビューに合格すると、コードはメインブランチにマージされ、 に自動的に公開されます。
構造
詳細定義
