Dify New Agent 实操：Build 模式、持久文件与 build_note 记忆机制

Dify 的 New Agent 把「搭一个智能体」这件事的形态改了：过去是填表单——写提示词、挑工具、挂知识库，一项项配完再发布；现在多了一条对话式构建的路——你在 Build 模式里用自然语言描述要什么，Agent 自己把技能、文件、环境变量配起来，你确认后落地。这篇教程带你用 Build 模式搭一个能用的 Agent，并把持久文件、build_note、版本恢复这些新机制的边界一次讲清。

🎯 适合人群：用 Dify 云端版或自托管版搭智能体的产品/开发人员，不要求会写代码。前置只有一个硬条件：选一个原生支持工具调用的模型，后面会解释为什么这条不能省。

先理解：New Agent 的组件分工

一个 New Agent 由几块组成，各有各的职责：

组件	是什么	谁来维护
Model	推理引擎，必须原生支持工具调用	你选，官方对推荐的模型有标记
Prompt	Agent 级指令：角色、规则、输出要求	你写；build_note 已覆盖的不必重复
Skills	可复用的工作方法，Agent 按需取用	Build 模式可自动生成
Files	参考材料与沙箱文件，含 build_note	Build 模式产出 + 你上传
Tools	联网、文档处理、API 调用等行动能力	你配置或 Build 中安装
环境变量	沙箱内可读的键值对，如 ORDER_API_URL	高级设置或 Build 中设置

Step 1：创建 Agent，选对模型

1 入口在 Agents → Create

1. 侧边栏进入 Agents，点 Create → Create from Blank
2. 起名：用职责命名（如 会议纪要助手）
   或起个人格名（如 Max），都能随时改
3. 选模型：优先选带 Recommended 标记、
   原生支持工具调用的模型

模型这步不能将就。官方排障文档明确指出：通过 OpenAI 兼容端点（如 vLLM 自部署）提供的模型，常常不具备完整的原生工具调用支持，结果是 Agent 报错、或者从不调用工具——而且这个问题在 Build 对话和发布后的运行里都会出现。自部署模型上线前先验证工具调用能力，不行就换。

Step 2：用 Build 模式对话式搭起来

2 描述任务，看它自己配

Build 模式里你不是在填配置，而是在跟一个「正在成型」的 Agent 对话。它会边聊边改配置面板，所有变更列在 Build draft 里：

开场消息示例：
  「搭一个把原始会议记录转成结构化纪要的 Agent：
   输出与会人、决议、待办三项，
   待办要有负责人和截止时间。」

它的动作：
  · 自动生成 Skills（可复用的工作方法）
  · 生成 build_note.md（后面细讲）
  · 需要时自己装程序、建文件

你的动作：
  审 Build draft → Apply 保留 / Discard 丢弃
  → 两者都会退出 Build 模式并清空对话

💡 开场消息别追求一步到位——官方示例的写法是「先给最小可用版，边聊边补细节」。Build 对话本身是可多轮的，每轮聚焦一个组件（先定输出格式，再补工具，最后调环境变量），Build draft 会更干净，Apply 的粒度也更好控制。

Discard 是全量回滚，不是「只丢这条消息」。它会连本轮对配置的修改和 File system 里的持久文件一起丢掉。想分步落地就每谈成一小块 Apply 一次；一旦 Discard，之前没 Apply 的东西全部没有了。另外 Build 模式进行中，配置面板是只读的——想手动改配置，先退出 Build。

Step 3：吃透 File system 的持久规则

3 哪些文件会留下来，哪些不会

Build 模式中 Agent 在真实沙箱里干活，点右上角 File system 能浏览它的全部文件。持久规则是这套机制的核心：

场景	文件去向	后果
Build 对话中新增（模板、装的工具、草稿）	Persistent（默认）	进入 Agent 本体，随每次对话与工作流运行生效
你明说「这个文件保持临时」	Temporary	本次 Build 对话结束时清除
发布后的运行中新增	永远 Temporary	不改变 Agent 本体，跑完即清

💡 这套规则的设计意图是：Build 阶段你在「塑造 Agent 本体」，所以产出默认固化；发布后的运行是「Agent 在干活」，干活的痕迹不该污染本体。理解了这层对称，持久行为就不用死记。

Step 4：管理 build_note.md——Agent 的跨会话记忆

4 一次 Apply 之后去读它

