1.Agent使用

什么是 Agent ？

• 定义：Agent Assistant 利用大语言模型（LLM）的推理能力，自主分解任务、调用工具、并在多步流程中持续优化，直至完成既定目标。

• 能力侧重：

  1. 自主决策：不仅回答问题，更能根据“指令”拆解子任务并组织执行。

  2. 工具交互：在对话中动态选用内置或自定义 API，触达外部系统与数据源。

  3. 闭环执行：可多次调用模型与工具，形成“思考—行动—反馈”闭环

Agent 的核心构成

1. Instructions（指令）

   • 相当于 Agent 的“作战手册”：在此文本中，你需明确定义

     • 任务目标（Goal）

     • 执行流程（Workflow Outline）

     • 可用资源（Knowledge Base、工具列表）

     • 行动限制（Timeout、Iteration Limit）

   • 示例：

     你是一名财报分析 Agent。目标：提炼季度营收动因，撰写 3 段核心结论。  
     流程：1) 调用“财报检索”工具获取原始数据…  
     限制：最多调用模型 5 次。
     

2. Context（上下文）

   • 将知识库或任意文档通过 Embedding 接入，供 Agent 做检索时调用。

   • 在“Context”区添加知识库工具，Agent 可随时检索以补充背景知识(docs.dify.ai)。

3. Tools（工具）

   • 类型

     • 内置工具：如网络搜索、表格计算、图片生成等；

     • 自定义 API：支持 OpenAPI/Swagger、OpenAI Plugin 标准，轻松接入企业内网或自研服务。

   • 工作流中调用

     • 在对话中直接以工具名触发；

     • 或通过“Function Calling”／“ReAct”策略，由模型自动决定何时调用(docs.dify.ai)。

4. Inference Modes（推理模式）

   • Function Calling

     • 依赖 GPT‑3.5/GPT‑4 系列内置的函数调用接口；

     • 具备更稳定的参数传递与结果解析能力。

   • ReAct

     • 针对不支持函数调用的模型（如部分开源 LLM），用「思考—行动—观察」(ReAct) 框架模拟调用流程(docs.dify.ai)。

5. Iteration Limit（迭代限制）

   • 控制 Agent 在一次任务中能调用模型／工具的最大轮数，避免循环调用或无限思考。

   • 在 Agent 设置面板可自行调节。

从零到一：创建与配置流程

1. 选择模板或自定义

   • 在 “Explore” 中直接导入官方 Agent 模板；

   • 或在 Dify Studio 中点击 “Create Agent” 从空白开始。

2. 填写 Instructions

   • 在 “Instructions” 栏精准描述目标与流程。

3. 接入 Context

   • “Context” → 添加已有知识库或上传文档；

   • 若模型原生支持文件处理（如 Claude 3.5 Sonnet），可开启 “Documentation” 特性(docs.dify.ai)。

4. 配置 Tools

   • “Tools” → 从内置列表勾选所需工具；

   • 或 “+ Add” → 输入自定义 API 的 OpenAPI/Swagger 链接；

   • 填写凭据与调用参数。

5. 调整 Agent Settings

   • 选择推理模式（Function Calling / ReAct）；

   • 设置迭代上限；

   • 配置首屏开场（Conversation Opener），为用户展示 Agent 能力示例。

6. 调试与预览

   • 进入 “Debug” 模式，输入测试问题；

   • 观察 Agent 在每一步的“思考”（模型原始日志）与“行动”（工具调用）输出；

   • 根据效果优化 Instructions、工具列表、Iteration Limit。

7. 发布上线

   • 调试通过后，点击 “Publish” 将 Agent 转为可对外调用的应用；

   • 支持生成专属访问 URL、集成到业务系统。

定制 Agent 策略与插件

