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

在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"]}

这里有两个关键细节需要特别关注。第一，函数名称必须采用蛇形命名法（snake_case），不能包含空格或特殊字符。第二，返回值必须是纯粹的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的type必须设置为object，并且required字段数组不能缺失，否则在Dify控制台中无法选中并配置该工具。

打包工具并注册到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）或函数名拼写有误。

整个流程并不复杂，关键在于精准把控这些细节。正所谓“工欲善其事，必先利其器”，工具链的搭建值得多花几分钟时间把每一步都验证到位。

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：Dify Agent自定义工具SDK开发实操指南要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题