跳到主要内容

通过 MCP 与 Dify 集成

为了进一步释放企业数字资源的潜能，Xpert AI 多智能体平台 已支持通过 MCP 与 Dify 平台 进行深度集成，涵盖 知识库、工作流、Chatflow 等关键能力。

通过本教程，您将学会如何在 Xpert AI 平台中配置 MCP 工具，集成 Dify 的核心资源，并赋能 AI 智能体调用这些工具，实现更智能、专业的业务自动化流程。

🧩 第一步：准备 Dify 平台资源​

在集成之前，您需要在 Dify 平台 准备好希望接入的资源，例如：

  • 知识库（Knowledge Base）：如 FAQ 文档、产品介绍等；
  • 工作流（Workflow）：例如一个用于异常处理或审批的自动化流程；
  • Chatflow：自定义的大模型对话流程。

✅ 所需信息​

请准备以下信息，供后续工具配置时使用：

  • Dify 的 API Key（建议使用具有对应资源权限的 Key）；
  • 资源的唯一标识（如工作流 ID、Chatflow ID 等）；
  • 其他资源访问所需的参数（如 Base URL、Agent ID 等）。

🛠️ 第二步：在 MCP 市场安装 Dify 工具模版​

  1. 进入 Xpert AI 平台的 MCP 工具市场；
  2. 搜索关键词 “Dify”，即可看到官方提供的若干 Dify 集成模版：
    • Dify Chatflow 调用模版
    • Dify 工作流调用模版
    • Dify 知识库问答模版
  3. 选择适合您需求的模版，点击 “安装”；
  4. 在安装页面填写：
    • Dify 平台的 API Key
    • 目标资源的 ID（如 Chatflow ID、Workflow ID）
    • 可选：填写默认参数、环境变量配置等；
  5. 安装完成后，MCP 工具会自动生成，并在“工具列表”中可见。

🧬 第三步：修改 MCP 工具代码以自定义参数和逻辑​

进入“代码”，您可以对工具逻辑进行细粒度定制，示例如下：

main.py
import os
import requests

...

@mcp.tool()
def run_chatflow(input: str) -> Optional[str]:
   """
   调用 Dify 平台中的某个 Chatflow 对话流程，支持异常场景处理等应用。
   :param input: 用户输入的异常描述信息，将作为 Dify Chatflow 的主要上下文输入。
   :return: 返回 Dify 响应的核心文本内容
   """

   API_KEY = os.getenv("DIFY_API_KEY")
   CHATFLOW_ID = os.getenv("DIFY_CHATFLOW_ID")

   headers = {"Authorization": f"Bearer {API_KEY}"}
   payload = {
      "inputs": {"input": input},
      "response_mode": "blocking"
   }

   resp = requests.post(
      f"https://api.dify.ai/v1/chat-flows/{CHATFLOW_ID}/invoke",
      json=payload,
      headers=headers,
      timeout=20
   )

   if resp.status_code == 200:
      return resp.json().get("answer")  # 根据 Dify 的返回结构自行提取
   return None

💡 编写建议​

  • input 参数可以根据业务需要扩展，例如添加用户角色、业务类型等；
  • 函数的 Docstring 是 提示大模型调用工具的关键描述信息，务必详细写明工具用途、输入要求与典型调用场景；
  • 如需提取结构化结果（如 JSON 字段），可在返回逻辑中添加解析；
  • 支持读取环境变量，确保敏感信息安全配置。

完成后，点击保存，即可生成您的 MCP 工具。

🧠 第四步：将 MCP 工具集成到智能体​

  1. 打开某个需要调用 Dify 资源的智能体编排页；
  2. 点击“添加工具集”，选择您刚才创建的 Dify MCP 工具；
  3. 自动保存智能体配置；
  4. 接下来，您的智能体便具备调用 Dify Chatflow、工作流或知识库的能力，能在对话中根据用户输入智能触发相关逻辑。

✅ 示例应用场景​

  • 客户支持 Copilot：根据用户问题调用 Dify Chatflow，实现自动问答；
  • 流程协同智能体：接入 Dify 工作流，实现销售审批、异常处理等；
  • 知识搜索助手：集成 Dify 知识库，支持用户随时检索业务知识。

