Dify Agent自定义工具SDK开发实操指南

要在 Dify 平台为 Agent 挂载能调用外部 API 的工具，关键路径只有一个：走官方 Python SDK，将工具描述编写为符合 OpenAPI 3.0 规范的 JSON，再完成签名和注册。任何尝试绕过规范的捷径——比如直接上传未校验的 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 装饰器（推荐）

在函数上方添加装饰器，传入中文名称和描述，代码简洁直观：

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）或函数名拼写错误。

整条链路并不复杂，核心在于每个细节都需精准对齐。工具链的搭建值得多花几分钟逐一验证，避免后期排查更大的麻烦。