7.1 · 工具提供方类型与架构（Tool Provider Types and Architecture）

应用编排与外部知识接入 · 本章是 Dify DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Dify 章节7.1 状态全文译文模块智能体运行时、接口与服务契约、界面与交互、模型调用与提供方适配

项目要点页2.5 参考项目项目章节目录Dify DeepWiki 原始章节Tool Provider Types and Architecture 上一章7 下一章7.2

源码线索

api/controllers/console/workspace/tool_providers.py
api/core/mcp/client/sse_client.py
api/core/mcp/client/streamable_client.py
api/core/mcp/mcp_client.py
api/core/mcp/session/base_session.py
api/core/mcp/session/client_session.py
api/core/tools/__base/tool.py
api/core/tools/builtin_tool/tool.py
api/core/tools/custom_tool/provider.py
api/core/tools/custom_tool/tool.py

模块标签

智能体运行时
接口与服务契约
界面与交互
模型调用与提供方适配
配置治理

中文译文

工具提供方类型与架构（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/langgenius/dify/7.1-tool-provider-types-and-architecture

翻译时间：2026-05-27T08:44:28.750Z

翻译模型：deepseek-chat

原文字符数：13699

项目：Dify (dify)

---

工具提供者类型与架构

目的与范围

工具提供者系统抽象了工具发现、凭证管理和调用功能，支持以下多种不同的提供者类型：

内置提供者：Dify 自带的硬编码工具（例如搜索、天气）。
API 提供者：用户定义的基于 OpenAPI/Swagger 的工具。
工作流提供者：发布后作为可复用工具暴露的工作流。
插件提供者：通过插件市场分发并由插件守护进程管理的工具。
MCP 提供者：通过模型上下文协议（MCP）服务器暴露的工具。
数据集检索：用于知识库交互的专用工具。

本页面涵盖支持多提供者系统的架构模式、数据模型和控制器接口。

---

工具提供者类型分类

枚举定义

ToolProviderType 枚举定义了系统中用于路由和标识的所有支持的提供者类别。

class ToolProviderType(StrEnum):
    PLUGIN = auto()
    BUILT_IN = "builtin"
    WORKFLOW = auto()
    API = auto()
    APP = auto()
    DATASET_RETRIEVAL = "dataset-retrieval"
    MCP = auto()

来源： api/core/tools/entities/tool_entities.py:65-76

提供者类型对比

提供者类型	发现方式	凭证存储	模式来源	多租户
`BUILT_IN`	文件系统扫描	`BuiltinToolProvider`	Python 类	按租户凭证
`API`	用户创建	`ApiToolProvider`	OpenAPI/Swagger	租户作用域
`WORKFLOW`	工作流发布	`WorkflowToolProvider`	工作流图	租户作用域
`PLUGIN`	市场	`PluginToolManager`	插件清单	按租户凭证
`MCP`	MCP 发现	`MCPToolProvider`	MCP 协议	租户作用域
`DATASET_RETRIEVAL`	知识库	不适用	数据集元数据	租户作用域

来源： api/core/tools/entities/tool_entities.py:65-76, api/core/tools/tool_manager.py:182-237, api/models/tools.py:73-118, api/models/tools.py:128-182

---

ToolManager 单例架构

ToolManager 类作为所有工具提供者的中央注册表和工厂。它对硬编码的内置提供者实现了带锁的延迟初始化，并管理工具运行时的实例化。

ToolManager 类结构

graph TB
    subgraph "ToolManager 单例"
        TM["ToolManager<br/>(api/core/tools/tool_manager.py)"]

        subgraph "缓存与锁"
            HC["_hardcoded_providers<br/>dict[str, BuiltinToolProviderController]"]
            BPL["_builtin_provider_lock<br/>Lock"]
            PTM["plugin_tool_providers<br/>(contexts.plugin_tool_providers)"]
        end

        subgraph "提供者访问方法"
            GHP["get_hardcoded_provider()"]
            GBP["get_builtin_provider()"]
            GPP["get_plugin_provider()"]
        end

        subgraph "运行时工厂"
            GTR["get_tool_runtime()"]
        end
    end

    TM --> HC
    TM --> BPL
    TM --> GHP
    TM --> GBP
    TM --> GPP
    TM --> GTR

来源： api/core/tools/tool_manager.py:98-192

提供者类型分发逻辑

get_tool_runtime() 方法根据请求中提供的 ToolProviderType 路由到特定于提供者的逻辑。

graph TD
    GTR["ToolManager.get_tool_runtime()"]

    BUILTIN{"provider_type ==<br/>BUILT_IN?"}
    API{"provider_type ==<br/>API?"}
    WORKFLOW{"provider_type ==<br/>WORKFLOW?"}
    PLUGIN{"provider_type ==<br/>PLUGIN?"}
    MCP{"provider_type ==<br/>MCP?"}
    DR{"provider_type ==<br/>DATASET_RETRIEVAL?"}

    GBP["get_builtin_provider()"]
    GAPC["ApiToolProviderController"]
    GWPC["WorkflowToolProviderController"]
    GPP["get_plugin_provider()"]
    GMPC["MCPToolProviderController"]
    GDRC["DatasetRetrieverTool"]

    GTR --> BUILTIN
    BUILTIN -->|是| GBP
    BUILTIN -->|否| API
    API -->|是| GAPC
    API -->|否| WORKFLOW
    WORKFLOW -->|是| GWPC
    WORKFLOW -->|否| PLUGIN
    PLUGIN -->|是| GPP
    PLUGIN -->|否| MCP
    MCP -->|是| GMPC
    MCP -->|否| DR
    DR -->|是| GDRC

来源： api/core/tools/tool_manager.py:182-256

