Dify 节点设计手册发布于 2026-09-01

外部交互族：HTTP / 工具 / Agent 节点 / 外部数据源——与外部世界打交道的四种方式

基于 Dify 1.16.1 与 Hermes Agent 实战实测（2026-08/09）：E1 Agent 节点实验 + E8-B 外部数据源实验 + 工具发布链路 + 多源抓取实测

📖 摘要：与外部世界打交道有四种方式：HTTP 请求（一次调用）、工具（插件/子工作流能力）、Agent 节点（自主选择工具）、外部数据源（数据作为变量）。本文给四种方式的选型 + 契约 + 实测坑：Agent 节点 vs LLM 的实测成本对比（3.2s vs 1.5s、prompt 18 倍开销）、Agent 节点的 model-selector 结构坑与 tools 必填、工具缓存旧配置必须删旧重建、HTTP fail 分支必配、外部数据源没装插件时静默不赋值。

📌 本文要解决的核心痛点

调外部 API、调工具、让 Agent 自主干活、接外部数据——四种方式怎么选？

Agent 节点和 LLM 节点有什么区别？直接当 LLM 用行不行？

子工作流改了配置，为什么工具调用还是旧逻辑？

外部数据源配了变量，运行时为什么原样输出占位符？

本文给四种方式的选型表 + 实测成本数据 + 高频坑。

一、四种方式是干什么的（先选型）

方式	干什么	什么时候用	什么时候不用
HTTP 请求	调用外部 API（一次请求）	取数/回调/通知，请求路径确定	需要多轮协商/试错（那是 Agent 的活）
工具	调用插件能力或子工作流发布的工具	复用已验证的能力（拼装式交付）	能力简单到直接 HTTP/code 就行
Agent 节点	自主选择工具完成多步任务	任务路径不确定、需要试错/多步推理	任务路径确定（成本是 LLM 的 18 倍）
外部数据源	把外部数据（Notion/爬虫/API）作为变量	数据在外部系统（文档/网页/第三方）	数据已有（直接上传/导入知识库）

选型口诀：路径确定 → HTTP/工具；路径不确定要试错 → Agent；数据在外部 → 数据源。

二、设计模式

HTTP 请求（六要素）

要素	说明
method/url/headers/body	四件套基础
超时	外部调用必须设超时
fail 分支	必须补 fail 边（失败走降级/重试）——漏了外部失败直接阻断主流程
安全	SSRF/网络白名单（沙箱外调用要过白名单）

工具（发布链路）

环节	要点
发布	子工作流 publish → 发布为工具（Workflow as Tool）
⚠️ 缓存	改子工作流配置（LLM/code 逻辑）后，旧工具仍跑旧配置——必须删旧重建
⚠️ 连锁	删旧重建后 provider_id 变化，调用方 tool 节点必须同步更新
契约	工具输出四字段 text/files/json/error_code——错误契约按 error_code 路由

Agent 节点（E1 实测）

配置	要点
最小字段	type: agent + agent_strategy_provider_name（langgenius/agent/agent）+ agent_strategy_name（function_calling）+ tool_node_version + agent_parameters
⚠️ model 结构	必须 `{type: model-selector, model: ...}` 结构（字段名是 model 不是 name）——写错报「Model Field validation failed required」
⚠️ tools 必填	空数组报错「tool parameter tools not found」——必须挂至少一个真实工具
输出	text（回答）+ usage（token）+ files + json

外部数据源（E8-B 实测）

配置	要点
变量	start 变量 type: `external_data_tool`
结构	app 层 external_data_tools（旧式）或 user_input_form（新式）都合法
⚠️ 静默空值	没装数据源插件时，变量不赋值、引用它的模板原样输出（不报错）——必须做兜底
依赖	数据源插件（firecrawl/watercrawl/notion）——第三方 key/OAuth

三、实测踩坑（五个高频坑）

坑 1：Agent 节点当 LLM 用——18 倍 prompt 开销

现象：用 Agent 节点做确定性问答，慢且贵。

实测（E1）：同任务同输入——Agent 3.2s vs LLM 1.5s（约 2 倍耗时）；prompt tokens 665 vs 37（Agent 注入工具 schema + 策略指令，约 18 倍 prompt 开销）。

结论：确定性任务（固定输出/无自主工具选择）用 LLM 节点；真需要「多轮自主工具选择」才用 Agent 节点。Agent 节点的价值在自主性，不在生成质量。

坑 2：Agent model 参数结构错

现象：按 LLM 的扁平格式（provider/name）写 Agent 的 model，运行报 Model Field validation failed 'required'。

根因：Agent 节点的 model 参数是 model-selector 结构（{type: model-selector, model: ...}），与 LLM 节点的扁平结构不同（E1 实测）。

坑 3：工具缓存旧配置

现象：子工作流改了 LLM 配置 + publish，工具调用仍跑旧逻辑。

实测：2026-08-22 v21——关 thinking + publish 后工具仍按旧配置跑。必须删旧重建 + 调用方 provider_id 同步更新。

坑 4：HTTP 漏 fail 分支

现象：审计日志类 HTTP 失败直接阻断主流程（审计失败整个应用挂）。

根治：审计日志类 http 必须补 fail 边（失败不阻断主流程）。

坑 5：外部数据源静默空值

现象：external_data_tool 变量没配数据源插件，运行时引用它的模板原样输出 {{#变量#}}，不报错。

根治：生成 DSL 时给外部数据变量做兜底（判空/默认值）——静默空值比报错危险（E8-B 实测）。

四、节点级验证清单

验证点	怎么验	取证
Agent 成本	usage 查 prompt tokens（对比 LLM）	node-executions usage
Agent 工具调用	多次采样确认工具真实调用（非编造）	json 字段工具调用记录
工具配置生效	改子工作流后验证新配置生效	工具输出断言
外部调用失败	断网/错误 URL 触发 fail 分支	fail 路径用例
数据源兜底	无插件时运行确认不裸奔	输出检查

五、案例：多源串行 HTTP 抓取（双源合并）

环节	做法
取数	串行 HTTP：qc → http_a → http_b（不并行——保证顺序）
清洗	code 双 body 合并（XML 非法字符过滤 + 无信息描述过滤）
确定性	RSS 标题+描述 code 直出（LLM 零参与信息链路）
合并	交错取源（各取前 5 zip）保证双源都出现
来源标注	每行拼来源名

核心结论：外部交互四种方式的边界清楚后，90% 的坑都在「选错方式」（Agent 当 LLM）和「忘了兜底」（fail 边/静默空值）——选型 + 兜底是外部交互族的设计主线。

下一篇预告：《流程编排族：迭代 + 循环 + 定时触发 + 子工作流 + 人工输入》——复杂流程组织五件套。Iteration vs Loop 怎么选、循环的静默不执行坑、定时触发的三个坑、人工审批的恢复竞态。

这些 AI 应用能力，如何交付到真实业务场景？看看方案与服务 →

本系列 · Dify 节点设计手册