Tool Plugin
Last updated
Last updated
Tool type plugins are external tools that can be referenced by Chatflow / Workflow / Agent application types to enhance the capabilities of Dify applications. For example, adding online search capabilities, image generation capabilities, etc. to an application. Tool Type Plugins provide a complete set of tools and API implementations.
In this article, a "Tool Plugin" refers to a complete project that includes the tool provider file, functional code, and other related components. A tool provider may encompass multiple Tools (which can be understood as additional functionalities offered by a single tool), structured as follows:
This article uses GoogleSearch as an example of how to quickly develop a tool type of plugin.
Dify plugin scaffolding tool
Python, version ≥ 3.12
Run the CLI tool to create a new dify plugin project:
If you have renamed the binary file to dify and copied it to the /usr/local/bin path, you can run the following command to create a new plugin project:
In the following, the command-line tool
difyis used. If issues occur, please replace thedifycommand with the appropriate path to your command-line tool.
There are three types of plugins: tool, model and extension. All templates within SDK are provided with full code projects. The following part will use the Tool plugin template as an example.
The plugin also needs to read permissions from the Dify platform to connect properly. The following permissions need to be granted for the example tool plugin:
Tools
Apps
Enable persistent storage Storage, allocate default size storage
Allow registration of Endpoint
Use the arrow keys to select permissions within the terminal and the "Tab" button to grant permissions.
After checking all the permission items, tap Enter to complete the creation of the plug-in. The system will automatically generate the plug-in project code.
The tool vendor file can be understood as the base configuration entry point for a tool type plugin, and is used to provide the necessary authorization information to the tool. This section demonstrates how to fill out that yaml file.
Go to the /provider path and rename the yaml file in it to google.yaml. The yaml file will contain information about the tool vendor, including the provider name, icon, author, and other details. This information will be displayed when the plugin is installed.
Example:
identity contains basic information about the tool provider, including author, name, label, description, icon, and more.
The icon needs to be an attachment resource, which needs to be placed in the _assets folder in the project root directory.
Tags help users quickly find plugins by category, here are all the tags currently supported.
Make sure that the path to the file is in the /tools directory, the full path is below:
Where the google.yaml file needs to use its absolute path in the plugin project.
Completion of third-party service credentials
For ease of development, we have chosen to use the Google Search API provided by a third-party service, SerpApi. SerpApi requires an API Key in order to use it, so you need to add the credentials_for_provider field to the yaml file.
The full code is below:
It is necessary to specify which tools are included in this provider. This example only includes a tools/google_search.yaml file.
For the provider, in addition to defining its basic information, you also need to implement some of its code logic, so you need to specify its implementation logic. In this example, the code file for the function is placed in google.py, but instead of implementing it for the time being, you write the code for google_search first.
There can be multiple tools under a tool vendor, and each tool needs to be described by a yaml file, which contains basic information about the tool, its parameters, its output, and so on.
Still using the GoogleSearch tool as an example, you can create a new google_search.yaml file in the /tools folder.
identity contains the tool's basic information, including name, author, labels, description, etc.
parameters parameter list
name (required) parameter name, must be unique, cannot duplicate other parameter names
type (required) parameter type, currently supports nine types: string, number, boolean, select, secret-input, file, files, model-selector, app-selector, corresponding to string, number, boolean, dropdown menu, encrypted input field, file, file set, model selection, and application selection. For sensitive information, please use secret-input type
label (required) parameter label, used for frontend display
form (required) form type, currently supports two types: llm and form
In Agent applications, llm means the parameter is inferred by LLM, form means parameters that can be preset to use the tool
In workflow applications, both llm and form need to be filled in the frontend, but llm parameters will serve as input variables for tool nodes
required whether the field is required
In llm mode, if a parameter is required, the Agent must infer this parameter
In form mode, if a parameter is required, users must fill in this parameter in the frontend before starting the conversation
options parameter options
In llm mode, Dify will pass all options to LLM, which can make inferences based on these options
In form mode, when type is select, the frontend will display these options
default default value
min minimum value, can be set when parameter type is number
max maximum value, can be set when parameter type is number
human_description introduction displayed in frontend, supports multiple languages
placeholder prompt text for input fields, can be set when form type is form and parameter type is string, number, or secret-input, supports multiple languages
llm_description introduction passed to LLM. To help LLM better understand this parameter, please write as detailed information as possible about this parameter here so that LLM can understand it
After filling in the configuration information of the tool, you can start writing the functional code of the tool to realize the logical purpose of the tool. Create google_search.py in the /tools directory with the following contents.
Finally, you need to create a vendor code implementation code that will be used to implement the vendor's credential validation logic. If the credential validation fails, the ToolProviderCredentialValidationError exception will be thrown. After successful validation, the google_search tool service will be requested correctly.
Create a google.py file in the /provider directory with the following code:
Dify provides remote debugging method, go to "Plugin Management" page to get the debugging key and remote server address.
Go back to the plugin project, copy the .env.example file and rename it to .env. Fill it with the remote server address and debugging key.
The .env file:
Run the python -m main command to launch the plugin. You can see on the plugin page that the plugin has been installed into Workspace. Other team members can also access the plugin.
After confirming that the plugin works properly, you can package and name the plugin with the following command line tool. After running it you can find the google.difypkg file in the current folder, which is the final plugin package.
Congratulations, you have completed the complete development, debugging and packaging process of a tool type plugin!
Quick Start:
Plugins Specification Definition Documentaiton:
For detailed instructions on how to prepare scaffolding tools for plugin development, see .
If you are already familiar in plugin development, please refer to the to implement various types of plugins.
where the credentials_for_provider sub-level structure needs to satisfy the specification.
In this example, we simply request the serpapi and use self.create_json_message to return a string of json formatted data. For more information on the types of data returned, you can refer to the documentation.
You can now publish your plugin by uploading it to the ! Before uploading, make sure your plugin follows the . Once approved, the code will be merged into the master branch and automatically live in the .