• Agent Strategy Plugin 开发

  • 在 manifest.yaml 中添加 plugins.agent_strategies 字段，定义新策略（如 CoT、ToT、GoT 等）(docs.dify.ai)。

  • 编写策略实现文件（示例：function_calling.yaml），处理模型输入、工具路由与日志管理。

• Agent Node（Chatflow/Workflow）

  • 拖拽 “Agent” 节点到流程图：可在更大编排中调用 Agent，实现更复杂的自动化流水线(docs.dify.ai)。

常见应用场景示例

场景	示例
财报自动分析	Agent 检索并合并多份季度报告，提炼关键指标趋势并生成 PPT。
行程规划助手	Agent 调用地图 API、航班查询工具，自动设计最优旅游路线并输出行程表。
代码审查与修复	Agent 基于代码仓库检索问题单，调用静态分析工具，自动生成修复建议并提交 PR。
营销文案创意生成	Agent 多次迭代 A/B 文案，调用品牌数据库、情感分析工具，挑选最优文案输出。

2.应用工具箱

工具箱的总体架构

1. 内置工具（Built‑in Tools）
   由 Dify 官方预置，并持续维护升级，覆盖常见通用场景：

   • HTTP 请求：向任意 RESTful API 发起 GET/POST 等请求，支持 Header、Query、Body 自定义。

   • 知识库检索：基于向量搜索检索已接入的文档、FAQ、表格数据等。

   • 数据库操作：对接 MySQL、PostgreSQL 等关系型数据库，执行 SQL 查询与写入。

   • 电子表格：读取/写入 CSV、Excel，并在对话中展示表格或对其做聚合运算。

   • 定时任务：在 Workflow 中配置 Cron 表达式，实现准时触发。

2. 官方插件（Official Plugins）
   Dify 官方或生态合作方提供的标准化功能包，通过“一键安装”即可在工具箱内使用：

   • Web Search（Bing/Google）：自动抓取公开网页内容，并可进一步分析摘要。

   • Email/SMS：整合常见邮件和短信服务（如 SendGrid、Twilio），实现通知、验证码发送。

   • Calendar：对接 Google Calendar、Outlook Calendar，实现事件创建、查询与提醒。

   • 文件存储：支持 S3、阿里云 OSS 等对象存储操作，包括上传、下载、列举文件列表。

   • OCR 文字识别：调用第三方 OCR 服务（如 Google Vision、阿里云 OCR）将图片转文字。

3. 自定义工具（Custom Tools）
   任何符合 OpenAPI/Swagger 规范的自研后端服务、企业内部系统，都能通过工具箱接入：

   • 在“工具”→“添加自定义工具”界面，引入你的 OpenAPI JSON/YAML。

   • 填写鉴权信息（API Key、OAuth2、JWT 等），即可像内置工具一样调用。

   • 支持对输入输出参数做可视化配置，调用时由模型自动填充并解析结果。

工具箱在不同应用中的使用场景

应用类型	常见工具示例	场景说明
Chat Assistant	HTTP 请求、知识库检索、电子表格	用户问“本周销售排名前 5 的产品是什么？”，Agent 自动执行 SQL，返回表格并生成对话回复。
Agent	Web Search、Calendar、文件存储	旅行规划 Agent：调用地图 API、日历、文件存储（生成并上传行程 PDF）。
Chatflow	条件分支工具、OCR 文字识别	表单引导流程：上传身份证照片，OCR 工具提取信息，流程根据年龄分支跳转。
Workflow	定时任务、Email、SMS、电子表格	每天凌晨 2 点汇总报表，写入 Excel 并 Email 通知负责人。

工具配置与管理

1. 快速接入

   • 进入「设置 > 工具箱」或在应用编辑器侧边栏的「工具」面板。

   • 浏览“内置”与“官方插件”列表，一键启用；或点击“新建工具”导入自定义 API。

2. 授权与安全

   • 所有敏感凭据（API Key、Secret）统一使用 RSA PKCS1_OAEP 加密存储，租户隔离。

   • 可在“凭据管理”中查看/更新/吊销各工具的访问权限。

