Data-governance 工作流添加 Tools 指南

目标: 为 Data-governance 工作流添加检查和创建元数据的工具
日期: 2025-11-04

✅ 已完成的准备工作

1. 后端 API 接口已创建

检查元数据接口

GET http://192.168.3.143:5000/api/meta/check?name_zh=元数据中文名

Response:
{
  "code": 200,
  "data": {
    "exists": true/false,
    "name_zh": "元数据中文名"
  },
  "msg": "查询成功"
}

创建元数据接口

POST http://192.168.3.143:5000/api/meta/node/add
Content-Type: application/json

{
  "name_zh": "元数据中文名",
  "data_type": "string",
  "describe": "描述信息",
  "source": "data-governance-workflow",
  "status": true
}

Response:
{
  "code": 200,
  "data": { ... },
  "msg": "success"
}

2. AI Agent 系统消息已更新

AI Agent 现在已配置为：

引导用户提供元数据信息
使用 check_metadata 工具检查
使用 create_metadata 工具创建

🛠️ 在 n8n 界面中添加 Tools

步骤 1: 登录 n8n

访问: https://n8n.citupro.com
登录账号

步骤 2: 打开 Data-governance 工作流

1. 进入 Workflows 页面
2. 找到 "Data-governance" 工作流
3. 点击打开编辑器

步骤 3: 添加检查元数据工具

3.1 添加节点

1. 点击 "+" 添加节点
2. 搜索 "HTTP Request Tool"
3. 选择 "HTTP Request Tool" (LangChain类别)

3.2 配置节点参数

基本配置:

Name: check_metadata

Description:

检查元数据中文名是否已经存在。需要参数：name_zh（元数据中文名）。返回exists字段表示是否存在（true/false）

HTTP Request 配置:

Method: GET
URL: http://192.168.3.143:5000/api/meta/check?name_zh={{ $parameter.name_zh }}
Authentication: None

Placeholder Definitions (参数定义): 点击 "Add Placeholder" 添加：

Name: name_zh
Description: 元数据中文名

3.3 连接到 AI Agent

1. 将 "HTTP Request Tool" 节点拖动到 AI Agent 旁边
2. 从 "HTTP Request Tool" 的输出点拖线到 "AI Agent"
3. 在弹出的连接类型选择中，选择 "ai_tool" 连接类型

步骤 4: 添加创建元数据工具

4.1 添加节点

1. 再次点击 "+" 添加节点
2. 搜索 "HTTP Request Tool"
3. 选择 "HTTP Request Tool" (LangChain类别)

4.2 配置节点参数

基本配置:

Name: create_metadata

Description:

创建新的元数据。需要参数：name_zh（中文名，必填）, data_type（数据类型，默认string）, description（描述信息，选填）。返回创建结果

HTTP Request 配置:

Method: POST
URL: http://192.168.3.143:5000/api/meta/node/add
Authentication: None
Send Body: ✅ 启用
Body Content Type: JSON
JSON Body:
```
{
"name_zh": "={{ $parameter.name_zh }}",
"data_type": "={{ $parameter.data_type || 'string' }}",
"describe": "={{ $parameter.description || '' }}",
"source": "data-governance-workflow",
"status": true
}
```
Placeholder Definitions (参数定义): 点击 "Add Placeholder" 三次添加：
1. Name: name_zh, Description: 元数据中文名（必填）
2. Name: data_type, Description: 数据类型（string/int/float等，默认string）
3. Name: description, Description: 描述信息（选填）
4.3 连接到 AI Agent

