Dify Agent 应用实战：Beta 版「真 Agent」的能力边界实测

📖 摘要：Dify 1.16.1 的「Agent 应用」和 workflow 里的 agent 节点不是一回事——它有独立的推理运行时、独立的沙盒，模型可以自主决定调用工具、执行命令、查知识库。但这功能目前是 Beta：有些能力能用，有些能力（比如 CLI 工具）前后端没对齐，UI 里连入口都没有。本文用 9 项实测验证划出它的真实能力边界：哪些可用、哪些不可用、哪些是坑，以及 Beta 功能对交付意味着什么。

1. 业务场景

给客户做 AI 应用交付时，经常会遇到一类需求：「我要的机器人不是一问一答，是能自己干活的那种。」

比如运维场景：客户问「这台设备的日志有异常，帮我查一下问题在哪」，期望的回复不是一段话，而是机器人自己登录设备、跑几条命令、把结论整理出来。比如知识场景：客户问「这个型号支持哪些特性」，期望机器人自己查手册、核对版本、给出带出处的答案。

这类需求的核心是自主性——模型要能自己决定「下一步做什么」，而不是走完一条固定的流程。以前要实现这种效果，基本只能靠外部框架（Agent 框架 + 沙盒环境）来兜底，Dify 平台本身只做确定性编排。

直到 1.16.1 的 Agent 应用出现。

2. 场景痛点

Dify 里其实一直有两个「Agent」概念，容易混淆：

1. agent 节点：workflow/chatflow 里的一个节点，在流程里执行一步多轮推理。它是流程的一部分，不是独立的 Agent。

2. Agent 应用：独立的应用类型，有自己的配置页（模型/Skill/文件/工具/知识检索/环境变量），运行在独立的推理引擎里，自主循环由平台托管。

问题在于：Agent 应用这个「新物种」，官方文档语焉不详，社区里没人说清楚它的真实边界。它到底是完整的 Agent 平台，还是半成品 Demo？哪些能力能用来交付，哪些是摆设？在 Beta 阶段贸然拿它交付，风险在哪里？

这些问题的答案，只能靠实测。

3. 方案

在云端 Dify 1.16.1 环境，创建了一个实验 Agent 应用（exp_agent_e1），按 9 个验证点逐项实测：创建与落库、配置读写、基础对话、自主工具调用、知识库检索、沙盒执行、CLI 工具、多轮记忆、接口限制。

实测原则两条：源码确认机制，API 实测验证行为；全程用实验应用和构造数据，不碰任何生产环境。

4. 整体架构

Agent 应用是三层独立运行时，不是 workflow 的扩展：主 API 管应用生命周期和请求入口，专门的 Agent 后端跑自主推理循环，独立的 Linux 沙盒容器执行命令。模型、工具、知识库、记忆、环境变量全部打包在一份「Soul 配置」里，发布时生成不可变版本，支持回滚。

5. 模块设计

5.1 创建与配置

# 创建 Agent 应用（自动落 agents + apps 双表，1:1 绑定）

POST /console/api/agent

{ "name": "xxx", "description": "...", "role": "..." }

# 编辑 Soul 配置（checkout 草稿 → 修改 → apply 落共享草稿 → publish 生成版本）

POST /console/api/agent/<id>/build-draft/checkout

PUT  /console/api/agent/<id>/build-draft      # 带 agent_soul + variant + save_strategy

POST /console/api/agent/<id>/build-draft/apply

POST /console/api/agent/<id>/publish          # 生成不可变版本，支持回滚

Soul 配置的结构（对应 UI 各区块）：prompt / tools（Dify 工具 + CLI 工具）/ knowledge（多知识库集合）/ env（环境变量）/ skills / files / sandbox / memory / model / app_variables。

实测确认：配置写入后读回完全一致；发布生成版本 v1→v7 逐版累积；未配置模型时发布被拦截（agent_model_not_configured）。

5.2 对话调用

# 调用（注意：只支持 streaming！）

POST /v1/chat-messages

{ "query": "...", "response_mode": "streaming" }

SSE 事件流里能看到 agent_thought 事件——模型的推理过程（thought 字段）实时流式输出，position 递增表示多步执行。这对调试和用户信任都是加分项：Agent 每一步在想什么，全程可见。

5.3 工具与知识库

工具挂载走 Soul 配置的 tools.dify_tools，内置工具实测可用（time 工具：问「现在几点了」，Agent 自主调用工具并引用结果回答）。知识库挂 knowledge.sets（多库集合，按 set 配检索策略），实测问缺陷分级标准，回答正确引用库内文档内容。

5.4 沙盒执行

最意外也最重要的发现：Agent 不需要配置任何工具，默认就带 shell 能力。实测让它「在工作目录创建文件并读回」，Agent 自主执行命令完成（文件创建成功、内容读回正确），shell 作业日志完整可见（job_id / exit_code）。

Agent 默认工具面（实测中 Agent 自述）：shell 四件套（shell_run / shell_wait / shell_input / shell_interrupt）+ 时间五件套 + dify-agent CLI（config / file）。

6. 运行验证

两个值得记住的数字：

9 项验证，8 项可用，1 项确认不可用——不可用的恰恰是 CLI 工具，而且不是「不会配」，是功能本身没做完：API 层能配置能校验能发布，但 UI 工具添加界面只有「工具插件 / Swagger API / 工作流 / MCP」四类，没有 CLI 入口；运行时也没有授权路径（授权状态字段依赖 UI 流程，UI 没实现）。

一次问答成本 ≈¥0.004（deepseek-v4-flash）——知识库问答实测 3847 prompt tokens + 867 completion tokens。成本不是 Agent 应用的瓶颈，响应体积才是：一次问答的 SSE 流 0.6~1.2MB（思考过程全量流式输出），网络与解析成本要提前设计。

7. 实战坑

8. 总结与适用边界

Agent 应用是 Dify 目前最接近「真正意义的 Agent」的形态：独立推理运行时、默认沙盒执行、工具/知识库/记忆全挂载、推理过程流式可见。9 项实测里 8 项可用，作为「对话式自主助理」它是真实可用的。

但它是 Beta，交付前必须看清边界：

适合什么：对话式自主助理（查资料+整理+执行命令+返回结果）、知识库问答 + 自主分析、运维辅助（让 Agent 在沙盒里跑命令验证结论）。Agent 默认的 shell 能力让它天然适合「读文件、跑命令、给结论」这类活。

不适合什么（现阶段）：需要 CLI 工具定制的场景（功能未完成）、确定性流程编排（那是 workflow 的主场）、blocking 同步调用（只支持 streaming）、对版本稳定性要求极高的生产环境（Beta 功能后续可能变）。

对交付的启示：Beta 能力不写进正式交付标准。客户要「自主 Agent」时，先问清楚是尝鲜还是生产；生产场景优先 workflow + 外部 Agent 框架的组合，Agent 应用可以作为演示和原型验证的加分项。

实验在 Dify 1.16.1 云端环境实测（独立实验应用 + 构造数据）。机制细节与踩坑清单已沉淀进内部技能库，Agent 应用后续版本的能力变化会持续跟踪。

本文基于真实实验交付经验撰写（Dify 1.16.1 环境，云端实测）。文中数据均来自我们自己的实测记录，理论与推断部分以「实测/待验证」标注边界。