3. 调试与日志

   • 开启“调试模式”后，工具调用过程的原始请求与响应都会记录在“调用日志”里。

   • 支持按应用、按工具、按时间维度检索日志，方便快速排查问题。

4. 版本与灰度

   • 自定义工具支持版本管理，您可以在生产环境灰度新版本，确认无误后再全量切换。

   • 官方插件也会推送新版本更新通知，升级后可享受性能与功能增强。

进阶玩法

1. 复合工具链

   • 在 Chatflow/Workflow 中，可串联多个工具节点，让模型先检索、再计算、再生成报告，一气呵成。

2. 工具触发条件

   • 配置“条件表达式”或“正则匹配”，让模型只有在满足特定触发词或意图时才调用工具。

3. 工具能力扩展

   • 对于自有模型厂商，也可将「Function Calling」能力映射到自定义工具，使 LLM 原生识别并调用。

4. 指标监控

   • 在「监控中心」查看各工具的调用频次、成功率、平均耗时，帮助优化成本与体验。

3.工作流

定义与定位

特性	Chatflow	Workflow
定位	面向多轮对话的流程化编排	面向一次性/批量自动化任务的流程编排
交互方式	人–机多轮对话	无需持续交互，仅流程节点执行
终结形式	最终返回一条或多条对话回复	流程结束时不返回对话，而是完成后端任务或产出

• Chatflow
  通过“节点＋分支”方式，把对话拆解成可视化的步骤，适合构建有条件判断、记忆管理的复杂对话体验。
• Workflow
  类似 Chatflow 的低代码编排，但不绑定用户对话，主要用于初始化脚本、数据处理、定时任务、报告生成等后台流程。

核心概念对比

核心要素	Chatflow	Workflow
节点类型	Prompt 节点、条件分支、变量赋值、记忆节点、工具调用节点等	模型推理节点、条件分支、循环节点、工具调用节点、定时触发节点等
上下文管理	支持跨节点对话上下文共享（记忆节点可存储变量）	不保存用户对话上下文，节点间仅通过流程变量传递数据
用户输入	首屏问候／引导式问题→多轮输入	一次性参数输入（或通过外部触发），后续无需人为干预
触发方式	用户主动在 Chat 界面点击或输入驱动	可手动执行、API 调用或定时 Cron 触发
典型输出	针对用户的自然语言回复	文件（Excel、PDF）、数据库写入、消息推送（Email/SMS）等

配置流程详解

1. Chatflow 配置流程

1. 创建 Chatflow

   • 在 Dify Studio，点击 “Create → Chatflow”。

2. 节点拖拽与连线

   • 起始节点：设置首屏欢迎词或问题选择（可用按钮菜单引导用户）。
   • Prompt 节点：填写针对用户输入或变量的 Prompt 模板。
   • 分支节点：基于用户意图或变量值做条件判断，决定后续走向。
   • 记忆节点：将关键数据存入“对话记忆”，让后续节点可复用。
   • 工具节点：调用知识库检索、HTTP 请求、数据库查询等，插入外部数据。

3. 变量管理

   • 在“Variables”面板定义全局或局部变量，用于存储用户输入、工具结果等。

4. 测试与调优

   • 切换到 “Preview” 模式，模拟用户输入，验证流程逻辑与输出；
   • 根据对话断点或错误分支，调整节点条件和 Prompt 内容。

5. 发布与集成

   • 发布后可生成 Chat URL，或通过 Embed SDK 将 Chatflow 嵌入官网/小程序中。

2. Workflow 配置流程

1. 创建 Workflow

   • 在 Dify Studio，点击 “Create → Workflow”。

