# 创建与复用工作流工具

> 将可视化工作流封装为带标准输入输出契约的工具，供对话 Agent、Agent V2 与其他工作流调用。

Source: https://doc.fastgpt.cn/zh-CN/guide/build/tools/workflow-tools

工作流工具（Workflow Tool）允许你将一段包含 HTTP 请求、知识库检索、代码处理或模型推理的画布流程，封装成具有严格输入参数和输出字段的可调用工具，在团队内跨应用共享复用。

## 适用场景与前提条件

* **适用场景**：将多步骤业务查询（如先查工单接口、再经代码清洗、最后汇总结果）封装为原子工具，挂载给对话 Agent V2 或工作流[工具调用节点](/zh-CN/guide/build/workflow/nodes/tool)。
* **权限要求**：拥有当前团队的工具创建与发布权限；调用方应用需拥有该工作流工具的读取或使用权限。

![工作流工具自定义输入与参数配置](/imgs/optimized/current/tool-variables.png.webp)

## 第一步：创建工作流工具并声明输入契约

1. 进入 **工作台 → 我的工具**，点击列表首个 **新建** 卡片，选择 **工作流工具**（右上角工具栏提供 **批量管理**、**+ 文件夹** 与 **导入** 入口）。
2. 画布默认包含 **插件开始（`pluginInput`）** 和 **插件输出（`pluginOutput`）** 两个核心契约节点，节点内分别为 **自定义输入**、**自定义输出** 分区。
3. 在 **插件开始** 节点的 **自定义输入** 分区点击 **新增**，按调用方式声明输入参数：

| 配置项             | 说明                                                                     |
| --------------- | ---------------------------------------------------------------------- |
| **字段名（Key）**    | 英文或字母数字标识（如 `orderId`、`queryDate`），作为函数调用的 JSON 属性名                    |
| **字段标签（Label）** | 界面显示的可读名称                                                              |
| **数据类型**        | 支持 `String`、`Number`、`Boolean`、`Object`、强类型数组及 `选择知识库`（允许父应用传入目标知识库范围） |
| **参数描述**        | 明确说明参数含义、格式示例与取值范围；当工具挂载给大模型时，模型依据此描述自动提取并填入参数                         |
| **是否必填**        | 开启后，大模型调用或父工作流静态连线必须提供该参数                                              |

## 第二步：编排内部节点并绑定输出契约

1. 在画布中添加业务处理节点（如 HTTP 请求、知识库搜索、代码运行或 AI 对话），将 **插件开始** 节点右侧的执行连线接入首个处理节点。
2. 在处理节点中通过变量选择器引用**自定义输入**声明的字段。
3. 将最后一个处理节点的执行出口连接到 **插件输出（`pluginOutput`）** 节点。
4. 在 **插件输出** 节点的 **自定义输出** 分区点击 **新增**，声明返回字段名（如 `resultSummary`、`statusCode`），并引用上游处理节点的对应输出。关于输入输出节点的完整参考见 [应用调用与工作流工具节点](/zh-CN/guide/build/workflow/nodes/run_app)。

## 第三步：独立调试与发布版本

1. 点击右上角**运行**打开调试面板，按声明的输入表单填入一组已知测试参数，点击发送。
2. 展开运行详情，检查**自定义输入**是否正确传入、中间节点是否执行成功，以及**自定义输出**是否生成预期的结构化字段。
3. 验证无误后，点击右上角**保存并发布**。调用方应用始终执行该工具的最新**已发布版本**。

## 第四步：在应用中挂载与调用

* **在对话 Agent / Agent V2 中调用**：进入应用的 **工具** 配置区，点击 **+ 选择** 并勾选已发布的工作流工具。若工具包含无需大模型生成、需由管理员预设的固定参数（如固定 API 密钥或目标知识库），在挂载卡片中直接填写。
* **在主工作流中静态调用**：在画布“添加节点 → 工具”中选择该工作流工具，作为普通节点连入主流程，并将上游变量映射到其输入端口。
* **在主工作流工具调用节点中动态调用**：使用底部蓝色菱形连接点，将工作流工具挂载到[工具调用节点](/zh-CN/guide/build/workflow/nodes/tool)下方。

## 调用异常排查

| 现象                   | 排查方式                                               |
| -------------------- | -------------------------------------------------- |
| 模型调用工具时漏传参数或格式错误     | 优化**自定义输入**中的工具描述与字段描述，补充格式示例（如 `YYYY-MM-DD`）      |
| 工具执行成功但 Agent 未拿到返回值 | 检查是否已将内部节点结果连接到 **插件输出（`pluginOutput`）** 并重新发布工具版本 |
| 修改了工具内部逻辑但调用方未生效     | 回到工作流工具编辑器点击**保存并发布**，更新正式版本快照                     |

下一步：对比其他工具形态见 [选择工具与 Skill](/zh-CN/guide/build/tools/overview)，或配置 [HTTP 工具集](/zh-CN/guide/build/tools/http_tools)。