AI Agent（六）- Dify 自定义工具实战 - 基于百度天气 API 搭建天气查询 Agent（天气智查助手）

文章目录

一、前言
二、整体实现思路
三、申请百度地图开放平台 AK
- 1. 注册百度地图开放平台
- 2. 登录百度地图开放平台
- 3. 创建应用并获取AK
- 4. 查看国内天气查询接口开发文档
- 5. 接口测试
四、创建自定义工具
- 1. OpenAPI 规范配置内容及说明
- - 1.1 OpenAPI 规范配置内容
    - 1.2 OpenAPI 规范配置说明
- 2. 配置OpenAPI 规范
- 3. 工具测试
六、搭建天气智查助手Agent
- 1. 创建Agent
- 2. System Prompt（系统提示词）
- 3. 调用工具
- 4. 功能测试与效果展示
- 5. 发布
- 6. 运行

一、前言

在 AI 应用快速落地的当下，Dify 作为低代码 AI 应用开发平台，支持通过自定义工具对接第三方 API，快速封装具备业务能力的 Agent。

本文将完整实战演示：基于百度天气开放 API，在 Dify 中配置 OpenAPI 规范、封装自定义工具、编写 Agent 系统提示词，最终实现一款可查询实况天气、7天预报、逐小时天气、生活指数、气象预警的天气查询智能助手。

适用场景：AI 问答助手、小程序天气模块、企业内部气象查询工具、智能客服天气能力扩展。

二、整体实现思路

调用第三方接口：百度地图开放平台天气 API，支持城市/区县维度查询；
接口标准化：编写符合 OpenAPI 3.1.0 规范的接口描述文件，接入 Dify 自定义工具；
工具封装：在 Dify 中导入 OpenAPI 配置，完成接口参数、响应、异常码配置；
Agent 配置：编写角色、任务、限制、输出格式四类系统提示词，规范 AI 解析与回复逻辑；
联调测试：调用工具获取原始天气 JSON 数据，验证 Agent 解析、格式化输出效果。

三、申请百度地图开放平台 AK

1. 注册百度地图开放平台

进入百度地图开放平台，点击页面右上角的「注册」按钮，进入开发者注册流程；按照指引填写用户名、手机号、密码和验证码，完成账号注册；若已有百度账号，也可直接点击「登录」，选择已有账号登录并完成开发者认证。

2. 登录百度地图开放平台

进入百度地图开放平台官网，点击右上角的「登录」按钮，在弹出的登录窗口中，可选择短信登录（输入手机号和验证码）、扫码登录或第三方账号登录，完成身份验证后即可进入平台后台。

3. 创建应用并获取AK

登录百度地图开放平台后，点击右上角「控制台」进入开发者后台，在左侧「应用管理」-「我的应用」页面，点击「创建应用」按钮，开始配置用于天气API调用的服务端应用。

在创建应用弹窗中，填写应用名称、选择「服务端」类型、勾选「国内天气查询」服务，同时在IP白名单中配置访问权限（测试阶段可设置为0.0.0.0/0，正式环境建议填写服务器公网IP），完成后点击「提交」即可创建应用。

应用创建成功后，在「我的应用」列表中找到目标应用，点击「访问应用（AK）」右侧的复制按钮，获取并保存生成的AK密钥，后续在Dify配置自定义工具时，将使用该密钥调用百度天气API。

4. 查看国内天气查询接口开发文档

在百度地图开放平台控制台顶部的搜索框中输入“国内天气”，在搜索结果里点击「国内天气查询开发文档」链接，即可进入对应的官方接口说明页面。

进入国内天气查询开发文档页面后，可以查看接口说明、API服务地址、请求参数、返回参数等详细信息，为后续在Dify中配置OpenAPI和自定义工具提供官方依据。

5. 接口测试

在百度天气接口文档的「国内天气查询」页面，输入你之前获取的AK密钥并确认，在右侧「在线运行」面板填写测试参数（如区县代码district_id和数据类型data_type），点击「执行」按钮，即可直接测试接口调用，成功后会在下方返回包含status和result字段的天气数据JSON响应，验证接口可用性。

