Dify 1.16.1 Agent 完全使用指南：全新沙箱架构、Skills 与 MCP 工具调用

2026 年 7 月，Dify 连续发布了 1.16.0 和 1.16.1 两个版本，带来了自项目诞生以来最大的一次 Agent 架构重构。全新的沙箱式 Agent、Skills 系统、AI 辅助构建模式——如果你还在用旧版 Agent 的思路，这篇文章会帮你完成认知升级。

一、Dify 1.16 系列：Agent 的脱胎换骨

先说结论：1.16.0 引入的全新 Dify Agent（Beta）与旧版 Agent 是两代完全不同的产品。

旧版 Agent 本质上是「LLM + 工具调用」的组合——模型根据提示词决定何时调用哪个工具，工具执行完返回结果，模型再组织回答。这套机制能用，但能力边界很明确：它只能调用你预先配置好的工具，不能运行代码，不能操作文件系统，不能自主安装依赖。

1.16.0 打破了这层天花板。新版 Agent 运行在独立的 Linux 沙箱中，具备完整的 shell 命令执行能力、代码运行能力、文件系统操作能力，甚至可以按需自主安装命令行工具。它不再是「会调工具的聊天机器人」，而更接近「能干活的 AI 员工」。

1.16.1 作为补丁版本，在这个基础上修复了一系列 Agent 相关的 bug，并增加了几个实用功能。

新旧 Agent 架构对比

二、部署前置条件

新版 Agent 引入了两个全新的 Docker 服务，这是与旧版最大的部署差异：

• agent_backend：Agent 后端核心服务，负责 Agent 的调度和执行
• local_sandbox：本地 Linux 沙箱环境，Agent 的实际运行场所

如果你使用标准的 Docker Compose 部署，升级到 1.16.1 后这两个服务会自动启动。但有几个安全相关的环境变量必须在生产环境中修改：

# DIFY_AGENT_SERVER_SECRET_KEY - JWE 加密密钥，默认值不安全
# DIFY_AGENT_API_TOKEN - API 与 agent_backend 之间的认证令牌
# AGENT_BACKEND_API_TOKEN - agent_backend 侧的认证令牌（需与上面一致）

# 生成安全密钥
python -c 'import secrets; print(secrets.token_urlsafe(32))'

⚠️ 安全警告：Dify Agent 服务应仅提供给受信任的非恶意用户。Agent 运行在 Linux 沙箱中，具备执行 shell 命令和代码的能力。虽然沙箱有 Landlock 保护，但它不是为对抗性环境设计的。

三、创建 Agent 应用

3.1 从零创建

1. 在 Dify 界面进入 Agents 页面
2. 点击 创建 > 创建空白应用
3. 输入应用名称，可选填角色（如「研究助理」）和描述
4. 点击 创建，进入配置页面

你也可以选择 导入 DSL 文件 来使用他人分享的 Agent 配置。注意：DSL 文件不包含 Skill 和文件，这些需要单独上传。

1.16.1 新功能：Agent 应用现在可以直接从侧边栏菜单导出为 DSL YAML 文件，方便备份和版本控制。

3.2 配置面板概览

新版的配置面板比旧版丰富很多，包含以下核心区域：

• 模型：选择 Agent 使用的对话模型
• 提示词：定义 Agent 的角色和工作方式
• Skill：上传打包好的能力包
• 文件：上传参考文档
• 工具：添加 Dify 工具（插件、OpenAPI、工作流、MCP 服务器）
• 知识检索：连接知识库
• 高级设置：环境变量等

下面逐一详解。

四、配置核心能力

4.1 模型选择

选择 Agent 运行的对话模型。优先选择推理能力强、原生支持工具调用的较新模型，因为 Agent 需要自行判断何时行动、哪个工具合适、如何解读结果。

实践建议：

• 简单任务：GPT-4o-mini、Claude 3.5 Sonnet 等即可
• 复杂任务（需要多轮推理、沙箱操作）：推荐 GPT-4o、Claude 3.5 Sonnet 或更强模型
• 旧模型可能用不好沙箱：常见表现是 Agent 始终不去运行命令或安装工具，即使任务需要也不动手

