Dify 插件开发实验03工具接入工作流与Agent——插件工具如何在工作流和 Agent 中使用Dify 实验系列 · 插件开发 03/12 | 实验编号DIFY-106-03基于 Dify 1.16.1 实测2026-081. 业务场景先讲一个我们实际遇到的场景。客服工单 SaaS 有两个入口在用之前做好的工具一边是工单流程——用户提交工单时系统要自动记下建单时间戳、并校验这张工单在订单系统里的状态这是固定动作不能乱另一边是门户对话——用户在网页上直接问「现在几点」「我的工单 WO-20260805 到哪一步了」模型要自己判断该不该调工具、调哪个工具。同一个插件两种用法一个要「确定性地执行」一个要「智能地选择」。工具造出来只是第一步怎么接进业务应用才是插件真正产生价值的地方。我们第一次做这种接入时第一反应也是「工具节点拖进工作流不就行了」。真正动手才发现——「能被工作流调用」和「能被 Agent 智能调用」是两套完全不同的消费逻辑工作流要确定性参数绑死上游变量Agent 要自主性参数靠模型按描述生成——同一个插件要同时伺候好这两种形态工具描述和调用形态都得重新设计。这不是个例。任何「一个工具既要在固定流程里跑、又要能被对话智能调用」的场景都是这个模式电商的物流查询、银行的账户查询、SaaS 的工单查询——确定性编排和模型自主调用是插件消费的两种基本形态。2. 场景痛点这个流程的痛点在接入业务时体现得最直接同一能力要接两套形态工单流程要固定调用门户对话要智能调用——不会接工具就只能躺在插件列表里吃灰。模型乱调工具不加约束时用户闲聊「你好」模型也可能去调一次时间工具白白浪费 token还显得很傻。参数瞎编工具描述写得含糊模型就生成非法参数比如把工单号编成abc123调用必然失败。出错就中断工具调用失败如果直接抛错整个工作流就断了——下游业务无感知、无降级。本质上「怎么被消费」决定工具的价值——工作流要的是确定性Agent 要的是可引导的自主性两者都需要把工具描述和调用形态设计好。3. 方案为什么是双形态接入选双形态接入我们实际对比过workflow 工具节点 确定性编排参数显式绑定上游变量固定调用适合「必须执行」的步骤建单打时间戳Agent function calling 模型自主选择模型按 query 意图决定调不调、调哪个适合开放对话门户问答同一插件实例两种形态共用插件装一次工作流和 Agent 都能挂插件日志统一出口排障只看一处。这篇文章我们就用它把 01/02 的工具get_current_timeget_order_status分别接进工单流程workflow和门户对话agent并对比两种形态的差异、掌握插件运行日志的定位方法。4. 整体架构agent 验证对话dify106_03_验证对话工具列表 get_current_time get_order_statusfunction_call 策略workflow 验证应用dify106_03_验证应用开始order_id issue_textget_current_time建单时间戳get_order_status状态校验输出汇总结束工具插件106-01/02 成果time_tool order_toolworkflow 形态工具节点参数显式绑定上游变量两者共用同一插件实例插件日志统一出口agent 形态工具列表模型按需选择参数由模型生成链路很清晰同一插件 → 双形态挂载 → 各自消费。workflow 走工具节点、参数绑定上游变量agent 走工具列表、参数由模型按描述生成——两种形态的关键差异就在「参数从哪来、怎么校验」。5. 模块设计5.1 workflow 工具节点 DSL实测格式-id:time_tooldata:type:tooltitle:获取当前时间provider_type:builtinprovider_id:dify106/dify106_01_time_tool/time_tooltool_name:get_current_timetool_configurations:{}# 必填字段无凭证配置也保留空对象tool_parameters:timezone:type:constantvalue:UTC8第二个工具节点order_tool的 order_id 参数用type: mixedvalue: {{#start.order_id#}}绑定上游变量。多工具串行时各节点独立配tool_configurations: {}。5.2 agent 工具挂载agent-chat DSLagent_mode:enabled:truestrategy:function_callmax_iteration:5tools:-enabled:trueprovider_id:dify106/dify106_01_time_tool/time_toolprovider_type:builtintool_name:get_current_timetool_parameters:timezone:5.3 工具描述撰写规范决定 agent 调用成功率llm description 给参数规则 示例order_id must match format WO- followed by 8 digits, e.g. WO-20260805——实测模型据此正确生成工单号。pre_prompt 里写工具边界「时间类问题只调时间工具工单类问题只调工单工具不要混用」「闲聊不调用工具」——实测负例不触发。格式错误时模型行为可控pre_prompt 写「工单号格式不对时先请用户核对」→ 实测 abc123 不调工具直接提示格式合理行为。可选参数给合法取值集合模型会自主选择时区问时间 → timezoneUTC8。5.4 双形态对照表核心交付物维度workflow 形态agent 形态参数来源显式绑定上游变量tool_parameters mixed 模板模型自主生成tool_input JSON按工具描述规则校验时机工具内校验param_invalid 直接返回模型先按描述规则判断格式不对时不调工具错误处理工具返回结构化 error → 下游节点处理工具返回 error → 模型解读并转述给用户调试方式node-executions 看工具节点输入/输出SSE 事件 agent_thought 的 tool/tool_input 字段工具选择固定调用编排决定模型按 query 意图选择描述质量决定成功率6. 运行验证输入预期结果workfloworder_idWO-20260805时间戳 工单状态均正确输出通过实测 17:08:53 UTC8 processingworkflow 错误路径bad-idparam_invalid 输出流程不中断通过agent 问「现在几点」触发 get_current_time回答精确时间通过timezoneUTC8 模型自选agent 问工单状态触发 get_order_status回答真实数据通过模型正确生成 order_idagent 闲聊「你好」不触发任何工具通过排障演练base_url 改不可达upstream_error 结构化返回不中断daemon 日志可见 dispatch/tool/invoke 链路通过7. 实战坑坑现象修复工具描述差导致 agent 乱调/不调描述不含参数规则 → 模型生成非法参数描述含规则示例WO- 8 位数字→ 模型正确生成实测agent_thought 事件结构按 tool_calls 字段解析不到工具调用工具调用在 tool/tool_input 字段不是 tool_calls每个工具调用出现 2 条 agent_thought实测workflow 未发布直接跑400 “Workflow not published”验证脚本必须含 publish 步骤实测日志层级分不清排障找不到插件调用证据daemon 日志 dispatch/tool/invoke 是插件调用链路证据故障信息在工具结构化 error 里实测agent 格式错误不调工具提问 abc123 模型不调工具直接提示格式合理行为pre_prompt 规则生效非缺陷实测8. 实验文档及源码获取实验文档完整操作步骤DIFY-106-03工具接入工作流与Agent.md源码可直接导入dify106_03_验证应用.ymlworkflow、dify106_03_验证对话.ymlagent全部源码目录dify-106/dsl文章聚焦核心配置与采坑点实验的完整分步操作节点搭建/参数表/调试指引见实验文档原文。下一篇Dify 插件开发实验04企业系统对接工具——如何用插件对接企业 ERP/CRM 你在这个实验的场景里踩过什么坑欢迎评论区分享你的实战经验。