必须使用dify-tools sdk编写符合openapi 3.0规范的工具，经打包上传后才能在dify agent中启用；手动构造请求或上传非法json会导致工具不可用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在 Dify 平台为 Agent 添加能调用外部 API 的自定义工具，必须基于官方 Python SDK 编写符合 OpenAPI 3.0 规范的工具描述，并通过正确签名与注册流程接入工作流。直接上传未经校验的 JSON 或跳过 token 签名会导致工具在编排界面显示为“不可用”状态。
准备开发环境与依赖
创建独立虚拟环境并安装 Dify 官方工具 SDK：python -m venv dify-tool-env → source dify-tool-env/bin/activate（Windows 用 dify-tool-env\Scripts\activate）→ pip install dify-tools。
这一步不能省略，【dify-tools 是唯一支持自动注入 auth header 和 schema 校验的 SDK】，手动构造请求头或使用 requests 将无法通过 Dify 后端的工具签名验证。
编写工具逻辑函数
新建 weather_tool.py，定义一个接受 location: str 参数、返回天气数据字典的函数：
def get_current_weather(location: str) -> dict:
import requests
resp = requests.get(f"https://api.example.com/weather?q={location}")
return {"temperature": resp.json()["temp"], "condition": resp.json()["weather"]}
函数名必须是蛇形命名且不含空格或特殊符号；返回值必须是纯 Python 字典，不能含 datetime 对象或 requests.Response 实例——否则 SDK 序列化时会抛出 TypeError。
声明工具元信息与 OpenAPI Schema
方法一：使用 @tool 装饰器（推荐）
Dify 3.9.2更新重点增强系统安全性，引入 Chainguard 安全基础镜像并同步社区版 CVE 修复，同时优化 OpenSearch 向量存储兼容性、插件参数传输机制及 Helm 部署配置。新增工作流模型节点缓存能力，可减少重复凭证查询，显著提升复杂工作流初始化速度，为企业级 AI 应用提供更稳定、高效的运行体验。
在函数上方添加装饰器并传入中文名称与描述：
from dify_tools import tool@tool(name="查询实时天气", description="根据城市名获取当前温度和天气状况")def get_current_weather(location: str) -> dict:
...
方法二：手动构造 OpenAPI 3.0 JSON Schema
创建 weather_schema.json，严格按 Dify 要求填写 name（英文小写）、description、parameters 中每个字段的 type 和 description；【parameters 必须是 object 类型，且 required 字段数组不能遗漏】，否则工具在 Dify 控制台中无法被选中配置。
打包并注册工具到 Dify
第一步：将工具文件与 schema（若未用装饰器）放入同一目录，确保无 .pyc 或 __pycache__；
第二步：执行命令 dify-tools pack --entry weather_tool:get_current_weather；
第三步：命令成功后生成 weather_tool.zip；
第四步：登录 Dify 控制台 → 进入「Agent」→「工具」→「上传自定义工具」→ 选择该 ZIP 文件。
上传后需等待约 10 秒，状态从“处理中”变为“已启用”才可拖入工作流节点。若卡在“处理中”，说明 ZIP 内结构不符合要求——常见原因是入口函数路径写错，例如写成 weather_tool.py:get_current_weather（多写了 .py）或函数名拼错。