4.2 提示词

提示词是定义 Agent 角色的核心。建议包含以下几个部分：

# 角色
你是一位专业的数据分析助手，擅长处理 CSV、Excel 等数据文件。

# 工作方法
1. 先理解用户的数据分析需求
2. 检查数据文件的格式和内容
3. 使用 Python 进行数据清洗和分析
4. 生成可视化图表
5. 用简洁的语言解释分析结果

# 工具使用
- 当需要查询外部信息时，使用搜索工具
- 当需要处理数据时，在沙箱中运行 Python 代码
- 当需要查阅文档时，检索知识库

# 输出要求
- 分析结果用表格或图表呈现
- 结论部分不超过 200 字

你可以在提示词中通过输入 / 来引用特定的 Skill、文件、工具或知识源，也可以只添加不引用，让 Agent 自行决定何时使用。

4.3 Skill 系统

Skill 是 1.16.0 全新引入的概念，它是你为 Agent 打包的一套完整流程：把某项专门任务所需的指令、参考材料和脚本捆绑在一起，定义一次即可反复使用。

打个比方：提示词设定的是 Agent 的整体角色（「你是数据分析师」），而 Skill 是它只在特定任务需要时才取用的作业指南（「季度报告生成 SOP」）。就像交给能干员工的一份标准化操作流程。

Skill 包的要求：

• 格式：.zip 或 .skill 文件
• 大小：不超过 50 MB
• 必须包含 SKILL.md 文件

你可以在构建模式中让 Agent 替你创建 Skill，也可以手动打包后上传。

4.4 文件

文件是 Agent 工作时可查阅的参考文档，如规格说明、模板或指南。与 Skill 不同，文件只是供阅读的材料，不是可执行的流程。

文件类型默认大小上限：

• 文档：15 MB
• 图片：10 MB
• 视频：100 MB
• 音频：50 MB

提示：文件适合少量需要 Agent 完整阅读、严格遵循的文档。要让 Agent 在大量资料中检索，应改为连接知识库。

4.5 工具配置

为 Agent 添加工具，让它能在聊天之外采取行动。1.16.x 支持四种工具类型：

1. 插件工具：从 Dify Marketplace 安装的现成工具，如 Google 搜索、GitHub、当前时间等
2. OpenAPI（Swagger）工具：通过导入 OpenAPI 规范来集成任意 API 服务
3. 工作流工具：将任何以「用户输入」节点开头的工作流转为可复用工具
4. MCP 服务器：连接 MCP 服务器，自动导入其提供的所有工具

除了你在这里添加的 Dify 工具，Agent 还能在沙箱内自行安装并运行命令行程序。这类工具不会出现在工具列表中，但一经安装，后续任务可继续使用。

1.16.1 修复：MCP 工具的 output_schema 不再被错误地当作必填项处理，修复了部分 MCP 服务器因可选输出 schema 导致的兼容性问题。

4.6 知识检索

连接知识库后，Agent 可以在工作时搜索大量资料。为每个知识库设置查询方式：

• Agent 决定：Agent 根据对话自行编写搜索查询。适合问题多变的场景。
• 自定义查询：固定一条每次都执行的查询。适合来源固定、查询方式统一的场景。

检索设置中可调整：

• Rerank：重排序模型或权重设置（语义 vs 关键词）
• Top K：重排序后最多保留的结果数量
• Score 阈值：结果入选所需的最低相似度
• 元数据过滤：将搜索限定在特定文档内

五、沙箱环境：Agent 的「手」

新版 Agent 最大的变化是拥有了真正的执行环境。沙箱不是模拟器，而是一个真实的 Linux 容器，Agent 可以在其中：

• 运行 shell 命令（pip install、curl、git 等）
• 执行 Python / Node.js 脚本
• 读写文件
• 安装第三方依赖