四、创建自定义工具

1. OpenAPI 规范配置内容及说明

1.1 OpenAPI 规范配置内容

1{
2  "openapi": "3.1.0",
3  "info": {
4    "title": "百度天气查询接口",
5    "description": "根据城市、区县名称获取实时天气数据",
6    "version": "v1.0.0"
7  },
8  "servers": [
9    {
10      "url": "https://api.map.baidu.com",
11      "description": "百度地图开放平台服务地址"
12    }
13  ],
14  "paths": {
15    "/weather/v1/": {
16      "get": {
17        "summary": "城市+区县查询天气",
18        "description": "传入城市、区县名称，获取对应地区完整天气信息",
19        "operationId": "getWeatherByCityDistrict",
20        "deprecated": false,
21        "parameters": [
22          {
23            "name": "city",
24            "in": "query",
25            "description": "城市名称",
26            "required": false,
27            "schema": {
28              "type": "string",
29              "example": "昭通市"
30            }
31          },
32          {
33            "name": "district",
34            "in": "query",
35            "description": "区县名称",
36            "required": true,
37            "schema": {
38              "type": "string",
39              "example": "镇雄县"
40            }
41          },
42          {
43            "name": "data_type",
44            "in": "query",
45            "description": "控制返回内容类型：now=实况, fc=5天预报, index=生活指数, alert=预警, fc_hour=小时预报, all=全部数据",
46            "required": true,
47            "schema": {
48              "type": "string",
49              "enum": ["now", "fc", "index", "alert", "fc_hour", "all"],
50              "default": "all"
51            }
52          }
53        ],
54        "responses": {
55          "200": {
56            "description": "请求成功，返回天气数据",
57            "content": {
58              "application/json": {
59                "schema": {
60                  "$ref": "#/components/schemas/WeatherResponse"
61                }
62              }
63            }
64          },
65          "400": {
66            "description": "请求参数错误"
67          },
68          "401": {
69            "description": "AK密钥无效"
70          },
71          "403": {
72            "description": "IP白名单限制 / 权限不足"
73          },
74          "500": {
75            "description": "服务器内部异常"
76          }
77        }
78      }
79    }
80  },
81  "components": {
82    "schemas": {
83      "WeatherResponse": {
84        "type": "object",
85        "description": "天气接口统一返回结构",
86        "properties": {
87          "status": {
88            "type": "integer",
89            "description": "接口状态码，0 表示请求成功"
90          },
91          "result": {
92            "type": "object",
93            "description": "天气详细业务数据"
94          }
95        }
96      }
97    }
98  }
99}
100

1.2 OpenAPI 规范配置说明

基础信息与服务器配置：

字段	说明
openapi: "3.1.0"	声明使用 OpenAPI 3.1.0 规范，是 Dify 支持的主流版本
info.title	接口文档标题，会在工具列表中展示
info.description	接口功能概述，帮助 Dify 理解工具用途
servers[0].url	百度地图 API 的基础地址，后续路径会自动拼接在其后

接口路径与请求配置：

字段	说明
/weather/v1/	百度天气接口的请求路径，与基础地址拼接后为 https://api.map.baidu.com/weather/v1/
get	接口使用 GET 请求，适合查询类操作
summary	接口的简短功能说明，用于工具调用时的提示
description	接口的详细描述，帮助大模型理解工具能力
operationId	接口唯一标识，Dify 用它来区分不同工具函数

请求参数配置：

参数名	位置	类型	是否必填	说明
city	query	string	否	城市名称，如“昭通市”，用于辅助定位
district	query	string	是	区县名称，如“镇雄县”，为接口定位的核心参数
data_type	query	string	是	控制返回数据类型，支持 now/fc/index/alert/fc_hour/all，默认 all

响应与状态码配置：

状态码	说明
200	请求成功，返回天气数据，响应结构引用 WeatherResponse 模型
400	请求参数错误，如 data_type 传参不在枚举范围内
401	AK 密钥无效或未授权
403	IP 白名单限制或接口权限不足
500	百度服务端内部异常

数据模型配置：

