クイック統合ツール

ここでは、GoogleSearchを例にとって、ツールを迅速に接続する方法をご紹介します。

1. ツールプロバイダーのyamlを準備

イントロダクション

このyamlには、プロバイダーの名前、アイコン、著者などの詳細情報が含まれており、前端で柔軟に表示できるようにします。

サンプル

core/tools/provider/builtinフォルダーにgoogleモジュール（フォルダー）を作成し、その中にgoogle.yamlを作成します。名前はモジュール名と一致する必要があります。

以降、このツールに関するすべての操作はこのモジュール内で行います。

identity: # ツールプロバイダーの基本情報
  author: Dify # 著者
  name: google # 名前、唯一無二で、他のプロバイダーと重複してはいけません
  label: # ラベル、前端表示用
    en_US: Google # 英語ラベル
    zh_Hans: Google # 中国語ラベル
  description: # 説明、前端表示用
    en_US: Google # 英語説明
    zh_Hans: Google # 中国語説明
  icon: icon.svg # アイコン、現在のモジュールの_assetsフォルダーに配置する必要があります

• identity フィールドは必須です。著者、名前、ラベル、説明、アイコンなどの基本情報が含まれています。

  • アイコンは現在のモジュールの_assetsフォルダーに配置する必要があります。参考例：api/core/tools/provider/builtin/google/_assets/icon.svg

    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="25" viewBox="0 0 24 25" fill="none">
      <path d="M22.501 12.7332C22.501 11.8699 22.4296 11.2399 22.2748 10.5865H12.2153V14.4832H18.12C18.001 15.4515 17.3582 16.9099 15.9296 17.8898L15.9096 18.0203L19.0902 20.435L19.3106 20.4565C21.3343 18.6249 22.501 15.9298 22.501 12.7332Z" fill="#4285F4"/>
      <path d="M12.214 23C15.1068 23 17.5353 22.0666 19.3092 20.4567L15.9282 17.8899C15.0235 18.5083 13.8092 18.9399 12.214 18.9399C9.38069 18.9399 6.97596 17.1083 6.11874 14.5766L5.99309 14.5871L2.68583 17.0954L2.64258 17.2132C4.40446 20.6433 8.0235 23 12.214 23Z" fill="#34A853"/>
      <path d="M6.12046 14.5766C5.89428 13.9233 5.76337 13.2233 5.76337 12.5C5.76337 11.7766 5.89428 11.0766 6.10856 10.4233L6.10257 10.2841L2.75386 7.7355L2.64429 7.78658C1.91814 9.20993 1.50146 10.8083 1.50146 12.5C1.50146 14.1916 1.91814 15.7899 2.64429 17.2132L6.12046 14.5766Z" fill="#FBBC05"/>
      <path d="M12.2141 6.05997C14.2259 6.05997 15.583 6.91163 16.3569 7.62335L19.3807 4.73C17.5236 3.03834 15.1069 2 12.2141 2C8.02353 2 4.40447 4.35665 2.64258 7.78662L6.10686 10.4233C6.97598 7.89166 9.38073 6.05997 12.2141 6.05997Z" fill="#EB4335"/>
    </svg>

2. プロバイダーの認証情報を準備

GoogleはSerpApiが提供するAPIを使用しているため、SerpApiのAPIキーが必要です。一方で、wikipediaのようなツールでは認証情報フィールドを記入する必要はありません。参考例：api/core/tools/provider/builtin/wikipedia/wikipedia.yaml

identity:
  author: Dify
  name: wikipedia
  label:
    en_US: Wikipedia
    zh_Hans: 维基百科
    pt_BR: Wikipedia
  description:
    en_US: Wikipedia is a free online encyclopedia, created and edited by volunteers around the world.
    zh_Hans: 维基百科是一个由全世界的志愿者创建和编辑的免费在线百科全书。
    pt_BR: Wikipedia is a free online encyclopedia, created and edited by volunteers around the world.
  icon: icon.svg