2. 节点搭建与参数化

   • Trigger 节点：选择触发方式——手动触发／API 调用／Cron 定时。
   • Model 节点：调用系统推理模型或文本生成模型，处理流程核心逻辑。
   • 工具节点：与 Chatflow 一致，可执行 HTTP 请求、数据库操作、电子表格处理等。
   • 循环 & 分支：配置 For-Each 循环节点或 If 条件节点，实现批量/分支处理。

3. 数据流管理

   • 每个节点可定义输入参数来源（上游节点输出或全局常量），并将执行结果输出到下游。

4. 日志与监控

   • 开启“Debug”后，可在“执行日志”里查看节点的输入、输出、执行耗时。

5. 部署与调度

   • 对定时触发 Workflow，可直接在面板设置 Cron 表达式；
   • 亦可通过 API 一键调用，实现与外部系统联动。

典型场景举例

场景类别	Chatflow 示例	Workflow 示例
客服导购流程	引导用户选择产品分类→根据偏好推荐商品→确认下单或跳转人工	无
智能问诊导航	多轮采集症状→分支判断紧急程度→提供初步诊断建议并推荐就医科室	无
定时日报	无	每日 8:00 汇总营销数据→生成 Excel→发送 Email 给运营负责人
批量报告生成	无	接收上游系统推送的参数列表→循环处理每个参数→批量生成 PDF 并上传 OSS

进阶要点与最佳实践

1. 共用组件化设计

   • 将“常用对话片段”或“工具调用”封装成子 Chatflow/Workflow，复用在多个项目中。

2. 参数化与变量传递

   • 充分利用全局变量与节点参数映射，降低流程改动时的重复维护成本。

3. 监控与告警

   • 对关键 Workflow 配置失败/超时告警，确保后台任务及时修复。

4. 灰度与版本管理

   • 对 Chatflow/Workflow 都支持多版本并行，对新流程做灰度测试后再全量切换。

5. 安全与权限

   • 合理划分团队成员权限，控制谁能编辑/发布 Chatflow 与 Workflow，保护生产环境稳定。

4.变量

系统变量（sys.*）

特性	Workflow	Chatflow
前缀	sys.	sys.
可读范围	全局（任意节点都可读取）	全局（任意节点都可读取）
主要变量	sys.files sys.user_id sys.app_id sys.workflow_id sys.workflow_run_id	sys.query sys.files sys.dialogue_count sys.conversation_id sys.user_id sys.app_id sys.workflow_id sys.workflow_run_id
作用侧重	记录文件上传、用户/应用/工作流标识等	记录用户输入、会话轮次、会话 ID 及与 Workflow 相同的标识参数

• 共性

  • 前缀均为 sys.。
  • 均可在全局任何节点中读取，用于标识用户、应用、运行等元信息。

• 差异

  • Workflow 专注于“批量”流程（一次性执行），其变量多为运行时元数据；
  • Chatflow 强调多轮对话交互，新增了 sys.query（首轮用户输入）、sys.dialogue_count（对话轮数）、sys.conversation_id（会话 ID）等，用于丰富对话逻辑。

环境变量

特性	Workflow & Chatflow（共通）
命名约束	不可重复、前端在“环境”配置中统一管理
数据类型	String、Number、Secret
读写权限	只读（节点内全局可读，不可在流程/对话中修改）
作用	隐藏敏感信息（API Key、DB 密码等），防止泄露至代码层

说明：环境变量在两种应用类型中完全一致，都是用于在编排界面中统一管理、并在各节点中安全引用。

会话变量（仅 Chatflow）

特性	Chatflow 独有
数据类型	String、Number、Object、Array[string]、Array[number]、Array[object]
读写权限	可读写（需要配合“变量赋值”节点写入）
作用	在多轮对话中临时存储上下文信息、用户偏好、上传文件等，模拟“备忘录”

说明：Workflow 类型流程为一次性线性执行，不支持回溯或多轮对话，因此不具备会话变量。Chatflow 则专门为多轮对话设计，引入可写的会话变量，以便在对话各轮之间维护上下文状态。