这次我们来看一个 Dify 平台上的 Agent Skill 使用案例。如果你正在探索 AI Agent 开发或者想了解如何通过 Skill 扩展智能体能力这个简单示例能帮你快速理解核心概念和实操流程。Dify 是一个开源的 LLM 应用开发平台支持通过可视化方式构建 AI Agent、工作流和聊天应用。其中 Skill 是 Agent 的核心能力单元可以让智能体具备调用外部工具、执行特定任务的能力。本文将通过一个天气预报查询的案例演示如何创建、配置并测试一个简单的 Skill。最值得关注的是Dify 提供了低代码的 Skill 开发方式不需要深厚编程基础也能快速上手。平台支持本地部署和云端使用本文演示基于 Dify 云端版本本地部署流程类似但需额外注意环境配置。我们将重点看 Skill 的创建、参数配置、Agent 绑定和效果验证四个环节。1. 核心能力速览能力项说明平台类型低代码 LLM 应用开发平台核心功能Agent 构建、工作流设计、知识库管理、Skill 扩展Skill 作用为 Agent 添加外部工具调用能力开发门槛低代码支持 HTTP API 配置和自定义脚本部署方式云端 SaaS / 本地 Docker 部署硬件要求云端无需本地硬件本地部署需考虑模型推理资源接口能力支持 RESTful API 调用可集成外部服务适合场景企业助手、客服机器人、数据查询、自动化任务2. 适用场景与使用边界Dify 的 Skill 机制适合需要将 AI 能力与业务系统集成的场景。比如内部系统查询天气、订单、库存、信息检索知识库、文档、内容生成报告、邮件等。通过 Skill你可以让 Agent 调用已有的 API 服务而不必完全依赖大模型的内部知识。使用边界方面Skill 依赖于外部服务的可用性和稳定性。如果第三方 API 失效或限流会直接影响 Agent 的表现。另外涉及用户隐私或敏感数据的 Skill需要确保 API 调用的加密和权限控制。本文的天气预报案例属于公开数据查询适合入门练习。3. 环境准备与前置条件开始前你需要准备好以下内容Dify 账号访问 Dify 官网注册云端账号或本地部署后创建账号网络环境确保能正常访问 Dify 平台及第三方 API 服务如天气 APIAPI 密钥可选部分第三方服务需要 API Key本文示例使用开放的天气 API基本概念了解什么是 Agent、Skill、工作流Dify 文档有详细说明如果你选择本地部署 Dify还需要准备操作系统Windows 10/macOS/LinuxDocker 及 Docker Compose至少 4GB 内存推荐 8GB 以上稳定网络连接用于拉取镜像和模型4. Skill 创建与配置步骤下面我们一步步创建一个天气预报 Skill。4.1 创建 Skill登录 Dify 控制台进入「工具」页面点击「新建工具」工具类型选择「API」填写工具名称如「天气预报」描述信息可写「根据城市名称查询实时天气」4.2 配置 API 参数在 API 配置部分填写以下信息{ url: https://api.openweathermap.org/data/2.5/weather, method: GET, headers: { Content-Type: application/json }, params: { q: {{city}}, appid: 你的API密钥, units: metric, lang: zh_cn } }参数说明url天气 API 地址这里用 OpenWeatherMap 的免费接口methodHTTP 方法查询一般用 GETheaders请求头通常需要指定 JSON 格式params查询参数其中{{city}}是动态变量由 Agent 调用时传入如果你没有 OpenWeatherMap 的 API Key可以使用其他开放天气 API或先用静态数据测试。4.3 设置参数描述为了让 Agent 知道何时调用这个 Skill需要配置参数描述参数名称city描述要查询天气的城市名称如北京、上海必填是类型字符串这部分描述会帮助大模型理解这个 Skill 的用途和调用时机。4.4 配置响应处理API 返回的数据需要提取关键信息。在响应处理部分配置// 示例响应处理脚本 if (response.status 200) { const data response.json(); return { city: data.name, weather: data.weather[0].description, temperature: data.main.temp °C, humidity: data.main.humidity % }; } else { return { error: 天气查询失败 }; }这段脚本将原始 API 响应转换为更易读的格式方便 Agent 直接使用。5. 创建 Agent 并绑定 SkillSkill 本身不会主动工作需要绑定到 Agent 上5.1 新建 Agent在 Dify 控制台点击「创建应用」选择「Agent」类型应用名称天气查询助手模型选择根据需求选择 GPT-3.5、GPT-4 或其他支持的模型描述一个可以查询城市天气的智能助手5.2 启用工具在 Agent 的「工具」配置中找到刚创建的「天气预报」Skill 并启用。重要步骤在工具说明中清晰描述这个 Skill 的用途比如当用户询问城市天气时使用天气预报工具查询实时天气信息。需要提供城市名称参数。这个说明会引导大模型在合适的场景下调用 Skill。5.3 配置提示词在提示词编排中可以加入针对天气查询的指导你是一个天气查询助手当用户询问天气时请使用天气预报工具获取实时信息。 使用工具时注意 - 必须明确询问或获取城市名称 - 如果用户没有指定城市请主动询问 - 将工具返回的温度、天气状况、湿度等信息整合成自然语言回复6. 功能测试与效果验证现在可以测试整个流程了。6.1 基础功能测试在 Agent 的对话界面输入「北京天气怎么样」预期行为Agent 识别出天气查询意图自动调用天气预报 Skill传入城市参数「北京」获取 API 返回的天气数据生成自然语言回复如「北京现在晴温度 25°C湿度 40%」6.2 参数缺失测试输入「今天天气如何」预期行为Agent 发现缺少城市参数主动询问「请问您想查询哪个城市的天气」用户回复「上海」后继续完成查询6.3 错误处理测试输入「查询火星的天气」预期行为Agent 调用天气 API但 API 返回错误城市不存在Skill 的响应处理脚本返回错误信息Agent 生成友好提示「抱歉找不到火星的天气信息请检查城市名称是否正确」6.4 多轮对话测试连续对话用户「杭州天气」Agent「杭州现在多云温度 22°C湿度 65%」用户「那上海呢」Agent「上海现在小雨温度 18°C湿度 80%」这测试了 Agent 的上下文理解能力能识别「那上海呢」指的是天气查询。7. 高级功能与批量任务虽然单个天气查询很简单但 Skill 的真正价值在于批量和自动化场景。7.1 批量城市查询通过 Dify 的工作流功能可以构建批量查询创建工作流输入为城市列表添加循环节点遍历每个城市在循环内调用天气预报 Skill收集所有结果生成汇总报告这种模式适合需要同时监控多个城市天气的业务场景。7.2 定时任务与自动化结合外部调度系统可以实现每日定时生成天气报告特定天气条件触发告警与其他系统数据结合分析7.3 技能组合使用一个 Agent 可以绑定多个 Skill比如天气查询 地图服务 行程建议用户问「周末去北京玩穿什么衣服」Agent 可以查询北京天气根据温度推荐衣物提供出行建议这种技能组合让 Agent 真正具备多维度问题解决能力。8. 接口 API 与集成调用Dify 提供了完整的 API 接口可以将 Agent 能力集成到其他系统中。8.1 API 调用示例通过 Dify 的应用 API可以直接调用集成了 Skill 的 Agentimport requests def query_weather(city): url https://api.dify.ai/v1/chat-messages headers { Authorization: Bearer YOUR_DIFY_API_KEY, Content-Type: application/json } payload { inputs: {}, query: f{city}的天气怎么样, response_mode: blocking, user: test-user-123 } response requests.post(url, jsonpayload, headersheaders) return response.json() # 调用示例 result query_weather(北京) print(result[answer])8.2 批量任务处理对于需要处理大量查询的场景可以使用异步模式# 创建异步任务 response requests.post(https://api.dify.ai/v1/chat-messages, json{ inputs: {}, query: 北京天气, response_mode: streaming, # 异步流式响应 user: batch-job-001 }) task_id response.json()[task_id] # 轮询获取结果 while True: status_response requests.get(fhttps://api.dify.ai/v1/tasks/{task_id}) status status_response.json()[status] if status completed: result requests.get(fhttps://api.dify.ai/v1/chat-messages/{task_id}) print(result.json()[answer]) break elif status failed: print(任务执行失败) break else: time.sleep(1) # 等待1秒后继续查询9. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 不调用 Skill工具描述不清晰或模型不理解检查工具描述是否明确说明使用场景优化工具描述加入具体触发关键词API 调用返回错误参数配置错误或服务不可用查看 Dify 日志中的 API 响应检查 URL、参数格式验证 API 单独调用是否正常城市名称识别错误用户输入不规范或模型解析偏差测试不同城市名称的输入在提示词中加强城市参数提取指导响应处理脚本报错脚本语法错误或数据结构不匹配查看脚本执行日志测试各种 API 响应情况完善错误处理多轮对话上下文丢失Agent 配置或模型限制检查对话历史传递设置调整上下文长度或在提示词中强调记住关键信息10. 最佳实践与使用建议基于这个简单案例总结一些 Skill 开发的实用经验Skill 设计原则单一职责一个 Skill 只做一件事保持简洁明确触发在工具描述中清晰说明何时使用这个 Skill错误处理考虑各种异常情况提供友好的降级响应数据安全涉及敏感数据的 Skill 要做好权限控制和加密Agent 提示词优化明确技能调用条件减少误触发指导模型如何解释和呈现 Skill 返回的数据设置fallback机制当 Skill 不可用时提供替代方案测试策略先单独测试 API 接口确保正常再测试 Skill 的调用和响应处理最后在完整 Agent 环境中进行端到端测试覆盖正常流程、边界情况和错误场景性能考虑API 调用有延迟设置合理的超时时间考虑缓存频繁查询的结果批量任务时注意 API 调用频率限制这个天气预报案例虽然简单但涵盖了 Skill 开发的核心流程。掌握了这个模式你就可以为 Agent 添加更复杂的技能比如数据库查询、图像处理、业务系统集成等。Dify 的低代码方式大大降低了开发门槛让更多人能快速构建实用的 AI 应用。下一步你可以尝试创建更复杂的 Skill比如结合多个 API 的复合查询或者添加条件判断逻辑的工作流。真正的价值在于将 AI 能力与实际业务需求结合解决具体问题。 
长河君 · 2026/9/8 14:09:42 · 阅读 1.2k Dify平台Agent Skill开发实战：从天气预报案例入门AI智能体扩展
这次我们来看一个 Dify 平台上的 Agent Skill 使用案例。如果你正在探索 AI Agent 开发或者想了解如何通过 Skill 扩展智能体能力这个简单示例能帮你快速理解核心概念和实操流程。Dify 是一个开源的 LLM 应用开发平台支持通过可视化方式构建 AI Agent、工作流和聊天应用。其中 Skill 是 Agent 的核心能力单元可以让智能体具备调用外部工具、执行特定任务的能力。本文将通过一个天气预报查询的案例演示如何创建、配置并测试一个简单的 Skill。最值得关注的是Dify 提供了低代码的 Skill 开发方式不需要深厚编程基础也能快速上手。平台支持本地部署和云端使用本文演示基于 Dify 云端版本本地部署流程类似但需额外注意环境配置。我们将重点看 Skill 的创建、参数配置、Agent 绑定和效果验证四个环节。1. 核心能力速览能力项说明平台类型低代码 LLM 应用开发平台核心功能Agent 构建、工作流设计、知识库管理、Skill 扩展Skill 作用为 Agent 添加外部工具调用能力开发门槛低代码支持 HTTP API 配置和自定义脚本部署方式云端 SaaS / 本地 Docker 部署硬件要求云端无需本地硬件本地部署需考虑模型推理资源接口能力支持 RESTful API 调用可集成外部服务适合场景企业助手、客服机器人、数据查询、自动化任务2. 适用场景与使用边界Dify 的 Skill 机制适合需要将 AI 能力与业务系统集成的场景。比如内部系统查询天气、订单、库存、信息检索知识库、文档、内容生成报告、邮件等。通过 Skill你可以让 Agent 调用已有的 API 服务而不必完全依赖大模型的内部知识。使用边界方面Skill 依赖于外部服务的可用性和稳定性。如果第三方 API 失效或限流会直接影响 Agent 的表现。另外涉及用户隐私或敏感数据的 Skill需要确保 API 调用的加密和权限控制。本文的天气预报案例属于公开数据查询适合入门练习。3. 环境准备与前置条件开始前你需要准备好以下内容Dify 账号访问 Dify 官网注册云端账号或本地部署后创建账号网络环境确保能正常访问 Dify 平台及第三方 API 服务如天气 APIAPI 密钥可选部分第三方服务需要 API Key本文示例使用开放的天气 API基本概念了解什么是 Agent、Skill、工作流Dify 文档有详细说明如果你选择本地部署 Dify还需要准备操作系统Windows 10/macOS/LinuxDocker 及 Docker Compose至少 4GB 内存推荐 8GB 以上稳定网络连接用于拉取镜像和模型4. Skill 创建与配置步骤下面我们一步步创建一个天气预报 Skill。4.1 创建 Skill登录 Dify 控制台进入「工具」页面点击「新建工具」工具类型选择「API」填写工具名称如「天气预报」描述信息可写「根据城市名称查询实时天气」4.2 配置 API 参数在 API 配置部分填写以下信息{ url: https://api.openweathermap.org/data/2.5/weather, method: GET, headers: { Content-Type: application/json }, params: { q: {{city}}, appid: 你的API密钥, units: metric, lang: zh_cn } }参数说明url天气 API 地址这里用 OpenWeatherMap 的免费接口methodHTTP 方法查询一般用 GETheaders请求头通常需要指定 JSON 格式params查询参数其中{{city}}是动态变量由 Agent 调用时传入如果你没有 OpenWeatherMap 的 API Key可以使用其他开放天气 API或先用静态数据测试。4.3 设置参数描述为了让 Agent 知道何时调用这个 Skill需要配置参数描述参数名称city描述要查询天气的城市名称如北京、上海必填是类型字符串这部分描述会帮助大模型理解这个 Skill 的用途和调用时机。4.4 配置响应处理API 返回的数据需要提取关键信息。在响应处理部分配置// 示例响应处理脚本 if (response.status 200) { const data response.json(); return { city: data.name, weather: data.weather[0].description, temperature: data.main.temp °C, humidity: data.main.humidity % }; } else { return { error: 天气查询失败 }; }这段脚本将原始 API 响应转换为更易读的格式方便 Agent 直接使用。5. 创建 Agent 并绑定 SkillSkill 本身不会主动工作需要绑定到 Agent 上5.1 新建 Agent在 Dify 控制台点击「创建应用」选择「Agent」类型应用名称天气查询助手模型选择根据需求选择 GPT-3.5、GPT-4 或其他支持的模型描述一个可以查询城市天气的智能助手5.2 启用工具在 Agent 的「工具」配置中找到刚创建的「天气预报」Skill 并启用。重要步骤在工具说明中清晰描述这个 Skill 的用途比如当用户询问城市天气时使用天气预报工具查询实时天气信息。需要提供城市名称参数。这个说明会引导大模型在合适的场景下调用 Skill。5.3 配置提示词在提示词编排中可以加入针对天气查询的指导你是一个天气查询助手当用户询问天气时请使用天气预报工具获取实时信息。 使用工具时注意 - 必须明确询问或获取城市名称 - 如果用户没有指定城市请主动询问 - 将工具返回的温度、天气状况、湿度等信息整合成自然语言回复6. 功能测试与效果验证现在可以测试整个流程了。6.1 基础功能测试在 Agent 的对话界面输入「北京天气怎么样」预期行为Agent 识别出天气查询意图自动调用天气预报 Skill传入城市参数「北京」获取 API 返回的天气数据生成自然语言回复如「北京现在晴温度 25°C湿度 40%」6.2 参数缺失测试输入「今天天气如何」预期行为Agent 发现缺少城市参数主动询问「请问您想查询哪个城市的天气」用户回复「上海」后继续完成查询6.3 错误处理测试输入「查询火星的天气」预期行为Agent 调用天气 API但 API 返回错误城市不存在Skill 的响应处理脚本返回错误信息Agent 生成友好提示「抱歉找不到火星的天气信息请检查城市名称是否正确」6.4 多轮对话测试连续对话用户「杭州天气」Agent「杭州现在多云温度 22°C湿度 65%」用户「那上海呢」Agent「上海现在小雨温度 18°C湿度 80%」这测试了 Agent 的上下文理解能力能识别「那上海呢」指的是天气查询。7. 高级功能与批量任务虽然单个天气查询很简单但 Skill 的真正价值在于批量和自动化场景。7.1 批量城市查询通过 Dify 的工作流功能可以构建批量查询创建工作流输入为城市列表添加循环节点遍历每个城市在循环内调用天气预报 Skill收集所有结果生成汇总报告这种模式适合需要同时监控多个城市天气的业务场景。7.2 定时任务与自动化结合外部调度系统可以实现每日定时生成天气报告特定天气条件触发告警与其他系统数据结合分析7.3 技能组合使用一个 Agent 可以绑定多个 Skill比如天气查询 地图服务 行程建议用户问「周末去北京玩穿什么衣服」Agent 可以查询北京天气根据温度推荐衣物提供出行建议这种技能组合让 Agent 真正具备多维度问题解决能力。8. 接口 API 与集成调用Dify 提供了完整的 API 接口可以将 Agent 能力集成到其他系统中。8.1 API 调用示例通过 Dify 的应用 API可以直接调用集成了 Skill 的 Agentimport requests def query_weather(city): url https://api.dify.ai/v1/chat-messages headers { Authorization: Bearer YOUR_DIFY_API_KEY, Content-Type: application/json } payload { inputs: {}, query: f{city}的天气怎么样, response_mode: blocking, user: test-user-123 } response requests.post(url, jsonpayload, headersheaders) return response.json() # 调用示例 result query_weather(北京) print(result[answer])8.2 批量任务处理对于需要处理大量查询的场景可以使用异步模式# 创建异步任务 response requests.post(https://api.dify.ai/v1/chat-messages, json{ inputs: {}, query: 北京天气, response_mode: streaming, # 异步流式响应 user: batch-job-001 }) task_id response.json()[task_id] # 轮询获取结果 while True: status_response requests.get(fhttps://api.dify.ai/v1/tasks/{task_id}) status status_response.json()[status] if status completed: result requests.get(fhttps://api.dify.ai/v1/chat-messages/{task_id}) print(result.json()[answer]) break elif status failed: print(任务执行失败) break else: time.sleep(1) # 等待1秒后继续查询9. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 不调用 Skill工具描述不清晰或模型不理解检查工具描述是否明确说明使用场景优化工具描述加入具体触发关键词API 调用返回错误参数配置错误或服务不可用查看 Dify 日志中的 API 响应检查 URL、参数格式验证 API 单独调用是否正常城市名称识别错误用户输入不规范或模型解析偏差测试不同城市名称的输入在提示词中加强城市参数提取指导响应处理脚本报错脚本语法错误或数据结构不匹配查看脚本执行日志测试各种 API 响应情况完善错误处理多轮对话上下文丢失Agent 配置或模型限制检查对话历史传递设置调整上下文长度或在提示词中强调记住关键信息10. 最佳实践与使用建议基于这个简单案例总结一些 Skill 开发的实用经验Skill 设计原则单一职责一个 Skill 只做一件事保持简洁明确触发在工具描述中清晰说明何时使用这个 Skill错误处理考虑各种异常情况提供友好的降级响应数据安全涉及敏感数据的 Skill 要做好权限控制和加密Agent 提示词优化明确技能调用条件减少误触发指导模型如何解释和呈现 Skill 返回的数据设置fallback机制当 Skill 不可用时提供替代方案测试策略先单独测试 API 接口确保正常再测试 Skill 的调用和响应处理最后在完整 Agent 环境中进行端到端测试覆盖正常流程、边界情况和错误场景性能考虑API 调用有延迟设置合理的超时时间考虑缓存频繁查询的结果批量任务时注意 API 调用频率限制这个天气预报案例虽然简单但涵盖了 Skill 开发的核心流程。掌握了这个模式你就可以为 Agent 添加更复杂的技能比如数据库查询、图像处理、业务系统集成等。Dify 的低代码方式大大降低了开发门槛让更多人能快速构建实用的 AI 应用。下一步你可以尝试创建更复杂的 Skill比如结合多个 API 的复合查询或者添加条件判断逻辑的工作流。真正的价值在于将 AI 能力与实际业务需求结合解决具体问题。