credentials_for_provider:

認証情報フィールドを設定すると以下のようになります：

identity:
  author: Dify
  name: google
  label:
    en_US: Google
    zh_Hans: Google
  description:
    en_US: Google
    zh_Hans: Google
  icon: icon.svg
credentials_for_provider: # 認証情報フィールド
  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: 请输入你的 SerpApi API key # 中国語プレースホルダー
    help: # 認証情報フィールドヘルプテキスト
      en_US: Get your SerpApi API key from SerpApi # 英語ヘルプテキスト
      zh_Hans: 从 SerpApi 获取你的 SerpApi API key # 中国語ヘルプテキスト
    url: https://serpapi.com/manage-api-key # 認証情報フィールドヘルプリンク

• type：認証情報フィールドタイプ、現在はsecret-input、text-input、selectの3種類をサポートしており、それぞれパスワード入力、テキスト入力、選択ボックスに対応します。secret-inputの場合、前端で入力内容が非表示となり、後端で入力内容が暗号化されます。

3. ツールのyamlを準備

一つのプロバイダーには複数のツールがあり、それぞれのツールには基本情報、パラメーター、出力などを記述したyamlファイルが必要です。

GoogleSearchを例にとって、googleモジュール内にtoolsモジュールを作成し、その中にtools/google_search.yamlを作成します。内容は以下の通りです。

identity: # ツールの基本情報
  name: google_search # ツール名、唯一無二で、他のツールと重複してはいけません
  author: Dify # 著者
  label: # ラベル、前端表示用
    en_US: GoogleSearch # 英語ラベル
    zh_Hans: 谷歌搜索 # 中国語ラベル
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: 一个用于执行 Google SERP 搜索并提取片段和网页的工具。输入应该是一个搜索查询。
  llm: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query. # LLMに渡す紹介文。LLMがこのツールをよりよく理解して使用できるように、ここにはできるだけ詳細な情報を書いておくことをお勧めします。
parameters: # パラメーターリスト
  - name: query # パラメーター名
    type: string # パラメータータイプ
    required: true # 必須かどうか
    label: # パラメーターラベル
      en_US: Query string # 英語ラベル
      zh_Hans: 查询语句 # 中国語ラベル
    human_description: # 前端表示用の紹介文、複数言語対応
      en_US: used for searching
      zh_Hans: 用于搜索网页内容
    llm_description: key words for searching # LLMに渡す紹介文。同上、LLMがこのパラメーターをよりよく理解できるように、できるだけ詳細な情報を書いておくことをお勧めします。
    form: llm # フォームタイプ。llmはこのパラメーターがエージェントによって推論されるべきであることを示します。前端はこのパラメーターを表示しません。
  - name: result_type
    type: select # パラメータータイプ
    required: true
    options: # 選択ボックスオプション
      - value: text
        label:
          en_US: text
          zh_Hans: 文本
      - value: link
        label:
          en_US: link
          zh_Hans: 链接
    default: link
    label:
      en_US: Result type
      zh_Hans: 结果类型
    human_description:
      en_US: used for selecting the result type, text or link
      zh_Hans: 用于选择结果类型，使用文本还是链接进行展示
    form: form # フォームタイプ。formはこのパラメーターが対話開始前にユーザーによって前端で入力されるべきであることを示します。

• identity フィールドは必須です。名前、著者、ラベル、説明などの基本情報が含まれています。

