Dify 搭建工作流 Agent 全流程实战（含学生成绩查询案例）

前言很多人第一次接触 Dify容易把它当成一个“问答机器人平台”。但在实际业务里真正有价值的是把大模型能力流程化做成稳定、可发布、可维护的工作流 Agent。本文整理一条完整主线工作流基础知识工作流搭建 Agent 的流程发布应用的流程并结合“学生成绩查询”案例讲透实战落地一、先搞懂什么是 Dify 工作流 Agent在 Dify 里工作流 Agent 并不是“一个模型直接回答”而是将一个任务拆成多个节点按流程自动执行。常见节点包括开始节点接收用户输入如queryLLM 节点意图识别、SQL 生成、结果总结代码执行节点格式转换、字段提取、异常兜底条件分支节点根据结果走不同路径知识检索节点做 RAG 检索工具/插件节点数据库查询、图表生成等直接回复节点阶段性输出提示和结果一句话总结工作流 Agent 大模型理解 规则控制 工具执行 分支兜底。二、工作流基础知识第六章核心结合“跨境电商助手”和“学生成绩查询”两个案例可以提炼出 4 个关键原则。1先分流再深处理先判断问题类型如打招呼、转人工、专业问题简单问题直接返回复杂问题再进入检索/数据库流程。这样能降低成本、减少延迟、提升稳定性。2LLM 输出尽量结构化让 LLM 输出 JSON而不是纯自由文本。随后用代码节点解析交给下游节点继续处理。这一步是把“不可控语言输出”变成“可控流程输入”的关键。3必须设计兜底路径例如检索有结果 - RAG 回答检索无结果 - 闲聊模型回答JSON 解析失败 - 返回默认结构避免流程中断好的工作流不只是主路径通异常路径也要可运行。4过程可反馈用户有感知像“SQL 正在生成中”“SQL 生成完毕”“模型正在汇总中”这类中间回复能显著改善体验减少用户焦虑感。三、搭建工作流 Agent 的标准流程这套流程可以复用到大多数 Dify 项目。步骤 1定义业务目标与输入输出输入用户自然语言问题输出文本答案、结构化数据、图表、人工链接等步骤 2画出流程分层接入层开始节点理解层意图识别 / SQL 生成执行层知识检索 / 数据库 / 插件表达层结果汇总 / 直接回复步骤 3约束模型输出格式Prompt 强制输出 JSON配 Few-shot 样例代码节点做 JSON 提取与解析校验步骤 4设置条件分支有数据 / 无数据命中规则 / 未命中规则成功 / 失败步骤 5接入工具和插件Database执行 SQLECharts输出图表柱状图/折线图/饼图步骤 6增加中间提示在关键耗时节点前后增加“直接回复”节点提升交互友好度。步骤 7联调和测试覆盖正常输入、边界输入、异常输入确保分支和兜底都能工作。步骤 8发布与集成支持 API 调用与前端嵌入两种方式按业务场景选择。四、实战案例学生成绩查询工作流 AgentNLP2SQL这个案例是“自然语言 - SQL - 查询 - 分析 - 图表”的完整链路非常适合写入博客作为主案例。1业务目标用户输入“查询全校各科平均分情况”“哪个班不及格率最高”系统输出可读结论Markdown可选图表ECharts2核心链路拆解开始节点接收queryLLM 节点把自然语言转成 SQL JSON 数组代码节点提取并解析 JSON循环节点遍历 SQLDatabase 工具执行每条 SQL代码节点汇总查询结果LLM 节点生成业务解读和图表参数条件分支判断是否需要图表ECharts 节点输出图表 最终回复3案例价值不再是单轮问答而是数据分析流程LLM 负责理解工具负责执行代码负责约束输出结果既可读又可视化适合业务决策场景五、发布应用流程重点是两种发布方式API 发布、前端嵌入发布。1方式一API 接口发布文档中的关键点基础 URL 示例http://localhost/v1鉴权方式Authorization: Bearer app-xxxx可先用 Postman 联调再接入业务后端推荐做法API Key 放后端不放前端对外统一走后端代理便于限流、审计和权限控制2方式二Web 页面嵌入发布通过嵌入脚本快速接入网页配置window.difyChatbotConfig引入embed.min.js使用 token 绑定应用适用场景快速演示内部知识助手官网/活动页聊天窗口六、生产环境注意事项1密钥安全不要把生产 token 明文写在前端 HTML 中使用后端签发临时凭证或 API 代理2Prompt 与输出约束Prompt 里明确字段和格式要求代码节点做兜底解析防止模型输出波动影响流程3错误与超时处理数据库查询失败时给用户友好提示关键节点加重试或分支兜底4可观测性记录每次请求的输入、SQL、执行耗时、错误信息便于后续调优和排障总结Dify 工作流 Agent 的核心不是“让模型更会聊”而是“让 AI 能稳定交付业务结果”。通过LLM 理解 代码约束 工具执行 分支兜底我们可以把一个演示级聊天机器人升级为可上线、可维护、可扩展的智能应用。以学生成绩查询案例为例AI 不仅能理解用户问题还能自动生成 SQL、完成数据库查询、汇总分析并生成图表真正实现从“提问”到“决策支持”的闭环。