模型名	字段	类型	说明
WeatherResponse	-	object	接口统一返回结构
status	integer	接口状态码，0 表示请求成功
result	object	天气业务数据，包含定位、实况、预报、指数等内容

2. 配置OpenAPI 规范

登录 Dify 平台后，进入「工作室」→「工具」页面，选择「自定义」分类，点击「创建自定义工具」按钮；在工具创建窗口中，填写工具名称（如“天气智查助手”），并将前面准备好的 OpenAPI 规范配置完整粘贴到 Schema 输入框中，完成接口定义的导入。

由于百度天气接口需要通过 ak 参数鉴权，因此在工具配置的「鉴权方法」中，选择「查询参数」类型，设置参数名为 ak，并将之前在百度地图开放平台获取的 AK 密钥填入值输入框，点击「保存」即可完成接口调用权限配置。

3. 工具测试

在Dify的自定义工具配置页面，找到刚创建的“天气智查助手”工具，点击右侧的「测试」按钮；在测试面板中输入查询参数（例如district填“西山区”、city填“昆明市”），点击「测试」按钮即可调用百度天气接口；若返回包含status:0和天气数据的JSON响应，则说明接口配置与鉴权均正常，最后点击「保存」完成工具的发布配置。

六、搭建天气智查助手Agent

1. 创建Agent

2. System Prompt（系统提示词）

为了让 Agent 能够将百度天气接口返回的原始 JSON 数据，转化为用户可读的结构化自然语言，在 Dify 中配置了完整的系统提示词。

角色设定：明确 Agent 为专业的天气数据查询与解读助手，依托百度天气API提供服务。
任务指令：定义了从接收用户查询、调用工具获取数据、解析整理信息到给出生活建议的完整流程，并支持按用户指定的 data_type 筛选展示内容。
限制要求：设定了严格的对话边界、数据真实性、信息安全和用户友好性规则，确保 Agent 回答的专业性和可靠性。
输出格式：规定了统一、清晰的结构化回复模板，并根据不同查询类型（实况、预报、指数）定义了对应的精简展示规则，避免信息冗余。

1### 1. 角色设定
2你是云小朵，你是专业的**天气数据查询与解读助手**，依托百度天气API获取全国各城市、区县的气象数据，能够精准解析实况天气、七日预报、逐小时天气、气象预警、生活指数等信息，为用户提供清晰、易懂、实用的天气服务。
3
4### 2. 任务指令
51. 接收用户提出的**城市/区县**天气查询需求，调用内置百度天气接口完成数据获取。
62. 根据接口返回的原始天气数据，分类整理信息：地理位置、实时实况、温度体感、风力风向、空气质量、未来7天天气预报、逐小时天气、气象预警、生活出行指数。
73. 结合天气情况给出合理的出行、穿衣、运动、洗车等生活化建议。
84. 若用户指定 data_type（now/fc/index/alert/fc_hour/all），仅展示对应类型的天气内容。
95. 接口返回异常时（参数错误、AK失效、IP限制、服务异常），如实告知用户故障原因及简单解决办法。
10
11### 3. 限制要求
121. 仅围绕**天气查询、气象解读、出行建议**开展对话，不回应与天气无关的问题。
132. 严格基于接口返回的真实数据作答，禁止编造、篡改天气信息。
143. 数据单位统一使用接口标准：温度(℃)、降水量(mm)、湿度(%)、能见度(m)。
154. 气象预警为空时，明确说明「当前该地区无气象预警信息」，不虚构内容。
165. 语言通俗易懂，避免堆砌专业代码、原始JSON字段，面向普通用户展示结果。
176. 不泄露接口AK、服务器地址等敏感配置信息。
187. 区分城市、区县层级，精准对应用户查询的地域，不混淆地区数据。
19
20### 4. 输出格式
21统一使用结构化格式回复，根据查询类型精简内容，格式如下：
22#### 通用标准格式（默认 all 全量数据）
23【查询地区】：XX省XX市XX区县
24【更新时间】：XXXX年XX月XX日 XX时
25
26#### 实时实况天气
27天气状况：xxx
28当前温度：xxx℃ | 体感温度：xxx℃
29相对湿度：xxx% | 能见度：xxx米
30风向风力：xxx
31空气质量：AQI xxx，PM2.5：xxx
321小时降水量：xxx mm
33
34#### 生活指数
35逐条展示各项指数名称、简要评价、详细建议
36
37#### 未来7天天气预报
38按日期+星期，展示当日最高/最低温、白天/夜间天气、风向风力
39
40#### 逐小时预报（近期时段）
41选取关键时段展示天气、温度、降水概率
42
43#### 气象预警
44有预警：展示预警类型、等级、详情；无预警：当前无气象预警
45
46#### 出行小贴士
47结合整体天气，给出穿衣、出行、户外活动等综合建议
48
49---
50补充规则：
511. 若用户仅查询实况(now)：只保留「查询地区、更新时间、实时实况天气、出行小贴士」模块。
522. 若用户仅查询预报(fc)：只保留「查询地区、更新时间、未来7天天气预报、出行小贴士」模块。
533. 若用户仅查询生活指数(index)：只保留「查询地区、更新时间、生活指数」模块。
544. 若接口报错：直接输出【异常提示】+ 故障原因 + 解决建议。
55

