このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。
ツールは、Chatflow、Workflow、Agent アプリケーションから呼び出せるサードパーティサービスです。オンライン検索や画像生成などの機能で Dify アプリケーションを拡張します。
本ガイドにおける ツールプラグイン とは、ツールプロバイダーファイル、機能コード、および関連する構造を含む完全なプロジェクトです。ツールプロバイダーは複数のツールをまとめることができ、各ツールはそれぞれ独立した機能を提供します。
- Tool Provider
- Tool A
- Tool B
前提条件
- Dify プラグインスキャフォールディングツール
- Python 環境（バージョン 3.12）
スキャフォールディングツールのセットアップについては、開発ツールの初期化 を参照してください。
新しいプロジェクトの作成
スキャフォールディングコマンドラインツールを実行して、新しい Dify プラグインプロジェクトを作成します。
./dify-plugin-darwin-arm64 plugin init
dify に名前変更し、/usr/local/bin パスにコピーした場合は、以下のコマンドを実行して新しいプラグインプロジェクトを作成できます：
以下の例では dify をコマンドとして使用します。問題が発生した場合は、dify をコマンドラインツールのパスに置き換えてください。
プラグインタイプとテンプレートの選択
スキャフォールディングツールの各テンプレートは、完全なコードプロジェクトです。この例では Tool プラグインを選択します。
すでにプラグイン開発に精通しており、テンプレートが不要な場合は、一般仕様 ガイドを参照して、任意のタイプのプラグインを構築できます。 プラグイン権限の設定
プラグインには、Dify プラットフォームからデータを読み取る権限も必要です。このサンプルプラグインに以下の権限を付与します：
- Tools
- Apps
- 永続ストレージを有効にし、デフォルトサイズを割り当てる
- Endpoints の登録を許可
ターミナルで矢印キーを使用して権限を選択し、Tab キーで権限を付与します。
ツールプラグインの開発
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 マーケットプレイス で公開されます。
全体の手順については、公開の概要 を参照してください。
さらに探索
クイックスタート
プラグインインターフェースドキュメント
次のステップ