沙箱的安全机制包括：

• Landlock 保护：Agent 的 HOME 目录受 Linux Landlock 机制保护，限制文件系统访问范围
• 路径隔离：SHELLCTL_ENABLE_PATH_ISOLATION 默认启用，防止跨用户路径访问
• shellctl（Go 重写）：Agent 的所有 shell 操作都经过 shellctl 中转，支持输出脱敏（DIFY_AGENT_SHELL_REDACT_PATTERNS）
• 网络隔离：1.16.1 将 local_sandbox 从默认网络移至专用的 agent_sandbox_network，并新增 agent_ssrf_proxy（Squid）服务

这意味着你可以构建这样的 Agent：

• 「读取上传的 CSV 文件，用 pandas 做数据清洗，生成 matplotlib 图表，输出分析报告」
• 「克隆一个 GitHub 仓库，分析代码结构，生成项目文档」
• 「安装 ffmpeg，将上传的音频文件转码为 MP3，提取前 30 秒作为预览」

这些在旧版 Agent 中完全不可能实现。

六、构建模式：用对话来构建 Agent

构建模式（Build Mode）是 1.16.0 的杀手级功能。 你不再需要逐项手动配置 Agent，而是可以直接用自然语言描述需求，Agent 会自行配置好 Skill、文件和环境变量。

使用方法

1. 在 Agent 配置页面点击进入构建模式
2. 用自然语言描述你的需求，例如：

帮我构建一个会议纪要 Agent：把原始会议记录整理成结构化纪要，
包含参会人、决议和行动项。输出格式用 Markdown，行动项要标注负责人和截止日期。

1. Agent 会边构建边测试，你可以看到它如何反应
2. 它会自动创建所需的 Skill、安装依赖、配置环境变量
3. 所有更改会列在 Build 草稿 中，你可以点击 应用 保留或 放弃 撤销

构建笔记

工作过程中，Agent 会把配置内容记录在一个 build_note.md 文件中。这份笔记会在首次点击 应用 后出现在 文件 区域，并在每次新对话开始时被 Agent 重新读取。

这意味着 Agent 在多次构建对话之间拥有「记忆」——你在第一次对话中定好的格式和规范，第二次对话时它会自动遵循。

1.16.1 修复：修复了构建草稿在应用时的 UI 闪烁问题，以及重置构建时预览聊天记录被清除的问题。

七、MCP 工具集成

MCP（Model Context Protocol）是 Anthropic 发布的开放标准，可以理解为「AI 的 USB-C」——一个协议连接所有工具。Dify 原生支持作为 MCP 客户端，连接 MCP 服务器后自动导入其所有工具。

连接 MCP 服务器

1. 在 Dify 顶部导航点击 工具
2. 点击 MCP > 添加 MCP 服务（HTTP）
3. 填写配置：
   • 服务端 URL：MCP 服务器的 HTTP 端点
   • 名称和图标：便于识别
   • 服务器标识符：唯一标识，导出的应用也会引用此标识符
4. 认证配置：
   • 动态客户端注册（默认开启）：Dify 自动获取 OAuth 凭证
   • 如服务器不支持，关闭后手动填写 Client ID 和 Client Secret
5. 高级选项：
   • 自定义 Headers：支持静态值或动态值（{{request.headers.X-Custom-Auth}}）
   • 超时设置：请求超时和 SSE 读取超时

常用 MCP 服务器

在 Agent 中使用 MCP 工具

MCP 服务器添加后，在 Agent 配置页面的 工具 区域点击 添加，选择 MCP 服务，点击 添加全部 即可。Agent 会根据对话内容自主决定何时调用哪些工具。

自托管提示：如果 Dify 和 MCP 服务器运行在同一主机上，请使用服务器内部 IP 而非 localhost（因为 Dify 运行在 Docker 中）。例如 http://172.17.0.1:3000/mcp 或 http://host.docker.internal:3000/mcp。

八、工作流中的 Agent 节点

