📖 前言/概述

本文将从0到1完成Dify自定义工具的全流程开发，以天气接口爬取为例，串联FastAPI接口开发、natapp内网穿透、Dify OpenAPI工具配置三大核心环节，最终实现Dify Agent自动调用自定义天气查询工具的效果。

你将学会：

• 使用FastAPI快速开发可对外调用的天气查询API
• 借助natapp将本地FastAPI服务暴露到公网
• 通过OpenAPI Schema在Dify中创建自定义工具
• 配置Dify Agent并实现工具的自动调用

---

📁 第一步：创建FastAPI天气查询服务

1. 完整API代码编写

新建weather_api.py文件，复制以下完整代码（已集成CORS跨域支持，解决Dify调用跨域问题）：

from fastapi import FastAPI, Query
import requests
import uvicorn,json

app = FastAPI(
    servers=[
        {"url": "你的公网地址", "description": "natapp 公网服务"}
    ]
)


@app.get("/get_weather")
async def get_weather(city: str):
    appid = "27697298"
    appsecret = "Iw9did41"

    url = "http://v1.yiketianqi.com/free/day"
    params = {
        "appid": appid,
        "appsecret": appsecret,
        "unescape": 1,
        "city": city
    }

    res = requests.get(url, params=params)
    datas = json.loads(res.text)

    # 如果返回错误，添加提示信息
    if "errcode" in datas:
        datas["message"] = datas["errmsg"]
    return {
        "city": datas["city"],  # 城市信息
        "update_time": f"{datas['date']}\t{datas['update_time']}",  # 更新时间
        "wea": datas["wea"],  # 天气情况
        "tem": datas["tem"]  # 实况温度
    }

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8080)

2. 代码关键说明

1. 需先在tianqiapi.com注册账号后点击头像进入控制台，获取自己的appid和appsecret替换代码中对应位置
   

2. host="0.0.0.0"：必须配置成这样，否则本地服务仅能本机访问，无法通过natapp暴露
   运行示例：
   

3. /weather接口：接收city参数（城市名，如北京、上海），直接返回天气接口的JSON数据

4. 你的公网地址示例如下：
   

3. 本地启动与测试

！！！注意：需要先将host="0.0.0.0"改为host=“127.0.0.1”,才能进行本地测试

1. 命令行执行启动命令：python weather_api.py
2. 本地访问测试：浏览器打开http://127.0.0.1:8000/weather?city=北京
3. 成功返回：页面显示JSON格式的天气数据即代表本地服务正常
   运行示例：
   

---

🌐 第二步：用natapp将本地服务暴露到公网

1. 注册natapp账号

访问natapp.cn，使用手机号完成注册（免费隧道仅需注册，无需付费）

配图建议：natapp官网注册页面截图，标注出手机号输入、验证码获取位置

2. 申请免费隧道并获取authtoken

1. 登录后进入「我的隧道」→ 点击「购买隧道」→ 选择「免费隧道」

2. 隧道配置：协议选择HTTP，本地端口填写的填写必须与FastAPI服务端口一致
   下图圈住的就是端口号：
   

3. 配置完成后，在隧道列表中找到authtoken并记录（后续启动natapp需使用），如下图
   

3. 下载并启动natapp客户端

（1）下载客户端

访问natapp下载页面，选择对应系统版本（Windows选natapp_windows_amd64），解压到任意文件夹（如C:\natapp\），如图：

配图建议：natapp下载页面截图，标注出Windows版本的下载按钮

（2）启动natapp

1. 打开命令行，进入natapp解压目录：cd C:\natapp
2. 执行启动命令：natapp -authtoken=你的隧道authtoken
3. 启动成功标志：命令行显示Tunnel Status Online，并给出公网域名（如http://xxxx.natappfree.cc）
   示例：
   

4. 公网服务测试

将本地测试的地址替换为natapp公网域名，浏览器访问：http://你的natapp公网域名/weather?city=上海

• 成功：返回与本地一致的天气JSON数据，说明公网暴露成功
• 失败：检查FastAPI服务是否正常运行、natapp隧道端口是否与本地端口一致
  成功示例如下：
  

---

🤖 第三步：在Dify中创建自定义天气查询工具

1. 获取FastAPI自动生成的OpenAPI Schema

FastAPI会自动生成标准化的OpenAPI文档，访问以下地址获取JSON格式的Schema：

http://你的natapp公网域名/openapi.json

点击优质打印，直接复制页面中所有JSON内容，备用。

2. 手动编辑OpenAPI Schema（可选，适配Dify）

若自动生成的Schema缺少部分字段，可直接复制以下模板，替换servers中的公网域名即可使用：

