Tool Plugin¶

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

ツールとは、Chatflow / ワークフロー / エージェントタイプのアプリケーションから呼び出すことができるサードパーティサービスを指し、FlexAIアプリケーションを強化するための完全なAPI実装機能を提供します。例えば、オンライン検索、画像生成などの追加機能を追加できます。

Tool Plugin Example

この記事では、「ツールプラグイン」とは、ツールプロバイダーファイル、機能コード、およびその他の構造を含む完全なプロジェクトを指します。ツールプロバイダーには複数のツール（単一のツール内で提供される追加機能として理解できます）を含めることができ、構造は以下の通りです：

- Tool Provider
    - Tool A
    - Tool B

Tool Plugin Structure

この記事では、Google Searchを例として、ツールプラグインを素早く開発する方法を説明します。

前提条件¶

FlexAIプラグインスキャフォールディングツール
Python環境、バージョン ≥ 3.12

プラグイン開発スキャフォールディングツールの準備方法の詳細については、開発ツールの初期化を参照してください。初めてプラグインを開発する場合は、まずFlexAIプラグイン開発：Hello Worldガイドを読むことをお勧めします。

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

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

./flexai-plugin-darwin-arm64 plugin init

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

dify plugin init

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

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

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

すでにプラグイン開発に精通しており、テンプレートに依存する必要がない場合は、一般仕様ガイドを参照して、さまざまなタイプのプラグインの開発を完了できます。

Plugin Type: Tool

プラグイン権限の設定¶

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

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

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

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

Plugin Permissions

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

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

ツールプロバイダーファイルはyaml形式のファイルで、ツールプラグインの基本設定エントリとして理解でき、ツールに必要な認証情報を提供するために使用されます。

プラグインテンプレートプロジェクトの/providerパスに移動し、yamlファイルをgoogle.yamlに名前変更します。この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フィールドは以下のように説明されます：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: FlexAI
    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ファイルのみが含まれています。
プロバイダーとして、基本情報を定義するだけでなく、そのコードロジックの一部を実装する必要があるため、その実装ロジックを指定する必要があります。この例では、機能のコードファイルをgoogle.pyに配置しますが、まだ実装せず、最初にgoogle_searchのコードを書きます。

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

ツールプラグインには複数のツール機能を持たせることができ、各ツール機能には、ツール機能の基本情報、パラメータ、出力などを記述するyamlファイルが必要です。

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

identity:
    name: google_search
    author: FlexAI
    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の5つのタイプをサポートしており、それぞれ文字列、数値、ブール値、ドロップダウン、暗号化入力ボックスに対応しています。機密情報にはsecret-inputタイプを使用してください。
- label（必須）パラメータラベル、フロントエンド表示用。
- form（必須）フォームタイプ、現在llm、formの2つのタイプをサポートしています。
  - エージェントアプリケーションでは、llmはパラメータがLLM自体によって推論されることを意味し、formはこのツールを使用するために事前にパラメータを設定できることを意味します。
  - ワークフローアプリケーションでは、llmとformの両方をフロントエンドで入力する必要がありますが、llmパラメータはツールノードの入力変数として使用されます。
- required必須かどうか
  - llmモードでは、パラメータが必須の場合、エージェントはこのパラメータを推論する必要があります。
  - formモードでは、パラメータが必須の場合、ユーザーは会話開始前にフロントエンドでこのパラメータを入力する必要があります。
- optionsパラメータオプション
  - llmモードでは、FlexAIはすべてのオプションをモデルに渡し、モデルはこれらのオプションに基づいて推論できます。
  - formモードでは、typeがselectの場合、フロントエンドはこれらのオプションを表示します。
- defaultデフォルト値。
- min最小値、パラメータタイプがnumberの場合に設定できます。
- max最大値、パラメータタイプがnumberの場合に設定できます。
- human_descriptionフロントエンド表示用の説明、複数言語をサポート。
- placeholder入力フィールドのプロンプトテキスト、フォームタイプがformでパラメータタイプがstring、number、secret-inputの場合に設定でき、複数言語をサポート。
- llm_descriptionモデルに渡される説明。モデルがこのパラメータをより良く理解できるように、このパラメータに関するできるだけ詳細な情報をここに記述して、モデルがパラメータを理解できるようにしてください。

4. ツールコードの準備¶

ツールの設定情報を入力した後、ツールの機能のコードを書き始め、ツールの論理的な目的を実装できます。/toolsディレクトリにgoogle_search.pyを作成し、以下の内容を記述します：

from collections.abc import Generator
from typing import Any


from flexai_plugin import Tool
from flexai_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 flexai_plugin import ToolProvider
from flexai_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))

プラグインのデバッグ¶

プラグインの開発が完了したら、プラグインが正常に機能するかどうかをテストする必要があります。FlexAIは、テスト環境でプラグインの機能を素早く検証するのに役立つ便利なリモートデバッグ方法を提供しています。

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

Remote Debug Key

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

.envファイル：

INSTALL_METHOD=remote
REMOTE_INSTALL_URL=debug.flexai.com.tr:5003
REMOTE_INSTALL_KEY=********-****-****-****-************

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

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

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

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

dify plugin package ./google

おめでとうございます！ツールタイプのプラグインの開発、デバッグ、パッケージングの全プロセスを完了しました！

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

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

公開の概要

さらに探索¶

クイックスタート：¶

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

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

次の学習ステップ¶

プラグインのリモートデバッグ - より高度なデバッグテクニックを学ぶ
永続ストレージ - プラグインでのデータストレージの使用方法を学ぶ
Slack Botプラグイン開発例 - より複雑なプラグイン開発ケースを見る
ツールプラグイン - ツールプラグインの高度な機能を探索

{/ Contributing Section DO NOT edit this section! It will be automatically generated by the script. /}

Edit this page | Report an issue