新版 Agent 节点与经典节点「模型加工具」的组合完全不同——它请来的是一名自带能力和沙箱的完整 Agent。

使用方式

在工作流中添加 Agent 节点后，有两种选择：

1. 邀请已有 Agent：选择已发布的 Agent，它会带着已保存的能力就位。你在 Agents 页面发布更新后，所有用到该 Agent 的工作流都会同步更新。

   • 要编辑能力：点击 在 Agent Console 中编辑
   • 要创建一次性副本：点击 创建副本，节点切换为独立副本，不再跟随原 Agent 更新

2. 从空白创建：创建一个只属于此节点的一次性 Agent，直接在这里配置。如果好用，可转入 Agents 页面复用。

派任务

在 Agent 任务 中描述这一步需要什么，就像向同事交代一件事：

阅读 {{customer_email}} 中的客户邮件，起草一封回复，
逐一回应邮件中的问题，不超过 150 字。

声明输出

Agent 节点默认返回 text、files 和 json。你可以在任务文本中声明独立输出，供下游节点引用：

对比 {{vendor_quotes}} 中的三份供应商报价并给出推荐。
把胜出供应商的名称放入 {{vendor_name}}，其报价 PDF 放入 {{quote_file}}。

1.16.1 修复：未发布的 Agent 不再允许被放入工作流中使用，防止意外引用未就绪的配置。

九、1.16.1 版本专属更新

除了上述架构层面的变化，1.16.1 作为补丁版本带来了以下值得关注的改进：

新功能

• 工具多选输入：工作流工具节点支持多选下拉输入，可从预定义列表中选择多个值
• 工作流节点定位器：在运行日志或错误消息中点击 node_id，可直接定位并高亮画布上对应的节点
• 工作流块选择器改进：更好的键盘导航、分类预览和搜索体验
• Agent DSL 导出：从侧边栏直接导出 Agent 为 DSL YAML
• 知识追踪：为 RAG 文档处理操作添加了可观测性追踪

Agent 修复

• 预览对话不再继承旧的对话 ID
• 对话历史更新时不再覆盖聊天输入
• Agent 日志中完整保留模型使用定价
• Agent 执行日志中显示工作流节点运行
• Agent 监控统计中包含工作流运行
• 阻止未发布的 Agent 被用于工作流
• 防止预览操作被裁剪
• 修复构建草稿应用时的 UI 闪烁

安全增强

• API 与 agent_backend 之间使用 DIFY_AGENT_API_TOKEN 进行令牌认证
• Jinja2 模板渲染切换至 SandboxedEnvironment，防止模板注入攻击
• 修复 React Server Components DoS 漏洞
• 邮箱验证使用 re.fullmatch 拒绝尾部换行
• 验证账户状态后才接受工作空间邀请

十、调试与发布

调试

在配置页面的右侧 调试与预览 面板中，可以直接与 Agent 对话测试。1.16.1 修复了预览对话继承旧 ID 的问题，每次预览都是干净的新会话。

在 日志 中查看 Agent 的完整对话记录，在 监控 中查看用量、质量、速度和成本。1.16.1 新增了工作流节点运行在 Agent 执行日志中的显示，以及工作流运行在 Agent 监控统计中的包含。

发布

编辑内容会自动保存为草稿。Agent 就绪后，点击 发布 即可让该版本上线。可随时打开版本历史回看或恢复早期版本。

注意：恢复版本只会回滚 Agent 的配置。沙箱环境没有版本记录——安装的工具等环境更改会保持原样。

在 访问点 标签页中，可将 Agent 托管为 Web 应用、嵌入网站，或通过服务 API 调用。Agent 的 API 仅支持流式返回。

十一、安全配置最佳实践

1. 修改默认密钥：DIFY_AGENT_SERVER_SECRET_KEY 和 DIFY_AGENT_API_TOKEN 的默认值仅适用于开发环境，生产环境必须替换

2. 网络隔离：1.16.1 已将沙箱移至专用网络，但建议进一步限制沙箱的出站网络访问

