多来源工具调用系统

学习目标

• 理解 Dify 工具系统的五类来源及其注册发现机制
• 掌握 ToolManager 如何统一管理异构工具提供者
• 学会分析工具执行引擎的回调链与安全隔离

前置知识

本章涉及工具调用协议和 MCP 协议的通用原理，建议先阅读：

• 工具调用协议与执行模型
• MCP 协议与生态集成
• 插件系统

下文假设你已理解工具调用的通用概念，直接聚焦 Dify 的具体实现。

---

项目实践

五类工具来源

Dify 的工具系统支持五种不同的来源，每种对应一个独立的 Provider Controller：

类型	来源	部署位置	典型用例
Builtin Tool	代码内嵌	本地 Python 包	Google Search、DALL·E、Stable Diffusion、WolframAlpha
API Tool	用户配置	外部 HTTP 端点	用户自定义 REST API
Workflow Tool	工作流导出	本地 Dify 工作流	将复杂工作流封装为单步工具
Plugin Tool	插件市场	远程插件服务	社区/企业开发的工具插件
MCP Tool	MCP Server	远程 MCP 服务	通过 MCP 协议发现的远程工具

ToolManager：统一注册与发现

ToolManager 是整个工具系统的入口，负责发现、注册和管理所有工具提供者：

# 伪代码，展示 ToolManager 的核心方法
class ToolManager:
    # 缓存内置提供者
    _hardcoded_providers: dict[str, BuiltinToolProviderController] = {}

    # 获取运行时工具
    def get_tool_runtime(
        provider_type: ToolProviderType,
        provider_id: str,
        tool_name: str,
        invoke_from: InvokeFrom,
    ) -> Tool:
        # 根据 provider_type 路由到不同的提供者控制器
        # Builtin → ApiToolProvider → WorkflowToolProvider → PluginToolProvider → MCPToolProvider

    # 获取当前租户可用的工具列表
    def get_current_credentials_for_agent(
        agent_tool_entities: list[AgentToolEntity],
        invoke_from: InvokeFrom,
    ) -> list[Tool]:
        # 过滤出当前 Agent 配置的工具
        # 加载每个工具的凭证（加密存储）
        # 返回可用的 Tool 实例列表

关键设计决策：

• 所有工具类型共享 ToolProviderController 协议接口
• 凭证通过 ToolProviderCredentialsCache 缓存，避免每次调用都解密
• ToolRuntime 封装工具执行所需的上下文（tenant_id、凭证、运行时配置）

ToolEngine：统一执行引擎

ToolEngine 负责调用单个工具并处理返回值：

# 伪代码，展示执行流程
class ToolEngine:
    def invoke_tool(
        tool: Tool,
        tool_input: dict,
        user_id: str,
        tenant_id: str,
    ) -> ToolInvokeMeta:
        # 1. 参数校验与类型转换
        # 2. 执行工具（同步/异步）
        # 3. 捕获异常并转换为 ToolInvokeMeta
        # 4. 回调 DifyAgentCallbackHandler 推送事件
        # 5. 返回结果元数据（输出、Token 用量、耗时）

执行过程中通过 DifyAgentCallbackHandler 推送事件到流式前端，实现 Agent 调用工具过程的实时可视化。

工具参数加密与安全管理

工具凭证（如 API Key）通过加密存储保护：

# 伪代码，展示加密流程
class ToolParameterConfigurationManager:
    def encrypt_provider_config(self, config: dict) -> dict:
        encrypter = create_tool_provider_encrypter()
        return encrypter.encrypt(config)

安全边界：

• 凭证在数据库中加密存储
• 运行时解密后注入 ToolRuntime
• 日志中自动脱敏（通过 jsonable_encoder）

MCP 工具集成

MCP 工具通过 MCPToolProviderController 集成到工具系统中：

# 伪代码，展示 MCP 工具发现
class MCPToolProviderController(ToolProviderController):
    def discover_tools(self, server_url: str) -> list[MCPTool]:
        # 1. 连接到 MCP Server
        # 2. 调用 tools/list 获取可用工具
        # 3. 转换为 Dify Tool 格式
        # 4. 注册到 ToolManager

MCP Server 的连接信息存储在 services/tools/mcp_tools_manage_service.py 中管理。

问题与规避

陷阱 1：工具 SSRF 攻击

API Tool 和 MCP Tool 可能指向内网地址，导致 SSRF 攻击。

Dify 的规避策略：

• 使用 core.helper.ssrf_proxy 进行所有出站 HTTP 请求
• SSRF Proxy 自动拦截内网 IP 段和保留地址
• 工具文件访问通过 DatabaseFileAccessController 控制权限

陷阱 2：工具凭证泄露

工具凭证在日志和错误消息中可能泄露。

Dify 的规避策略：

• 所有凭证使用 jsonable_encoder 序列化时自动脱敏
• 错误消息中不返回原始凭证值
• 数据库中使用加密字段存储

陷阱 3：工具调用超时

远程工具（API Tool、MCP Tool）可能长时间不响应，阻塞 Agent 循环。

Dify 的规避策略：

• 工具执行设置超时时间（通过 ToolRuntime 配置）
• 超时后抛出 ToolInvokeTimeoutError，由 Agent Runner 处理
• 流式推送 QueueAgentThoughtEvent 通知前端工具调用状态

设计取舍

多来源 vs 统一协议

Dify 选择支持五类工具来源而非统一的工具协议：

优势：

• 用户可以使用任意来源的工具，灵活性高
• 内置工具开箱即用，无需额外配置
• MCP 工具支持与外部工具生态集成

代价：

• ToolManager 需要维护五套不同的注册和发现逻辑
• 每种工具类型的错误处理和重试策略不同
• 新来源需要实现完整的 ToolProviderController 协议

替代方案：统一所有工具为 MCP 协议，简化内部实现。但这会牺牲内置工具的零配置体验和 API Tool 的灵活性。

参考来源

• MCP Protocol Specification
• OpenAI Function Calling
• Dify Tools 模块源码：api/core/tools/