7.2 · 内置与 API 工具集成（Built-in and API Tool Integration）

内置与 API 工具集成

内置工具与 API 工具集成

相关源文件

本章引用的主要源码文件：

• 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/entities/api_entities.py
• api/core/tools/errors.py
• api/core/tools/mcp_tool/provider.py
• api/core/tools/tool_manager.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/services/tools/test_builtin_tools_manage_service.py
• api/tests/unit_tests/services/tools/test_mcp_tools_transform.py
• web/app/components/app/annotation/add-annotation-modal/index.tsx
• web/app/components/datasets/external-knowledge-base/connector/__tests__/index.spec.tsx
• web/app/components/datasets/external-knowledge-base/connector/index.tsx
• web/app/components/tools/edit-custom-collection-modal/__tests__/get-schema.spec.tsx
• web/app/components/tools/edit-custom-collection-modal/config-credentials.tsx
• web/app/components/tools/edit-custom-collection-modal/get-schema.tsx
• web/app/components/tools/edit-custom-collection-modal/index.tsx
• web/app/components/tools/edit-custom-collection-modal/test-api.tsx
• web/app/components/tools/mcp/__tests__/modal.spec.tsx
• web/app/components/tools/provider/__tests__/custom-create-card.spec.tsx
• web/app/components/tools/provider/__tests__/detail.spec.tsx
• web/app/components/tools/provider/custom-create-card.tsx
• web/app/components/tools/provider/detail.tsx
• web/app/components/workflow/nodes/_base/components/field.tsx
• web/app/components/workflow/nodes/_base/components/info-panel.tsx

本文档记录了 Dify 中内置工具和基于 API 的工具提供者的实现，重点关注凭证存储、OpenAPI 模式解析和工具运行时创建。该系统提供了多种集成模式：预配置的内置工具、基于 OpenAPI 规范的自定义 API 工具、已发布的工作流以及模型上下文协议（MCP）服务器。

核心组件：

• BuiltinToolProvider：用于存储硬编码工具的租户特定凭证的 SQLAlchemy 模型 api/models/tools.py:64。
• ApiToolProvider：用于自定义基于 OpenAPI 的工具的 SQLAlchemy 模型 api/models/tools.py:64。
• WorkflowToolProvider：用于将已发布的工作流暴露为工具的 SQLAlchemy 模型 api/models/tools.py:64。
• MCPToolProvider：用于模型上下文协议集成的 SQLAlchemy 模型 api/models/tools.py:29。
• ToolManager：用于工具运行时创建和凭证解析的单例 api/core/tools/tool_manager.py:98。
• ApiBasedToolSchemaParser：用于将 OpenAPI/Swagger 模式转换为工具包的实用工具 api/services/tools/api_tools_manage_service.py:23。
• ToolTransformService：用于将内部工具实体转换为 API 友好结构并处理图标 URL 的服务 api/services/tools/tools_transform_service.py:37。

工具提供者类型系统

Dify 实现了五种主要的工具提供者类型，每种类型都有不同的模型类和集成模式：

工具提供者模型与控制器架构

下图将工具管理的自然语言概念映射到负责其执行的具体代码实体。

来源： api/models/tools.py:29-64、api/core/tools/tool_manager.py:98-192、api/core/tools/workflow_as_tool/provider.py:29-30、api/core/tools/custom_tool/provider.py:46-47

API 工具提供者系统

API 工具提供者通过 OpenAPI 规范实现与自定义 REST API 的集成。ApiToolProvider 模型存储完整的 OpenAPI 模式，并将各个操作提取为可调用的工具。

API 工具模式解析

ApiToolManageService 和 ApiBasedToolSchemaParser 将原始的 YAML/JSON 模式转换为 Dify 内部的 ApiToolBundle 格式。

• 模式校验：parser_api_schema 使用 ApiBasedToolSchemaParser.auto_parse_to_tool_bundle 来校验模式，并返回参数和凭证 api/services/tools/api_tools_manage_service.py:41-51。
• 凭证生成：该服务会自动生成一个默认的凭证模式，包含 auth_type（none 或 api_key）和请求头配置 api/services/tools/api_tools_manage_service.py:52-79。
• 限制约束：Dify 对每个提供者强制限制最多 100 个 API，以确保性能并保持上下文窗口的可管理性 api/services/tools/api_tools_manage_service.py:160-161。

API 工具提供者持久化

来源： api/services/tools/api_tools_manage_service.py:39-176、api/core/tools/utils/parser.py:23

工具运行时与执行

ToolManager 逻辑

ToolManager 充当所有工具执行的入口点。当调用 get_tool_runtime 时，它会：

1. 识别提供者类型（内置、API、工作流、MCP 等）api/core/tools/tool_manager.py:184-192。
2. 从数据库或 ToolProviderCredentialsCache 中解析凭证 api/core/tools/tool_manager.py:20。
3. 实例化特定的 ToolRuntime 子类 api/core/tools/tool_manager.py:23。

图标与资源管理

ToolTransformService 负责处理图标 URL 的动态生成和元数据格式化，以供前端使用。

• 图标解析：get_tool_provider_icon_url 为内置工具构建 URL，或为自定义工具解析表情符号/JSON 图标 api/services/tools/tools_transform_service.py:41-70。
• 数据重新打包：repack_provider 确保提供者实体在发送到客户端之前具有完整的图标 URL api/services/tools/tools_transform_service.py:72-101。

工作流作为工具集成

工作流可以通过 WorkflowToolManageService 暴露为工具。

• 同步：该服务确保工作流不包含 HumanInputNode 类型，因为工具执行被设计为同步且非阻塞的 api/services/tools/workflow_tools_manage_service.py:79-80。
• 唯一性：Dify 通过检查工具名称和租户内的源 app_id 来防止重复的工作流工具 api/services/tools/workflow_tools_manage_service.py:45-61。

管理服务

BuiltinToolManageService

处理预定义工具（例如 Google 搜索、WolframAlpha）的生命周期。

• 凭证更新：使用 BuiltinToolManageService.create_tool_encrypter 管理内置提供者的 API 密钥加密 api/services/tools/builtin_tools_manage_service.py:176。
• OAuth 集成：通过 get_builtin_tool_provider_oauth_client_schema 为需要 OAuth2 的工具提供模式和重定向 URI api/services/tools/builtin_tools_manage_service.py:62-84。

MCPToolManageService

管理模型上下文协议服务器。

• 提供者创建：使用 encrypter.encrypt_token 加密服务器 URL，并对其进行哈希处理以便快速查找 api/services/tools/mcp_tools_manage_service.py:145-152。
• URL 校验：通过 ServerUrlValidationResult 对 MCP 服务器可用性进行独立校验 api/services/tools/mcp_tools_manage_service.py:54-62。

来源： api/services/tools/builtin_tools_manage_service.py:40-176、api/services/tools/api_tools_manage_service.py:39-176、api/services/tools/mcp_tools_manage_service.py:78-180、api/controllers/console/workspace/tool_providers.py:38-44