• parameters パラメーターリスト

  • name パラメーター名、唯一無二で、他のパラメーターと重複してはいけません。

  • type パラメータータイプ。現在はstring、number、boolean、selectの4種類をサポートしており、文字列、数値、ブール値、選択ボックスに対応します。

  • required 必須かどうか

    • llmモードでは、パラメーターが必須の場合、エージェントは必ずこのパラメーターを推論する必要があります。

    • formモードでは、パラメーターが必須の場合、ユーザーは対話開始前に前端でこのパラメーターを入力する必要があります。

  • options パラメーターオプション

    • llmモードでは、DifyはすべてのオプションをLLMに渡し、LLMはこれらのオプションを基に推論します。

    • formモードでは、typeがselectの場合、前端にこれらのオプションが表示されます。

  • default デフォルト値

  • label パラメーターラベル、前端表示用

  • human_description 前端表示用の紹介文、複数言語対応

  • llm_description LLMに渡す紹介文。LLMがこのパラメーターをよりよく理解できるように、できるだけ詳細な情報を書いておくことをお勧めします。

  • form フォームタイプ。現在はllm、formの2種類をサポートしており、それぞれエージェントによる推論と前端入力に対応します。

4. ツールコードを準備

ツールの設定が完了したら、次にツールのロジックを実装するためのコードを作成します。

google/toolsモジュール内にgoogle_search.pyを作成し、以下の内容を記述します。

from core.tools.tool.builtin_tool import BuiltinTool
from core.tools.entities.tool_entities import ToolInvokeMessage

from typing import Any, Dict, List, Union

class GoogleSearchTool(BuiltinTool):
    def _invoke(self, 
                user_id: str,
               tool_Parameters: Dict[str, Any], 
        ) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
        """
            invoke tools
        """
        query = tool_Parameters['query']
        result_type = tool_Parameters['result_type']
        api_key = self.runtime.credentials['serpapi_api_key']
        # TODO: search with serpapi
        result = SerpAPI(api_key).run(query, result_type=result_type)

        if result_type == 'text':
            return self.create_text_message(text=result)
        return self.create_link_message(link=result)

パラメーター

ツールの全体のロジックは_invokeメソッド内にあります。このメソッドはuser_idとtool_Parametersの2つのパラメーターを受け取ります。これらはそれぞれユーザーIDとツールパラメーターを表します。

返却データ

ツールの返却時に、1つまたは複数のメッセージを返すことができます。ここでは、1つのメッセージを返す例を示しており、create_text_messageとcreate_link_messageを使用してテキストメッセージまたはリンクメッセージを作成しています。

5. プロバイダーコードを準備

最後に、プロバイダーモジュール内にプロバイダークラスを作成し、認証情報の検証ロジックを実装します。認証情報の検証に失敗した場合、ToolProviderCredentialValidationError例外が投げられます。

googleモジュール内にgoogle.pyを作成し、以下の内容を記述します。

from core.tools.entities.tool_entities import ToolInvokeMessage, ToolProviderType
from core.tools.tool.tool import Tool
from core.tools.provider.builtin_tool_provider import BuiltinToolProviderController
from core.tools.errors import ToolProviderCredentialValidationError

from core.tools.provider.builtin.google.tools.google_search import GoogleSearchTool

from typing import Any, Dict

class GoogleProvider(BuiltinToolProviderController):
    def _validate_credentials(self, credentials: Dict[str, Any]) -> None:
        try:
            # 1. この場所でGoogleSearchTool()をインスタンス化し、GoogleSearchToolのyaml設定を自動的に読み込みますが、この時点では認証情報が内部にありません。
            # 2. その後、fork_tool_runtimeメソッドを使用して、現在の認証情報をGoogleSearchToolに渡します。
            # 3. 最後にinvokeします。パラメーターはGoogleSearchToolのyamlに記載されたパラメーター規則に従って渡します。
            GoogleSearchTool().fork_tool_runtime(
                meta={
                    "credentials": credentials,
                }
            ).invoke(
                user_id='',
                tool_parameters={
                    "query": "test",
                    "result_type": "link"
                },
            )
        except Exception as e:
            raise ToolProviderCredentialValidationError(str(e))

完成

上記のステップが完了すると、このツールがフロントエンドに表示され、エージェントでこのツールを使用することができます。

もちろん、google検索は資格情報を必要とするため、使用前にフロントエンドで資格情報を設定する必要があります。