{
  "openapi": "3.1.0",
  "info": {
    "title": "天气查询 API",
    "version": "1.0.0",
    "description": "用于Dify Agent调用的天气查询接口，支持查询全国城市实时天气"
  },
  "servers": [
    {
      "url": "你的natapp公网域名",
      "description": "natapp内网穿透公网服务地址"
    }
  ],
  "paths": {
    "/weather": {
      "get": {
        "summary": "获取城市天气信息",
        "description": "输入城市名称（如北京、上海），返回实时天气、温度、湿度、风力等信息",
        "operationId": "get_weather",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "城市名称，无需带市/区，如：北京、广州、成都"
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回天气信息",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "city": {"type": "string", "description": "城市名称"},
                    "wea": {"type": "string", "description": "实时天气状况"},
                    "tem": {"type": "string", "description": "实时温度"},
                    "humidity": {"type": "string", "description": "空气湿度"},
                    "win": {"type": "string", "description": "风向"},
                    "win_speed": {"type": "string", "description": "风力等级"}
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

3. Dify自定义工具创建步骤

1. 登录Dify平台，进入「工具」→「自定义」→「创建自定义工具」
2. 填写工具基础信息：
   • 工具名称：天气查询
   • 描述：查询全国城市实时天气，返回天气、温度、湿度等信息
3. 配置Schema：将复制的OpenAPI JSON粘贴到「Schema」输入框
4. 鉴权方法：选择「无」（本次接口无需鉴权）
5. 点击「保存」，工具创建完成

配图建议：分三步截图，① Dify工具管理页面的「创建自定义工具」按钮；② 工具信息填写页面，标注各字段填写位置；③ Schema粘贴完成后的页面截图

4. 工具验证

保存后，在「可用工具」列表中能看到get_weather方法，路径为/weather，说明工具配置成功。

配图建议：Dify可用工具列表截图，标注出get_weather方法的相关信息

---

🎯 第四步：配置Dify Agent并实现工具自动调用

1. 创建Dify Agent应用

1. 进入Dify「工作室」→「创建应用」→ 选择「Agent」类型
2. 应用名称：智能天气助手（可自定义）
3. 点击「创建」，进入Agent配置页面

配图建议：Dify创建应用的页面截图，标注出「Agent」类型的选择按钮

2. 为Agent添加自定义工具

1. 在Agent配置页面，找到「工具」模块，点击「添加工具」
2. 在工具列表中找到「天气查询」，勾选启用并保存

配图建议：Agent工具添加页面截图，标注出「天气查询」工具的勾选位置

3. 配置Agent系统提示词

在「系统提示词」输入框中填写以下内容，引导Agent正确调用工具：

你是一个专业的智能天气助手，擅长为用户查询全国各城市的实时天气信息。
当用户向你询问任意城市的天气时，必须使用「get_weather」工具进行查询，工具的「city」参数为用户询问的城市名称（无需带市/区）。
查询到结果后，将核心信息（城市、天气、温度、湿度、风力）整理成简洁易懂的自然语言回复用户，无需返回原始JSON数据。

配图建议：Dify Agent系统提示词配置页面截图，标注出提示词输入框

4. 最终效果测试

在Agent聊天框中输入问题：北京今天的天气怎么样？，Agent会自动调用天气查询工具，并返回整理后的自然语言结果。

示例回复：

北京今日天气为晴，实时温度28℃，空气湿度45%，吹3级东北风，整体天气状况良好，适合外出。

配图建议：Dify Agent聊天界面截图，包含用户提问、Agent工具调用过程、最终回复的完整内容，标注出「工具调用」的标识

---

📋 常见问题与解决方案

问题现象	核心原因	解决方法
Dify创建工具失败，提示缺少servers	OpenAPI Schema中无服务器地址	在Schema中添加servers字段，填写natapp公网域名
工具调用返回404错误	natapp域名变化/FASTAPI未运行	① 更新Schema中的公网域名；② 重启FastAPI服务
Dify调用工具出现CORS跨域错误	FastAPI未配置CORS中间件	检查代码中是否添加CORSMiddleware，配置allow_origins=["*"]
Agent不自动调用工具	系统提示词未明确工具使用规则	优化提示词，明确「何时调用、调用哪个工具、传什么参数」
natapp公网访问失败	本地端口与隧道端口不一致/服务未启动	① 检查natapp隧道本地端口为8000；② 确认FastAPI服务正常运行
天气接口返回报错	appid/appsecret错误/过期	重新在tianqiapi.com获取并替换代码中的对应参数

配图建议：制作一张「问题排查流程图」，从「问题现象」到「排查步骤」再到「解决方法」，逻辑清晰

---

📁 完整项目结构

fastapi-dify-weather/
├── weather_api.py  # 核心FastAPI服务代码
├── openapi.json    # OpenAPI Schema备份（可选）
└── README.md       # 项目说明文档（可选）

配图建议：电脑文件夹截图，展示上述项目文件结构

---

🎯 实战总结

通过本次实战，我们完成了从本地API开发到公网暴露，再到Dify工具集成的全流程，核心收获：

1. ✅ 掌握FastAPI快速开发API的方法，解决跨域调用问题
2. ✅ 学会使用natapp实现本地服务的内网穿透，快速获取公网访问地址
3. ✅ 理解OpenAPI Schema的标准化格式，能在Dify中创建自定义工具
4. ✅ 掌握Dify Agent的配置方法，引导AI自动调用自定义工具

核心逻辑：Dify自定义工具的本质是通过OpenAPI Schema标准化接口，让Agent识别接口的「调用地址、参数、返回值」，再通过内网穿透让本地开发的接口成为Dify可访问的公网接口，最终实现AI的工具调用能力扩展。

---

📚 扩展与进阶建议

1. 接口优化：为天气接口添加参数校验、异常处理，避免城市名错误导致的返回失败
2. 功能扩展：增加未来7天天气预报、空气质量查询等接口，丰富工具能力
3. 域名固定：购买natapp付费隧道（9元/月起），获取固定公网域名，避免免费域名频繁更换
4. 鉴权添加：为FastAPI接口添加API Key鉴权，防止接口被恶意调用
5. 多工具集成：将本方法复用至其他接口（如快递查询、股票查询），为Dify Agent添加更多工具
6. 本地大模型适配：结合Dify本地大模型部署，实现全流程本地化，数据更安全

配图建议：natapp付费隧道套餐截图，标注出「固定域名」核心权益；FastAPI鉴权代码示例截图（简易版）