3. 用户信任：Agent 服务仅提供给受信任的非恶意用户。如果面向多个终端用户，Dify 会通过文件访问控制降低跨会话数据访问风险，但不是强隔离方案

4. 环境变量保护：将敏感信息（API 密钥等）放在环境变量中并标记为 Secret，不要写进提示词

5. Shell 输出脱敏：配置 DIFY_AGENT_SHELL_REDACT_PATTERNS 对 shell 输出中的敏感信息进行脱敏

十二、实战案例：构建文档分析 Agent

让我们用一个完整案例串联以上内容。

目标：构建一个能读取上传文档、提取关键信息、生成分析报告的 Agent。

步骤 1：创建 Agent

在 Agents 页面创建空白应用，命名为「文档分析助手」。

步骤 2：配置模型

选择 GPT-4o 或 Claude 3.5 Sonnet——需要较强的推理和代码执行能力。

步骤 3：编写提示词

你是一位专业的文档分析助手。

工作流程：
1. 接收用户上传的文档（PDF、Word、CSV 等）
2. 在沙箱中安装必要的解析工具（如 pdfplumber、python-docx）
3. 提取文档内容，分析结构和关键信息
4. 生成结构化的分析报告

输出格式：
- 文档概要（200 字以内）
- 关键信息提取（表格形式）
- 数据洞察（3-5 条要点）
- 建议和下一步行动

步骤 4：使用构建模式（可选）

进入构建模式，输入：

我需要一个能分析 PDF 和 Excel 文件的 Agent。
请安装 pdfplumber 和 openpyxl，创建一个分析 Skill，
包含数据提取、统计分析和报告生成的完整流程。

Agent 会自动安装依赖、创建 Skill 文件，你只需确认应用即可。

步骤 5：添加 MCP 工具（可选）

如果需要联网搜索补充信息，连接 Brave Search MCP 服务器：

服务端 URL: https://mcp.brave-search.example.com/sse
服务器标识符: brave-search

然后在工具区域添加该 MCP 服务。

步骤 6：测试

在调试面板上传一份 PDF 文档，输入「分析这份文档的关键信息」，观察 Agent 的执行过程：

1. Agent 检测文件类型
2. 在沙箱中安装 pdfplumber
3. 运行 Python 脚本提取内容
4. 分析并生成报告

步骤 7：发布

确认效果后点击发布，获得 Web 应用链接或 API 端点。

十三、升级指南

从旧版本升级到 1.16.1：

# Docker Compose 部署
cd docker
docker compose down
git pull origin main
docker compose pull
docker compose up -d

# 数据库迁移会自动执行
# 检查日志确认无误
docker compose logs -f

关键检查项：

1. DIFY_AGENT_API_TOKEN：新引入的必需变量，默认值不安全，生产环境必须替换
2. OpenAI API 类型：如果使用自定义 OpenAI API key，检查 API 类型设置，从 Chat Completions 切换到 Responses（GPT-5.6 兼容性要求）
3. 数据库迁移：1.16.1 包含 4 个新的数据库迁移，均为累加式（新表、列、索引），可零停机执行
4. Docker Compose 变更：新增 agent_backend 和 local_sandbox 服务，api 和 worker 现在依赖 agent_backend

写在最后

Dify 1.16.1 标志着这个平台从「LLM 应用编排器」向「AI Agent 操作系统」的转型。沙箱式 Agent 赋予了 AI 真正的「双手」——它不再只是回答问题，而是能执行任务、操作文件、运行代码。Skills 系统让能力可以被标准化打包和复用，构建模式则大幅降低了配置门槛。

如果你还在用旧版 Agent，强烈建议升级体验。虽然新版 Agent 仍处于 Beta 阶段，但它代表的方向是 AI 应用发展的必然趋势——从「对话」到「行动」。

本文基于 Dify v1.16.1 官方文档和发布说明撰写。Dify 是开源项目，仓库地址：https://github.com/langgenius/dify

引用链接

[1] https://github.com/langgenius/dify