```

从 "HTTP Request Tool" 的输出点拖线到 "AI Agent"

选择 "ai_tool" 连接类型


### 步骤 5: 清理旧节点（可选）

如果工作流中还有这些节点，可以删除它们（它们已经不需要了）：
- "判断用户意图" (IF节点)
- "调用元数据新增API" (HTTP Request节点)
- "设置确认消息" (Set节点)
- "设置拒绝消息" (Set节点)

**注意**: 只保留以下核心节点：
- Chat Trigger
- AI Agent
- DeepSeek Chat Model
- check_metadata (HTTP Request Tool)
- create_metadata (HTTP Request Tool)

### 步骤 6: 保存并激活

点击右上角 "Save" 保存工作流

如果工作流未激活，点击 "Active" 开关激活


---

## 🧪 测试工作流

### 测试场景 1: 完整流程

访问: https://n8n.citupro.com/chat/tWfjLZE1FmMfQAIn

用户: "是，我要创建元数据" 预期: AI 询问元数据信息

用户: "中文名：测试字段001，类型：string，描述：这是一个测试字段" 预期:

AI 使用 check_metadata 检查是否存在
如果不存在，使用 create_metadata 创建

返回成功消息


### 测试场景 2: 元数据已存在

用户: "是，我要创建元数据" AI: "好的！请提供元数据信息..."

用户: "中文名：测试字段001，类型：string" 预期: AI 提示该元数据已存在


### 测试场景 3: 信息不完整

用户: "是，我要创建元数据" AI: "好的！请提供元数据信息..."

用户: "类型是string" 预期: AI 提示需要提供中文名


---

## 📊 工作流最终结构

┌────────────────┐ │ Chat Trigger │ └───────┬────────┘

    │
    ↓

┌────────────────┐ ┌─────────────────────┐ │ AI Agent │◄─────│ DeepSeek Chat Model │ └───────┬────────┘ └─────────────────────┘

    │
    │ (ai_tool连接)
    ├──────────────────────┐
    │                      │
    ↓                      ↓

┌────────────────┐ ┌─────────────────┐ │ check_metadata │ │ create_metadata │ │ (HTTP Tool) │ │ (HTTP Tool) │ └────────────────┘ └─────────────────┘


**关键连接**:
- `Chat Trigger` → `AI Agent` (main 连接)
- `DeepSeek Chat Model` → `AI Agent` (ai_languageModel 连接)
- `check_metadata` → `AI Agent` (ai_tool 连接)
- `create_metadata` → `AI Agent` (ai_tool 连接)

---

## ⚠️ 重要注意事项

### 1. 连接类型

**ai_tool 连接** 是特殊的连接类型：
- 不是普通的 main 连接
- 表示该节点是 AI Agent 可以使用的工具
- AI Agent 会根据用户输入自动决定何时调用哪个工具

### 2. Tool Description 很重要

Tool 的 Description 会告诉 AI：
- 这个工具的功能是什么
- 需要什么参数
- 返回什么结果

**AI 根据 Description 来决定是否调用该工具**。

### 3. 参数传递

Tool 的参数 (placeholders) 由 AI Agent 从对话中提取：
- 用户说："中文名是用户姓名"
- AI 提取: `name_zh = "用户姓名"`
- 调用: `check_metadata(name_zh="用户姓名")`

### 4. JSON Body 中的表达式

使用 n8n 表达式语法：
- `={{ $parameter.name_zh }}` - 获取参数值
- `={{ $parameter.data_type || 'string' }}` - 默认值
- 需要用双花括号 `={{ }}`

---

## 🔧 调试技巧

### 查看工具调用日志

在 n8n 界面打开 "Executions"
找到最近的执行记录
展开查看每个节点的输入输出
检查 Tool 是否被正确调用
```
### 测试单个工具
```
在编辑器中点击 Tool 节点
点击 "Test node"
手动输入参数值

查看返回结果 ```

常见问题

问题	原因	解决
AI 不调用工具	Description 不清晰	优化 Description，明确说明功能和参数
工具调用失败	API 不可达	检查 192.168.3.143 的网络连接
参数未传递	Placeholder 未定义	检查 Placeholder Definitions
返回格式错误	API 返回不符合预期	检查后端 API 返回格式

✅ 完成验收

工作流配置完成后，应该满足：

两个 HTTP Request Tool 节点已添加
工具通过 ai_tool 连接到 AI Agent
check_metadata 工具配置正确
create_metadata 工具配置正确
AI Agent 系统消息已更新
工作流已保存并激活
测试场景 1 通过
测试场景 2 通过
测试场景 3 通过

📚 相关资源

n8n 官方文档

项目文档

🎯 下一步

立即执行: 按照本指南在 n8n 界面中添加 Tools
测试验证: 使用测试场景验证功能
优化提示词: 根据测试结果优化 AI 系统消息
监控运行: 观察工作流执行日志，持续优化

预计配置时间: 15-20 分钟
难度: ⭐⭐⭐ (中等)

祝您配置顺利！🚀

n8n_add_tools_guide.md 9.0 KB Історія Запис