在 Dify 的「编排」页面中，将完整的系统提示词粘贴到提示词输入框内，提示词包含角色设定、任务指令、限制要求和输出格式四大模块，用于规范 Agent 的行为逻辑和回复样式。配置完成后，可通过右侧「调试与预览」窗口进行对话测试，验证 Agent 是否能正确调用工具并按预设格式返回天气信息。

3. 调用工具

在 Dify 应用的「编排」页面下方的「工具」模块中，点击「+ 添加」按钮，在弹出的工具列表中找到并勾选之前创建的「天气智查助手」自定义工具，开启工具开关，将其添加到当前 Agent 应用中，使大模型能够在对话中自动调用百度天气接口获取数据。

这里的「天气智查助手」自定义工具，是基于百度天气API封装的查询能力载体，它的核心作用是让Agent能够根据用户的城市/区县查询指令，自动调用接口获取实况天气、7天预报、逐小时天气、生活指数等结构化气象数据，而选择它是因为它完美适配Dify的工具调用机制，能通过OpenAPI规范定义接口参数与返回格式，配合系统提示词实现从用户自然语言提问到天气数据解析、再到结构化自然语言回复的完整闭环，让Agent真正具备实用的天气查询能力。

这里的「时间」工具，作用是为 Agent 提供当前系统时间的获取能力，它可以让天气查询回复里自动带上数据更新时间、区分“今天/明天/后天”等日期表述，让预报信息更贴合实际；搭配天气工具使用时，能让 Agent 精准处理时间相关的天气提问（比如“今天下午几点下雨”“未来三天的温度变化”），避免因缺少时间上下文导致的逻辑混乱。

4. 功能测试与效果展示

在 Dify 右侧的「调试与预览」窗口中，直接输入查询指令（如“帮我查询西山区现在的天气”）进行测试，Agent 会自动调用配置好的百度天气工具获取数据，并按照系统提示词中预设的结构化格式，返回包含查询地区、更新时间、实时天气及出行建议等信息的回复，验证工具调用与回复逻辑是否正常。

5. 发布

完成 Agent 功能测试并确认效果后，点击页面右上角的「发布」按钮，在下拉菜单中选择「发布更新」，即可将配置好的天气智查助手应用正式发布上线。发布后，你可以通过运行、嵌入网站、访问API等方式调用该应用，将其集成到不同的业务场景中使用。

6. 运行

在 Dify 应用页面，点击右上角「发布」按钮，在下拉菜单中选择「运行」选项，即可打开独立的对话窗口，开始正式使用天气智查助手。

在独立运行的对话窗口中，用户输入“西山区现在的天气”后，助手自动调用百度天气接口获取数据，并按照预设格式返回包含查询地区、更新时间、实时实况天气及出行小贴士的完整回复，实现了天气查询功能的最终落地。

《AI Agent（六）- Dify 自定义工具实战 - 基于百度天气 API 搭建天气查询 Agent（天气智查助手）》是转载文章，点击查看原文。