---

ToolProviderController 接口

所有提供者类型都实现（或扩展）了 ToolProviderController 接口，该接口定义了工具发现、凭证模式管理和工具实体检索的契约。

控制器层次结构

graph TB
    TPC["ToolProviderController<br/>(api/core/tools/__base/tool_provider.py)"]

    BTPC["BuiltinToolProviderController"]
    ATPC["ApiToolProviderController"]
    WTPC["WorkflowToolProviderController"]
    PTPC["PluginToolProviderController"]
    MTPC["MCPToolProviderController"]

    TPC --> BTPC
    TPC --> ATPC
    TPC --> WTPC
    TPC --> PTPC
    TPC --> MTPC

    BTPC -.加载.-> FS["core/tools/builtin_tool/providers/"]
    ATPC -.加载.-> ATPDB["ApiToolProvider 模型"]
    WTPC -.加载.-> WTPDB["WorkflowToolProvider 模型"]
    PTPC -.加载.-> PM["PluginToolManager"]
    MTPC -.加载.-> MTPDB["MCPToolProvider 模型"]

来源： api/core/tools/tool_manager.py:22-29, api/core/tools/__base/tool_provider.py:9

---

工作流工具提供者

工作流工具提供者允许将已发布的工作流视为单个工具。这使得复杂逻辑可以被封装并由智能体或其他工作流复用。WorkflowTool 运行时通过 WorkflowAppGenerator 执行工作流。

WorkflowTool 执行流程

sequenceDiagram
    participant WT as WorkflowTool
    participant WAG as WorkflowAppGenerator
    participant GE as GraphEngine

    WT->>WAG: generate(app_model, workflow, args, ...)
    WAG->>GE: 执行工作流图
    GE-->>WAG: 返回输出与用量
    WAG-->>WT: 返回结果字典
    WT->>WT: _derive_usage_from_result()
    WT->>WT: 生成 ToolInvokeMessages

来源： api/core/tools/workflow_as_tool/tool.py:91-119, api/core/tools/workflow_as_tool/tool.py:135-143, api/core/tools/workflow_as_tool/tool.py:149-175

WorkflowTool 数据模型

WorkflowToolProvider 模型持久化了将特定应用的工作流暴露为工具的配置。

class WorkflowToolProvider(db.Model):
    __tablename__ = 'tool_workflow_providers'

    id = db.Column(StringUUID, primary_key=True, default=uuid.uuid4)
    tenant_id = db.Column(StringUUID, nullable=False, index=True)
    app_id = db.Column(StringUUID, nullable=False, index=True)
    name = db.Column(db.String(255), nullable=False)
    label = db.Column(db.String(255), nullable=False)
    description = db.Column(db.Text, nullable=False)
    icon = db.Column(db.Text, nullable=False)
    parameter_configuration = db.Column(db.Text, nullable=False)
    privacy_policy = db.Column(db.Text, nullable=True)
    version = db.Column(db.String(255), nullable=False)

来源： api/models/tools.py:216-281

---

MCP 协议集成

模型上下文协议（MCP）提供者允许 Dify 连接到外部 MCP 服务器。MCPToolManageService 负责管理这些提供者的生命周期，包括认证和工具发现。

MCP 会话架构

MCP 通信依赖于基于会话的架构，该架构管理 Dify 客户端与 MCP 服务器之间的 JSON-RPC 消息流。

graph LR
    subgraph "MCP 客户端层"
        MCL["MCPClient<br/>(api/core/mcp/mcp_client.py)"]
        CS["ClientSession<br/>(api/core/mcp/session/client_session.py)"]
    end

    subgraph "传输层"
        SSEC["SSEClient<br/>(api/core/mcp/client/sse_client.py)"]
        STC["StreamableClient<br/>(api/core/mcp/client/streamable_client.py)"]
    end

    MCL --> CS
    CS --> SSEC
    CS --> STC

来源： api/core/mcp/session/base_session.py:123-160, api/core/mcp/mcp_client.py:26, api/services/tools/mcp_tools_manage_service.py:19-22

---

工具引擎与调用

ToolEngine 负责智能体和工作流中工具的实际执行，管理参数的转换以及响应（文本、JSON 或文件）的处理。

智能体工具调用

sequenceDiagram
    participant TE as ToolEngine
    participant T as 工具实例
    participant CH as DifyAgentCallbackHandler
    participant TF as ToolFileMessageTransformer

    TE->>CH: on_tool_start()
    TE->>T: _invoke(tool_parameters)
    T-->>TE: 生成 ToolInvokeMessages
    TE->>TF: transform_tool_invoke_messages()
    TE->>CH: on_tool_end()
    TE-->>TE: 返回 plain_text 与 message_files

来源： api/core/tools/tool_engine.py:48-127

关键类总结

类名	文件路径	角色
`ToolManager`	`api/core/tools/tool_manager.py:98`	管理提供者生命周期和运行时创建的单例。
`ToolEngine`	`api/core/tools/tool_engine.py:42`	工具调用和响应处理的执行引擎。
`WorkflowTool`	`api/core/tools/workflow_as_tool/tool.py:35`	暴露为工具的工作流的运行时实现。
`ApiTool`	`api/core/tools/custom_tool/tool.py:38`	基于 OpenAPI/Swagger 的工具的运行时实现。
`ToolTransformService`	`api/services/tools/tools_transform_service.py:37`	用于将数据库模型转换为 API 实体并处理图标的服务。

来源： api/core/tools/tool_manager.py:98, api/core/tools/tool_engine.py:42, api/core/tools/workflow_as_tool/tool.py:35, api/core/tools/custom_tool/tool.py:38, api/services/tools/tools_transform_service.py:37