Dify 部署与企业自建 Agent 实战:五大案例从搭建到发布
本篇聚焦企业最关心的落地形态:自建 Agent(智能体)。前两章压缩保留部署与地基准备(环境为 2026-11 最新:Ubuntu Server 26.04.1 + Docker 28.x + Compose ≥v2.35.0 + Dify 社区版 1.14.x,Agent×Skills 这一代新体验),第三章给出 Agent 构建通用方法论,第四章是主体——5 个企业可直接复现的 Agent 案例(电商客服、text2SQL 数据分析、IT 运维初诊、HR 入职助手、多平台内容营销),每个案例逐步骤、带完整提示词与配置表。模型侧衔接 01-本地大模型服务器搭建 的 vLLM,知识库侧衔接 03-RAGFlow部署与企业应用。
📌 核心概念
0.1 Dify 的应用形态与 Agent 的位置
| 形态 | 特点 | 适用 |
|---|---|---|
| 聊天助手 | 简单对话 + 知识库 | 纯问答 |
| Agent(智能体) | LLM 自主决定调用哪些工具、何时调用、迭代完成 | 有系统要对接、有动作要执行 |
| 工作流 | 固定编排、可控可测 | 流程确定的管线 |
| 文本生成 | 单轮输入→输出 | 文案/抽取 |
关键认知:Agent 可独立成应用,也可以作为"Agent 节点"嵌入工作流(官方文档明确的双形态)——先用独立 Agent 快速验证,再把它作为节点挂进"问题分类器"路由体系,是企业级的标准演进路径。
0.2 Agent 的六要素(搭任何 Agent 都填这张表)
| 要素 | 配置位 | 说明 |
|---|---|---|
| ① 模型 | 右上角 | 必须支持 Function Calling(本地 vLLM 的 qwen3 系列支持) |
| ② 指令 | 提示词区 | 角色/边界/工具使用规则/输出格式,Agent 质量的 80% 在这里 |
| ③ 工具 | 工具区 | 四个来源见 0.3;Agent 自主决定调用时机 |
| ④ 知识库 | 上下文 | 作为"知识库检索"工具挂载,Agent 按需检索 |
| ⑤ 记忆 | 会话设置 | 对话记忆开/关、窗口长度 |
| ⑥ Skills | 技能区(1.14+) | 可复用的"子能力包"(格式规范/操作流程),跨 Agent 复用 |
0.3 工具的四个来源(企业自建 Agent 的核心命题)
| 来源 | 做法 | 典型 |
|---|---|---|
| 插件市场 | 工具 → 安装现成插件 | 网页搜索、时间、计算器 |
| 自定义 API 工具 | 贴 OpenAPI(Swagger) Schema,Dify 自动生成可调用工具 | 查订单、执行 SQL、调内部 ERP |
| 工作流即工具 | 把一个工作流发布为工具,供 Agent 调用 | 复杂审批流、批量处理 |
| MCP 服务器 | 接入 MCP 端点,工具列表自动同步 | 查 RAGFlow 知识库(03 篇 MCP 路线) |
0.4 架构速览(compose 服务 = Dify 全部)
api(无状态可横扩)|worker(异步任务,知识库量大先扩它)|web|plugin_daemon(插件运行时)|db(PostgreSQL,备份核心)|redis|sandbox(工具代码沙箱)|ssrf_proxy(出网防 SSRF)|weaviate(默认向量库,可换)|nginx(唯一对外入口)。社区版 Apache 2.0 精神下可自部署商用(以仓库 LICENSE 为准);企业版(3.13.x 文档线)追加 SSO/License 激活等能力。
📖 详细内容
一、部署(Ubuntu 26.04.1 + Dify 1.14.x,生产加固版)
# 1) 基础环境(Compose 必须 ≥ v2.35.0)
curl -fsSL https://get.docker.com | sudo sh && docker compose version
sudo apt install -y git
# 2) 锁版本克隆(版本号以 GitHub Releases 当期为准)
sudo mkdir -p /opt/dify && cd /opt/dify
sudo git clone https://github.com/langgenius/dify.git --branch 1.14.0 --depth 1
cd dify/docker && cp .env.example .env
# 3) 必改配置
openssl rand -base64 42 # 填入 .env 的 SECRET_KEY=
# .env 其余必改:DB_PASSWORD / REDIS_PASSWORD / EXPOSE_NGINX_PORT
# 4) 起服务并初始化
docker compose up -d && docker compose ps
# 浏览器 http://IP/install → 建管理员(生产别用弱口令)升级四步:docker compose down → git checkout 新tag → pull → up -d(保 .env;升级后回归工具类应用,Sandbox 的 Python/Node 路径有变更史)。
二、地基准备:模型与知识库(5 分钟清单)
A. 模型(设置 → 模型供应商 → 装 OpenAI-API-compatible 插件 → 添加两个模型):
| 字段 | LLM | Embedding |
|---|---|---|
| 名称 | qwen3-235b-local | qwen3-embedding-local |
| API Key | vLLM 的 sk-vllm-internal | 同左 |
| Base URL | http://10.1.40.50:8000/v1 | 同左 |
B. 知识库:规整文档用 Dify 内置(分段 500~1000/重叠 50~100,混合检索+Top-K 6);扫描件/复杂表格走 RAGFlow 外部知识库(/api/v1/dify 专用路径)或 03 篇 MCP 路线。召回测试过关再挂给 Agent。
三、Agent 构建通用方法论(五个案例的公共骨架)
Step 1|填六要素表(0.2):先在文档里想清楚每项,再进 Dify。 Step 2|写指令(提示词模板):
# 角色
你是<企业><岗位>助手,服务对象是<谁>。
# 能力边界
- 你可以调用工具:<工具A:干什么>、<工具B:干什么>
- 你只依据知识库/工具返回作答,检索不到就说"需转人工",禁止编造
# 工作流程
1. <先做什么:如先查订单/先检索知识库>
2. <再做什么:判断与执行>
3. <最后:按格式输出>
# 输出格式
<固定结构,如:结论/依据/建议操作>
# 禁止
<泄露内部信息/直接承诺退款/执行写操作等>Step 3|接工具:插件装完即用;自定义 API 在"工具 → 自定义 → 创建工具"贴 OpenAPI Schema;MCP 在"工具 → MCP"填端点。 Step 4|调试:右侧预览窗对话测试,展开"执行过程"看 Agent 的每一次工具调用与入参——Agent 排错就看这条链(不调用=指令没说清用途;调用参数错=Schema 描述不清)。 Step 5|发布:预览链接试跑 → 正式发布(公开网页/iframe/API)→ API 模式下每个应用独立 key。 进阶|嵌入工作流:新建工作流"开始→问题分类器→Agent 节点(选已验证的 Agent 同款配置)→直接回复",实现多 Agent 分诊路由(官方 Agent 节点即为此设计)。
四、企业自建 Agent 五大案例(逐步骤详解)
案例 1:电商智能客服 Agent(订单工具 + 自主决策)
目标:客户问"我的订单怎么还没到"——Agent 自主查订单→依据政策回答→异常件自动建工单。
前置准备:
- 订单查询 API(内部已有,或让后端提供只读接口);
- 售后政策知识库(退换货/物流时效文档,Dify 内置库);
- 转人工工单接口(可用 n8n Webhook 承接)。
逐步操作:
- 建应用:工作台 → 创建空白应用 → 选 Agent,命名"售后客服";
- 选模型:qwen3-235b-local(支持 Function Calling);
- 创建自定义工具(工具 → 自定义 → 创建工具),贴入 OpenAPI Schema:
openapi: 3.0.0
info:
title: 订单服务
version: 1.0.0
servers:
- url: http://erp.company.internal/api
paths:
/orders/{order_id}:
get:
operationId: getOrder
summary: 按订单号查询订单状态、物流单号与异常标记 # Agent 靠 summary 决定何时调用,必须写清楚
parameters:
- name: order_id
in: path
required: true
schema: { type: string }
responses:
'200': { description: 订单详情 JSON }
/tickets:
post:
operationId: createTicket
summary: 为异常订单创建售后工单并通知人工客服
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
order_id: { type: string }
reason: { type: string }
responses:
'201': { description: 工单号 }- 挂工具与知识库:Agent 里启用 getOrder、createTicket 两个工具 + "知识库检索"挂售后政策库;
- 写指令:
# 角色
你是电商售后客服,服务购买了本店商品的顾客。
# 能力边界
- 可查订单(getOrder:用户给了订单号或能从上下文提取时调用)
- 订单显示异常(延迟/破损/丢件)时可建工单(createTicket),工单 reason 用一句话概括
- 政策类问题先检索知识库,依据条款编号回答
# 流程
1. 判断用户意图:查订单 / 问政策 / 投诉
2. 查订单:调用 getOrder 后如实告知状态与预计时效
3. 异常订单:先安抚,再调 createTicket,回复工单号并说明 24 小时内有人联系
# 输出格式
结论 → 依据(订单状态/政策条款)→ 下一步动作
# 禁止
- 不承诺知识库之外的赔偿;不编造物流信息;用户情绪激烈时直接建工单转人工- 调试:预览输入"订单 20261105001 三天了还没到"→ 展开执行过程,确认链路:getOrder →(异常)→ createTicket → 回复工单号;政策问题确认走了知识库检索且带条款引用;
- 发布:iframe 嵌入官网客服窗;API 交给小程序端(
/v1/chat-messages)。
常见坑:工具不被调用→summary 写太虚;参数乱填→Schema 里补 description;operationId 必须英文唯一。
案例 2:text2SQL 数据分析助手(自然语言问数)
参考:AWS"基于 Dify Agent 快速部署 text2SQL 智能数据分析助手"。
目标:业务同事问"上个月华南区销售额环比?"→ Agent 生成 SQL → 只读执行 → 返回数字和解读。
前置准备:
- 业务库只读账号(权限收窄到分析库,SELECT-only);
- 执行 SQL 的 HTTP 接口:最简做法是用 n8n Webhook 包一个"POST /query {sql} → 查库 → 返回 JSON"(n8n 的 Postgres 节点天然承接,还留了执行日志);
- 表结构 DDL 整理成文本(供提示词使用)。
逐步操作:
- 建 Agent"问数助手",选模型(生成 SQL 建议用本地最强模型,准确率差距明显);
- 自定义工具贴 Schema:
openapi: 3.0.0
info: { title: 只读查询服务, version: 1.0.0 }
servers: [{ url: http://n8n.company.internal/webhook }]
paths:
/query:
post:
operationId: runSql
summary: 对分析库执行只读 SELECT 查询并返回 JSON 结果(禁止任何写操作)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
sql: { type: string, description: 单条 SELECT 语句,带 LIMIT }
responses:
'200': { description: 查询结果行数组 }- 指令里内嵌 Schema 与安全规则(text2SQL 的灵魂):
# 角色
你是数据分析助手,把业务问题翻译成 SQL 并执行、解读结果。
# 数据库结构(唯一事实来源,禁止臆造表名列名)
<贴 DDL:orders(id, region, amount, created_at...)、products(...)>
# 规则
1. 只生成单条 SELECT,必须带 WHERE 时间条件与 LIMIT(默认 100)
2. 涉及"环比/同比"分别算两段再算增长率
3. 先向用户复述口径(时间范围/地区/指标),再调 runSql
4. 结果为空时明确说"无数据",并给出你用的 SQL 让用户核对口径
# 输出格式
口径 → 结果数字(表格)→ 一句话解读 → 本次执行 SQL- 调试:问三个梯度问题(单指标/聚合/环比),核对 SQL 正确性与口径复述行为;
- 发布:内网数据分析门户嵌入;沉淀"高频问题→标准 SQL"进知识库逐步提高直答率。
常见坑:臆造列名→DDL 放提示词并强调"唯一事实来源";慢查询→规则强制 LIMIT;写库风险→只读账号+接口层白名单 SELECT 双保险(只靠提示词约束=没有约束)。
案例 3:IT 运维初诊 Agent(知识库 + Skills + 文件上传,Agent×Skills 新体验)
目标:员工描述网络/系统故障 → Agent 检索运维知识库 → 给编号排查步骤 → 生成工单草稿;可上传报错截图。
前置准备:把 notegen 的网络/运维文件夹笔记做成知识库(Markdown 直传,General 模板;排错类内容建议按 Q&A 重编,03 篇案例 D 同款);工单系统接口(或 n8n 承接)。
逐步操作:
- 建 Agent"IT 初诊助手";
- 挂工具:知识库检索(运维文档库)+ createTicket(同案例 1 的自定义工具套路);开启 Agent 的文件上传与预览(1.14 起 Agent 对图片输入更友好,报错截图直接传);
- 做一个 Skill(1.14 新能力):技能 → 新建"工单摘要格式",内容为固定模板(现象/影响范围/级别 P1-P4/建议处理人/已执行排查步骤)——写成技能而不是写进指令,好处:格式升级只改技能,其他 Agent 也能复用同一格式;
- 指令:
# 角色
你是企业内网 IT 初诊助手,服务全体员工。
# 流程
1. 收到故障描述(或报错截图)先检索运维知识库,命中则按文档给"编号排查步骤"
2. 每完成一步引导用户反馈结果,按结果决定下一步(最多 6 步)
3. 六步未解决或属于 P1(全员断网/核心系统不可用)→ 调 createTicket,按"工单摘要格式"技能输出
# 边界
- 只依据知识库与用户反馈判断,不臆测;高危操作(重启核心设备)只建议、不执行- 调试用例:"分支用户反馈访问总部 OA 时通时断" → 期望引用 VPN 排错思路输出"一看 IKE 二看 SA……"的编号步骤(13-防火墙VPN互联排错表正是知识库内容);
- 进阶(工作流化):把本 Agent 配置搬进工作流"开始→问题分类器(IT/HR/其他)→ Agent 节点 → 直接回复",全公司共用一个入口、按类分流;
- 发布:API 给企业 IM 机器人(配合 n8n 工作流 1 的邮件入口,形成 IM+邮件双通道)。
案例 4:HR 入职与制度问答 Agent
目标:员工问制度(年假/报销)秒答带出处;HR 触发入职流程——Agent 收集信息后调工具建邮箱账号、发入职清单邮件。
前置准备:制度手册知识库(高频问题按 Q&A 重编命中率最高,03 篇案例 C 同款);入职执行接口(两种现实做法:a. 直连 Google Admin/AD 的只建账号 API;b. 推荐调 n8n 入职工作流(n8n 工作流 3),n8n 侧统一管审批与通知)。
逐步操作:
- 建 Agent"HR 助手",挂知识库检索 + 自定义工具
triggerOnboarding(POST {name, department, start_date},summary 写"为已审批的新员工触发入职流程(建邮箱/发清单/通知部门),仅 HR 角色可触发"); - 指令要点:制度问题必须带制度文档出处;触发入职前必须复述四要素让用户确认(姓名/部门/岗位/入职日期)——写操作前的确认环是 HR 场景的合规底线;
- 调试三条线:制度问答(带出处)、入职触发(确认→调用→回报结果)、越权测试(普通员工让它建账号→应拒绝并说明仅 HR 可触发);
- 发布:内嵌 HR 门户;API 交给 IM 的 HR 机器人。
常见坑:写类工具没有确认环→必加;制度更新→知识库版本化,旧版下架(过期制度比没有更糟)。
案例 5:多平台内容营销 Agent(官方 30 分钟入门同款进阶)
对齐:Dify 官方 30 分钟快速入门的示例应用正是"多平台内容生成器"——本案例把它落到企业营销部。
目标:输入一次活动素材 → 产出小红书/公众号/邮件三种风格文案初稿。
逐步操作:
- 建 Agent"内容工厂";装插件工具:时间/日期(自动带发布日期)、网页搜索(抓当日热点做钩子,可选);
- 指令(提示词工程为主,无自定义工具也成立):
# 角色
你是<品牌名>的内容营销专家,一次输入产出三版文案。
# 输入
活动主题、核心卖点、目标人群、主推链接
# 任务
1. 小红书版:钩子开头+3 个卖点 emoji 段+话题标签 5 个,≤300 字
2. 公众号版:标题(≤20 字)+导语+小标题分段+行动号召,600-800 字
3. 客户邮件版:主题行+三段式(价值/证据/CTA),≤200 字,语气专业克制
# 边界
- 品牌调性:<如:专业、不说大话、不使用感叹号轰炸>
- 禁编造数据;引用事实仅限输入素材- 做成 Skill 复用:"品牌调性规范 + 三平台格式"存为技能"内容规范 v1",后续新 Agent(如视频脚本助手)直接挂同一技能,品牌一致性就有了单一维护点;
- 调试:同一素材跑两轮对比稳定性;bad case(超字数/调性漂移)回填到指令或技能;
- 发布:API + 批量脚本跑活动日历(对照 n8n 工作流 10 的审批发布流,生成→审批→发布全链路)。
五、生产化运维要点(速查)
- HTTPS 反代 +
client_max_body_size 50m(知识库传大文件);.env同步 X-Forwarded 头; - 备份三件套:PG 卷 + 向量库卷 + .env(只备 db=丢知识库);备份要演练恢复;
- 监控:worker 队列积压(知识库索引变慢第一信号)、API 日志接 Loki;
- 高可用演进:api/worker 多副本 + PG/Redis/向量库外置(AWS CDK 参考架构见官方博客);
- 企业版迁移(3.13.x):社区版运行中建企业库→停服→备份→切换部署包→激活 License,以 enterprise-docs 当期步骤为准。
💡 重点难点
- Agent 与工作流的选择:让模型"见机行事"用 Agent,流程确定要可控用工作流;成熟做法是工作流做骨架、Agent 节点做脏活;
- 指令质量决定 Agent 上限:角色/边界/流程/格式/禁止五段式缺一不可;工具用途写不清=永远不被调用;
- 自定义工具的 summary/description 是给模型看的说明书——比给运维看的文档更重要;
- 写操作三保险:确认环(复述让用户确认)+ 最小权限凭据 + 审计日志;提示词约束只是第三道防线;
- 执行过程面板是 Agent 的 X 光:不调用/调用错/调用顺序乱,全部在这看;
- Skills 的价值在复用:跨 Agent 的格式与规范沉淀成技能,别在每个应用里复制粘贴提示词;
- 知识库先过召回测试再挂 Agent,否则 Agent 会"理直气壮地答非所问";
- text2SQL 的安全底线是只读账号,提示词永远拦不住注入;
- 版本锁定与升级回归:锁 tag 部署,升级后必跑工具类应用回归(Sandbox 路径变更史);
- 发布即产品:每应用独立 API key、限流、审计,别把平台 key 下发给业务。
🔗 延伸拓展
- 官方路径:30 分钟快速入门(多平台内容生成器)→ Agent 节点文档(工作流中的自主推理)→ 构建 Agent(工具四来源与认证);
- 保姆级中文教程:Datawhale hello-agents:Dify 智能体创建操作流程(问题分类器→Agent→回复的路由范式);
- 联动本文件夹:Agent 的"手脚"交给 n8n(04 篇),知识库交给 RAGFlow(03 篇),模型交给 vLLM(01 篇);
- 进阶:MCP 工具批量接入、多 Agent 协作编排(规划者/执行者/审查者)、Agent 评测集建设。
面试/实操高频问答
- Dify 的 Agent 和工作流怎么选? Agent 由模型自主决策工具调用(适合边界模糊任务),工作流固定编排(适合确定性流程);生产常组合:分类器路由+Agent 节点执行。
- 给 Agent 接内部系统有哪些方式? 四种:插件市场、自定义 API(OpenAPI Schema)、工作流即工具、MCP 服务器。
- 自定义工具不被调用怎么办? 依次查:模型是否支持 Function Calling、工具 summary 是否讲清用途、指令是否提到何时用、Schema 参数是否带 description。
- Agent 带写操作的 API 怎么防护? 指令加确认环+接口侧最小权限+审计留痕;提示词约束不作为唯一防线。
- text2SQL 怎么防注入/防写库? 只读账号+接口白名单 SELECT 双保险,提示词内嵌 DDL 约束生成范围,结果带 SQL 供人工核对。
- 怎么观察 Agent 的决策过程? 预览窗的"执行过程"逐条展示工具调用与入参,排错主战场。
- Skills 和提示词的区别? Skill 是可复用、可独立演进的"能力包",跨 Agent 挂载;提示词是单应用私有的。格式规范类内容优先做成 Skill。
- 知识库挂上 Agent 后答非所问? 先用检索测试验证召回(调分段/Top-K/rerank),Agent 只是消费检索结果,检索不准 Agent 无解。
- Agent 如何嵌入现有 IM? 发布为 API,IM 机器人后端调
/v1/chat-messages,配合 n8n 做消息入口与工单出口。 - 上线前最小验收集? 三条线:正例(正常业务流)、负例(越权/边界外请求应拒绝)、bad case 回归集(历史翻车问题逐条过)。
记忆口诀
- 六要素:模型指令工具库,记忆技能不能少;
- 工具四源:插件装、API 贴、工作流发、MCP 挂;
- 指令五段:角色边界流程格式禁,一段都不能省;
- 安全:确认环、最小权、留审计,提示词是最后防线;
- 排错:先看执行过程链,再改工具说明书,最后才是调模型。
参考来源
官方文档:
| 来源 | 链接 | 对应章节 |
|---|---|---|
| Dify 官网(Agent 双形态:独立/Agent 节点) | https://dify.ai/zh | 0.1 |
| Agent 节点文档 | https://docs.dify.ai/zh/cloud/use-dify/nodes/agent | 0.1/案例 3 |
| 构建 Agent(工具四来源与认证) | https://docs.dify.ai/zh/self-host/use-dify/build/new-agent/build | 0.3 |
| 30 分钟快速入门(多平台内容生成器) | https://docs.dify.ai/zh/quick-start | 案例 5 |
| Docker Compose 部署(openssl 令牌/Compose ≥2.35) | https://docs.dify.ai/zh/self-host/deploy/quick-start/docker-compose | 第一章 |
| GitHub Releases(1.14.x/升级须知) | https://github.com/langgenius/dify/releases | 版本口径 |
企业方案与教程:
| 来源 | 链接 | 对应章节 |
|---|---|---|
| 阿里云:自主决策的 AI 电商客服助手 | https://www.aliyun.com/solution/tech-solution/rapidly-deploy-dify-to-accelerate-ai-application-development/2876507 | 案例 1 |
| AWS:Dify Agent text2SQL 数据分析助手 | https://aws.amazon.com/cn/blogs/china/quickly-deploy-text2sql-intelligent-data-analysis-assistant-based-on-dify-agent-on-aws | 案例 2 |
| Datawhale hello-agents:Dify 智能体保姆级流程 | https://github.com/datawhalechina/hello-agents/blob/main/Extra-Chapter/Extra03-Dify智能体创建保姆级操作流程.md | 第三章 |
| 博客园:智能客服工作流实战(2026.3) | https://www.cnblogs.com/zjdxr-up/p/19751810 | 案例 1 |
| 知乎:一文入门 Dify 构建 AI Agent | https://zhuanlan.zhihu.com/p/25771359587 | 第三章 |
本地配套:
| 来源 | 链接 | 对应章节 |
|---|---|---|
| 本文件夹:本地大模型服务器搭建 | 01-本地大模型服务器搭建.md | 第二章 |
| 本文件夹:RAGFlow 部署与企业应用 | 03-RAGFlow部署与企业应用.md | 知识库 |
| 本文件夹:n8n 部署与企业工作流 | 04-n8n部署与企业工作流.md | 案例 1/2/3/4/5 |
| 本文件夹:Dify 与 RAGFlow 部署及对接指南(底稿) | Dify_与_RAGFlow_部署及对接指南.md | 第二章 |
说明:①Dify 周更迭代,版本号以 GitHub Releases 当期为准,UI/节点名随版本微调;②案例中的内部 API 地址、订单号、指标均为示例;③案例效果需以自有业务数据验收,验收方法见第三章 Step 4 与面试问答 10。