当然可以，以下是为这篇教程新增的“常见问题 FAQ”章节，覆盖了在使用 Xpert AI 平台集成 Dify 资源过程中用户可能遇到的问题及解答。

❓ 常见问题 FAQ​

在集成与使用 Dify 工具的过程中，您可能会遇到以下问题：

1. 🧠 大模型没有调用此工具？​

可能原因与解决方法：

  • 检查大模型是否支持 工具调用能力；
  • 查看 MCP 工具的 Docstring 是否详细、明确地描述了调用场景和参数用途；
  • 检查智能体的提示词（Prompt）中是否引导模型识别场景和工具功能；
  • 工具是否已正确绑定到该智能体。

建议：在描述中加入清晰的意图引导，例如：“当用户提出XXX问题时，请调用此工具进行处理”。

2. 🧾 调用 MCP 工具时没有填写参数？​

可能原因与解决方法：

  • 查看 MCP 工具函数中参数是否设置为可选（Optional）而非必填；
  • 检查 Docstring 中是否清晰描述了参数的用途和要求；
  • 考虑使用强制参数（无默认值）来提示模型 必须输入参数；
  • 提供结构化提示词，让模型清晰知道输入参数应是什么内容。

3. 🔐 出现 “Unauthorized” 或 “401” 错误？​

可能原因与解决方法：

  • 检查 API Key 是否正确粘贴，是否为有效的 Dify 平台 Key；
  • 是否在 MCP 工具代码中正确地通过环境变量传入了 Key；
  • 确认该 API Key 是否具备访问目标资源的权限（如 Chatflow、Workflow）。

4. 🆔 提示 “Resource Not Found” 或 “Invalid ID”？​

可能原因与解决方法：

  • 检查传入的 Chatflow ID / Workflow ID 是否准确；
  • 某些 ID 在 Dify 平台中可能为私有资源，请确认是否对 API Key 用户开放；
  • 复制 ID 时避免空格或隐藏字符错误。

5. 🌐 MCP 工具调用 Dify 失败或无响应？​

可能原因与解决方法：

  • 检查 Dify API 请求是否超时，可增加 timeout 参数（例如 timeout=30）；
  • 验证当前网络环境是否能访问 https://api.dify.ai；
  • 查看 MCP 工具代码中是否正确处理了异常，建议加入异常捕获和日志输出。

6. 🧪 模型调用工具后返回内容不完整或结构异常？​

可能原因与解决方法：

  • 确认 Dify API 返回的结构（通常是 JSON），并正确提取所需字段（如 answer）；
  • 可加入日志打印返回体以调试，或解析嵌套字段以获取完整信息；
  • 若返回为 markdown 或 HTML，可加入后处理逻辑进行清洗。

7. 🤖 智能体调用工具时频率受限或报错？​

可能原因与解决方法：

  • 检查 Dify 平台是否有调用频率限制（Rate Limit）；
  • 对于高频调用场景，建议申请高权限的 API Key 或升级计划；
  • 可在 MCP 工具中加入冷却时间、调用失败重试等策略。

8. 📦 MCP 工具无法连接成功？​

可能原因与解决方法：

  • 判断 MCP 工具代码中是否使用了某些第三方 Python 包（如 requests, httpx, pydantic 等）；
  • 若需要这些包，请确保在 requirements.txt 文件中添加对应依赖；
  • 添加后重新部署工具，再尝试连接；
  • 可通过查看日志信息判断是否为缺包导致的 ModuleNotFoundError 错误。

建议：在开发或调试 MCP 工具时，优先在本地完整测试所有依赖项，再部署到平台中。

9. 🛠️ 如何调试 MCP 工具调用是否成功？​

建议操作：

  • 在 MCP 工具代码中打印 response.status_code 和 response.json()；
  • 使用 Postman 或 curl 测试 Dify API 调用参数和响应结构；
  • 使用 Xpert AI 的 MCP 工具测试台，模拟输入并观察调用日志。

10. 🔄 如何更新或升级 Dify 集成工具？​

操作建议：

  • 可通过 MCP 工具后台编辑代码，更新逻辑或 API 接口；
  • 如模版有新版本，建议重新安装或复制模版代码进行对比合并；
  • 更新后请记得保存工具集，确保生效。

如有更多未覆盖的问题，欢迎加入我们的开发者社群或联系技术支持获得帮助。