Build 对话里 Agent 会把它做的事记进一份 build_note.md，Apply 之后出现在 Files 里。它在每次新对话开始时读回这份笔记，与你的 Prompt 合并成指令。这意味着：

build_note 管理守则：
1. Apply 后先通读：Agent 对角色的理解、
   已定的格式与决策都在里面，漏了就补
2. 改内容：让它在 Build 模式里改，别在外面另存一份
   ——你下载再上传的副本只是普通文件，
   下一次 Build 对话会另生成一份新笔记
3. Prompt 只放 build_note 没覆盖的 Agent 级指令
   （两者重复没有害处，但浪费上下文）
4. 想从干净记录重来：删除 Files 里的笔记即可

build_note 是记忆也是偏见。跨 Build 对话延续时，它会带着上次聊天里定下的格式与决策出发——这通常省事，但如果那些决策已经过时，记得回 Build 模式让它修订笔记，否则它会在错误的前提上继续盖楼。

Step 5：环境变量与敏感信息脱敏

5 配置共享地址，遮住敏感值

在高级设置里可以加环境变量——Agent 在沙箱里干活时可按名读取。典型用法：所有技能脚本共用一个 ORDER_API_URL，从测试切生产只改一处。支持导入 .env 批量添加，也可以让 Agent 在 Build 模式里帮你设。

# 防止敏感串出现在命令输出里被 Agent 读到，
# 用官方提供的脱敏模式变量：
DIFY_AGENT_SHELL_REDACT_PATTERNS=...   # 按文档配置要遮蔽的模式

环境变量不是保险箱。文档明确说明：存这里的值可能出现在 Agent 可读的命令输出里。密钥类信息优先走 Dify 的凭据体系，环境变量只放地址、开关这类非敏感配置，并配合脱敏模式使用。

Step 6：发布、回滚与多端接入

6 版本历史连沙箱文件一起回滚

编辑自动存草稿，就绪后发布让该版本生效。几个发布期要点：

操作	行为	注意
版本历史回滚	同时把沙箱里的持久文件恢复到该版本	回滚是「整包还原」，别只当配置回滚用
Chat Features	欢迎语、建议问题、语音等体验项	发布前在 Preview 里终验，Preview 不改配置
Access Point	Web 应用链接 / 嵌入 / Service API 三种形态	按消费方选择，API 走服务密钥
工作流 Agent 节点	把 Agent 邀进 Workflow 处理某一步	与独立发布不冲突
DSL 导出	跨工作区分享	不含 Skills 与 Files，要随包另发

用 DSL 迁移 Agent 是最容易翻车的场景。配置过去了，但 Skills 和文件留在原工作区——新环境里的 Agent 看起来一样，能力残缺。迁移清单里把 Skills 与 Files 单列，逐项搬运。

Step 7：知道运行上限，把任务切对大小

7 三条硬上限

单次运行时长    1 小时（Web 应用、Service API、工作流同此限）
                超时后未完成的回复直接丢弃
单次模型请求数  500 次/运行（重推理 + 高频工具会很快用完）
回复附件大小    单文件 50 MB，超出不送达

对应策略：
  长任务 → 拆成多轮，或改走工作流分步执行
  重任务 → 减少不必要的工具往返，合并推理步骤
  大文件 → 压缩或拆分后再让 Agent 回传

社区版的安全边界要说清楚。官方安全公告明确：社区版用文件访问控制限制同一 Agent 暴露给多个终端用户时的跨会话数据访问，能降低风险，但 Agent 运行时不是为互不信任的用户或负载设计的强隔离边界。需要强隔离或严格合规的场景，用单独加固的基础设施，或评估 Cloud/Enterprise 方案。

常见问题速查

你遇到的现象	大概率原因 & 解决
Agent 报错或从不调用工具	模型缺原生工具调用（vLLM 等兼容端点常见）。换支持的模型
Discard 后配置和文件都没了	Discard 是全量回滚。分步落地请每次 Apply
Build 里装的工具发布后不见了	检查是否被标成 Temporary；Build 产出默认 Persistent
改 build_note 不生效	外面另存的副本只是普通文件。回 Build 模式让 Agent 改正式笔记
回滚后行为反常	版本回滚连持久文件一起还原了，检查沙箱文件是否符合预期
任务跑到一半被掐断	触碰 1 小时时长或 500 次模型请求上限。拆小任务重试

← 返回教程中心