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

工具提供方类型与架构

工具提供者类型与架构

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

• 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
• api/core/tools/entities/api_entities.py
• api/core/tools/entities/tool_bundle.py
• api/core/tools/entities/tool_entities.py
• api/core/tools/errors.py
• api/core/tools/mcp_tool/provider.py
• api/core/tools/plugin_tool/tool.py
• api/core/tools/tool_engine.py
• api/core/tools/tool_manager.py
• api/core/tools/utils/configuration.py
• api/core/tools/utils/dataset_retriever/dataset_retriever_base_tool.py
• api/core/tools/utils/dataset_retriever_tool.py
• api/core/tools/utils/model_invocation_utils.py
• api/core/tools/workflow_as_tool/tool.py
• api/services/tools/api_tools_manage_service.py
• api/services/tools/builtin_tools_manage_service.py
• api/services/tools/mcp_tools_manage_service.py
• api/services/tools/tools_transform_service.py
• api/services/tools/workflow_tools_manage_service.py
• api/tests/test_containers_integration_tests/services/tools/__init__.py
• api/tests/test_containers_integration_tests/services/tools/test_api_tools_manage_service.py
• api/tests/unit_tests/core/tools/test_base_tool.py
• api/tests/unit_tests/core/tools/workflow_as_tool/test_tool.py
• api/tests/unit_tests/services/tools/test_builtin_tools_manage_service.py
• api/tests/unit_tests/services/tools/test_mcp_tools_transform.py
• api/tests/unit_tests/tools/test_api_tool.py
• docker/ssrf_proxy/squid.conf.template

本文档描述了 Dify 工具提供者系统的架构，该系统支持将外部工具和服务集成到工作流和智能体应用中。工具提供者框架支持多种提供者类型，每种类型具有不同的特性和集成模式，通过 ToolManager 单例进行管理。

目的与范围

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

• 内置提供者：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

提供者类型对比

来源： 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 类结构

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

提供者类型分发逻辑

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

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

ToolProviderController 接口

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

控制器层次结构

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

工作流工具提供者

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

WorkflowTool 执行流程

来源： 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 消息流。

来源： 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 或文件）的处理。

智能体工具调用

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

关键类总结

来源： 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