Underground-Digital/Workflow-Engine
0
1# Quick Tool Integration2 3Here, we will use GoogleSearch as an example to demonstrate how to quickly integrate a tool.4 5## 1. Prepare the Tool Provider yaml6 7### Introduction8 9This yaml declares a new tool provider, and includes information like the provider's name, icon, author, and other details that are fetched by the frontend for display.10 11### Example12 13We need to create a `google` module (folder) under `core/tools/provider/builtin`, and create `google.yaml`. The name must be consistent with the module name.14 15Subsequently, all operations related to this tool will be carried out under this module.16 17```yaml18identity: # Basic information of the tool provider19 author: Dify # Author20 name: google # Name, unique, no duplication with other providers21 label: # Label for frontend display22 en_US: Google # English label23 zh_Hans: Google # Chinese label24 description: # Description for frontend display25 en_US: Google # English description26 zh_Hans: Google # Chinese description27 icon: icon.svg # Icon, needs to be placed in the _assets folder of the current module28 tags:29 - search30 31```32 33- The `identity` field is mandatory, it contains the basic information of the tool provider, including author, name, label, description, icon, etc.34 - The icon needs to be placed in the `_assets` folder of the current module, you can refer to [here](../../provider/builtin/google/_assets/icon.svg).35 - The `tags` field is optional, it is used to classify the provider, and the frontend can filter the provider according to the tag, for all tags, they have been listed below:36 37 ```python38 class ToolLabelEnum(Enum):39 SEARCH = 'search'40 IMAGE = 'image'41 VIDEOS = 'videos'42 WEATHER = 'weather'43 FINANCE = 'finance'44 DESIGN = 'design'45 TRAVEL = 'travel'46 SOCIAL = 'social'47 NEWS = 'news'48 MEDICAL = 'medical'49 PRODUCTIVITY = 'productivity'50 EDUCATION = 'education'51 BUSINESS = 'business'52 ENTERTAINMENT = 'entertainment'53 UTILITIES = 'utilities'54 OTHER = 'other'55 ```56 57## 2. Prepare Provider Credentials58 59Google, as a third-party tool, uses the API provided by SerpApi, which requires an API Key to use. This means that this tool needs a credential to use. For tools like `wikipedia`, there is no need to fill in the credential field, you can refer to [here](../../provider/builtin/wikipedia/wikipedia.yaml).60 61After configuring the credential field, the effect is as follows:62 63```yaml64identity:65 author: Dify66 name: google67 label:68 en_US: Google69 zh_Hans: Google70 description:71 en_US: Google72 zh_Hans: Google73 icon: icon.svg74credentials_for_provider: # Credential field75 serpapi_api_key: # Credential field name76 type: secret-input # Credential field type77 required: true # Required or not78 label: # Credential field label79 en_US: SerpApi API key # English label80 zh_Hans: SerpApi API key # Chinese label81 placeholder: # Credential field placeholder82 en_US: Please input your SerpApi API key # English placeholder83 zh_Hans: 请输入你的 SerpApi API key # Chinese placeholder84 help: # Credential field help text85 en_US: Get your SerpApi API key from SerpApi # English help text86 zh_Hans: 从 SerpApi 获取您的 SerpApi API key # Chinese help text87 url: https://serpapi.com/manage-api-key # Credential field help link88 89```90 91- `type`: Credential field type, currently can be either `secret-input`, `text-input`, or `select` , corresponding to password input box, text input box, and drop-down box, respectively. If set to `secret-input`, it will mask the input content on the frontend, and the backend will encrypt the input content.92 93## 3. Prepare Tool yaml94 95A provider can have multiple tools, each tool needs a yaml file to describe, this file contains the basic information, parameters, output, etc. of the tool.96 97Still taking GoogleSearch as an example, we need to create a `tools` module under the `google` module, and create `tools/google_search.yaml`, the content is as follows.98 99```yaml100identity: # Basic information of the tool101 name: google_search # Tool name, unique, no duplication with other tools102 author: Dify # Author103 label: # Label for frontend display104 en_US: GoogleSearch # English label105 zh_Hans: 谷歌搜索 # Chinese label106description: # Description for frontend display107 human: # Introduction for frontend display, supports multiple languages108 en_US: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query.109 zh_Hans: 一个用于执行 Google SERP 搜索并提取片段和网页的工具。输入应该是一个搜索查询。110 llm: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query. # Introduction passed to LLM, in order to make LLM better understand this tool, we suggest to write as detailed information about this tool as possible here, so that LLM can understand and use this tool111parameters: # Parameter list112 - name: query # Parameter name113 type: string # Parameter type114 required: true # Required or not115 label: # Parameter label116 en_US: Query string # English label117 zh_Hans: 查询语句 # Chinese label118 human_description: # Introduction for frontend display, supports multiple languages119 en_US: used for searching120 zh_Hans: 用于搜索网页内容121 llm_description: key words for searching # Introduction passed to LLM, similarly, in order to make LLM better understand this parameter, we suggest to write as detailed information about this parameter as possible here, so that LLM can understand this parameter122 form: llm # Form type, llm means this parameter needs to be inferred by Agent, the frontend will not display this parameter123 - name: result_type124 type: select # Parameter type125 required: true126 options: # Drop-down box options127 - value: text128 label:129 en_US: text130 zh_Hans: 文本131 - value: link132 label:133 en_US: link134 zh_Hans: 链接135 default: link136 label:137 en_US: Result type138 zh_Hans: 结果类型139 human_description:140 en_US: used for selecting the result type, text or link141 zh_Hans: 用于选择结果类型，使用文本还是链接进行展示142 form: form # Form type, form means this parameter needs to be filled in by the user on the frontend before the conversation starts143 144```145 146- The `identity` field is mandatory, it contains the basic information of the tool, including name, author, label, description, etc.147- `parameters` Parameter list148 - `name` (Mandatory) Parameter name, must be unique and not duplicate with other parameters.149 - `type` (Mandatory) Parameter type, currently supports `string`, `number`, `boolean`, `select`, `secret-input` five types, corresponding to string, number, boolean, drop-down box, and encrypted input box, respectively. For sensitive information, we recommend using the `secret-input` type150 - `label` (Mandatory) Parameter label, for frontend display151 - `form` (Mandatory) Form type, currently supports `llm`, `form` two types.152 - In an agent app, `llm` indicates that the parameter is inferred by the LLM itself, while `form` indicates that the parameter can be pre-set for the tool.153 - In a workflow app, both `llm` and `form` need to be filled out by the front end, but the parameters of `llm` will be used as input variables for the tool node.154 - `required` Indicates whether the parameter is required or not155 - In `llm` mode, if the parameter is required, the Agent is required to infer this parameter156 - In `form` mode, if the parameter is required, the user is required to fill in this parameter on the frontend before the conversation starts157 - `options` Parameter options158 - In `llm` mode, Dify will pass all options to LLM, LLM can infer based on these options159 - In `form` mode, when `type` is `select`, the frontend will display these options160 - `default` Default value161 - `min` Minimum value, can be set when the parameter type is `number`.162 - `max` Maximum value, can be set when the parameter type is `number`.163 - `placeholder` The prompt text for input boxes. It can be set when the form type is `form`, and the parameter type is `string`, `number`, or `secret-input`. It supports multiple languages.164 - `human_description` Introduction for frontend display, supports multiple languages165 - `llm_description` Introduction passed to LLM, in order to make LLM better understand this parameter, we suggest to write as detailed information about this parameter as possible here, so that LLM can understand this parameter166 167 168## 4. Add Tool Logic169 170After completing the tool configuration, we can start writing the tool code that defines how it is invoked.171 172Create `google_search.py` under the `google/tools` module, the content is as follows.173 174```python175from core.tools.tool.builtin_tool import BuiltinTool176from core.tools.entities.tool_entities import ToolInvokeMessage177 178from typing import Any, Dict, List, Union179 180class GoogleSearchTool(BuiltinTool):181 def _invoke(self, 182 user_id: str,183 tool_parameters: Dict[str, Any], 184 ) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:185 """186 invoke tools187 """188 query = tool_parameters['query']189 result_type = tool_parameters['result_type']190 api_key = self.runtime.credentials['serpapi_api_key']191 # Search with serpapi192 result = SerpAPI(api_key).run(query, result_type=result_type)193 194 if result_type == 'text':195 return self.create_text_message(text=result)196 return self.create_link_message(link=result)197```198 199### Parameters200 201The overall logic of the tool is in the `_invoke` method, this method accepts two parameters: `user_id` and `tool_parameters`, which represent the user ID and tool parameters respectively202 203### Return Data204 205When the tool returns, you can choose to return one message or multiple messages, here we return one message, using `create_text_message` and `create_link_message` can create a text message or a link message. If you want to return multiple messages, you can use `[self.create_text_message('msg1'), self.create_text_message('msg2')]` to create a list of messages.206 207## 5. Add Provider Code208 209Finally, we need to create a provider class under the provider module to implement the provider's credential verification logic. If the credential verification fails, it will throw a `ToolProviderCredentialValidationError` exception.210 211Create `google.py` under the `google` module, the content is as follows.212 213```python214from core.tools.provider.builtin_tool_provider import BuiltinToolProviderController215from core.tools.errors import ToolProviderCredentialValidationError216 217from core.tools.provider.builtin.google.tools.google_search import GoogleSearchTool218 219from typing import Any, Dict220 221class GoogleProvider(BuiltinToolProviderController):222 def _validate_credentials(self, credentials: Dict[str, Any]) -> None:223 try:224 # 1. Here you need to instantiate a GoogleSearchTool with GoogleSearchTool(), it will automatically load the yaml configuration of GoogleSearchTool, but at this time it does not have credential information inside225 # 2. Then you need to use the fork_tool_runtime method to pass the current credential information to GoogleSearchTool226 # 3. Finally, invoke it, the parameters need to be passed according to the parameter rules configured in the yaml of GoogleSearchTool227 GoogleSearchTool().fork_tool_runtime(228 meta={229 "credentials": credentials,230 }231 ).invoke(232 user_id='',233 tool_parameters={234 "query": "test",235 "result_type": "link"236 },237 )238 except Exception as e:239 raise ToolProviderCredentialValidationError(str(e))240```241 242## Completion243 244After the above steps are completed, we can see this tool on the frontend, and it can be used in the Agent.245 246Of course, because google_search needs a credential, before using it, you also need to input your credentials on the frontend.247 248249