This document describes the tool and plugin architecture in Dify, covering how external tools are integrated, managed, and executed within applications. The tool ecosystem enables agent chat applications and workflow nodes to invoke external functionality through five distinct provider types: built-in tools, API-based tools, workflow-as-tool, plugin-based tools, and MCP (Model Context Protocol) servers.
For details, see:
ToolManager singleton, ToolProviderController interface, and different provider types.BuiltinToolProvider, ApiToolProvider, credential management, and tool runtime creation.MCPClient, transport layer, and server communication.Dify supports five distinct tool provider types, each serving different integration patterns and use cases. These types are defined in the ToolProviderType enum which includes BUILT_IN, API, WORKFLOW, PLUGIN, and MCP api/core/tools/entities/tool_entities.py65-76
| Provider Type | Storage Model | Controller Class | Typical Use Case |
|---|---|---|---|
BUILT_IN | BuiltinToolProvider | BuiltinToolProviderController | Pre-packaged tools (e.g., Google, Wikipedia) |
API | ApiToolProvider | ApiToolProviderController | Custom user-defined OpenAPI/Swagger tools |
WORKFLOW | WorkflowToolProvider | WorkflowToolProviderController | Workflow apps published as tools |
PLUGIN | None (runtime only) | PluginToolProviderController | Runtime plugin tools managed by plugin daemon |
MCP | MCPToolProvider | MCPToolProviderController | Remote Model Context Protocol servers |
Sources: api/core/tools/entities/tool_entities.py65-76 api/models/tools.py59 api/core/tools/tool_manager.py27-55
The ToolManager class is the core singleton that coordinates tool provider discovery, credential management, and tool runtime instantiation across all provider types api/core/tools/tool_manager.py94-188 It handles caching of built-in providers, plugin providers, and creation of runtime tool instances needed for invocation.
get_builtin_provider() retrieves either a hardcoded built-in provider or a plugin-based provider for the tenant.get_plugin_provider() loads provider controllers from plugin-managed tool providers stored in context-local cache.get_tool_runtime() instantiates a tool runtime instance based on provider type, credentials, and tool name, returning subclasses of Tool like BuiltinTool, PluginTool, ApiTool, WorkflowTool, or MCPTool.The ToolManager acts as the single entry point for components wanting to use any tool or invoke providers uniformly.
For detailed architecture and singleton patterns, see Tool Provider Types and Architecture.
Sources: api/core/tools/tool_manager.py94-188
Dify includes several built-in tools pre-packaged and maintained in BuiltinToolProviderController instances. Users can also define API tools dynamically by uploading OpenAPI or Swagger specs. These are managed by ApiToolProviderController. Tool credentials are managed via encrypted storage specific to each provider and tenant.
The OpenAPI or Swagger specification parsing into internal tool bundles is done by ApiBasedToolSchemaParser, which translates the schema JSON/YAML into executable API tool configurations api/core/tools/utils/parser.py32-36
This mechanism supports credential injection, parameter schema validation, and integrates with frontend tool definition UIs.
For details on credential management, schema parsing, and runtime tool creation, see Built-in and API Tool Integration.
Sources:
Dify's MCP integration allows it to extend with external MCP servers, which are networked tool providers speaking the Model Context Protocol.
MCPClientWithAuthRetry, which wraps the client to handle token refresh and error retries.MCP providers are stored with encrypted server info and credentials to secure communication. The tool runtime for MCP tools coordinates the invocation through the MCP client layer.
For detailed transport layer and server communication details, see MCP Protocol Integration.
Sources:
Plugins are external components running in a separate plugin daemon to provide dynamic tool capabilities. This isolation ensures security and scalability.
PluginToolManager loads and manages installed plugins, fetching tool provider declarations dynamically api/core/plugin/impl/tool.py25PluginToolProviderController implements the ToolProviderController interface for plugin-provided tools, enabling runtime tool discovery and execution api/core/tools/plugin_tool/provider.py26ToolManager.get_plugin_provider() ensures the plugin tool provider is loaded and cached per tenant, interfacing with the plugin daemon service api/core/tools/tool_manager.py140-175ToolTransformService using the plugin system api/services/tools/tools_transform_service.py80-100This mechanism offers a unified interface for plugin tools similar to built-in tools, enabling tool invocation without difference at the runtime level.
For security isolation, plugin installation, and marketplace integration, see Plugin Daemon and Execution Environment.
Sources:
The ToolEngine class orchestrates the invocation of tools from various providers, handling parameter conversion, runtime invocation, output parsing, and callback events api/core/tools/tool_engine.py43-170
agent_invoke() is designed for agent chat applications invoking tools, integrating with DifyAgentCallbackHandler. It parses input, forwards calls to tool runtimes, collects outputs, handles error cases, and manages message files api/core/tools/tool_engine.py49-130generic_invoke() supports workflow nodes invoking tools, including nested workflow tool calls and streaming response handling api/core/tools/tool_engine.py160-170WorkflowTool class wraps workflow apps as tools. Its invocation runs the underlying workflow graph via WorkflowAppGenerator and transforms the workflow outputs into tool messages consumable by callers api/core/tools/workflow_as_tool/tool.py40-153This engine provides a consistent invocation layer across diverse tool provider types and execution contexts.
Sources:
The Tool and Plugin ecosystem in Dify is modular and extensible, centered on the ToolManager singleton that unifies access to built-in, API, workflow, plugin, and MCP protocol tools. Built-in and API tools rely on static or user-defined schemas, while plugin and MCP providers dynamically add tool capabilities through secure, isolated runtimes or networked servers. The ToolEngine underpins execution across these tools, supporting rich invocation semantics required by agents and workflows.
Further details and developer guides are available in the respective child pages linked above.
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.