# 外部数据工具 - 快速接入指南

> **版本**: 2026-01-29 v2.0  
> **基础路径**: `/api/user/external-tools`  
> **认证方式**: Bearer Token（在请求头添加 `Authorization: Bearer <JWT Token>`）
> **设计原则**: 只需 3 步，连接您的 API

---

## 🚀 快速开始

### 创建工具只需提供 4 个信息：

| 信息 | 说明 | 示例 |
|------|------|------|
| **名称** | 给工具起个名字 | `"天气查询"` |
| **API 地址** | 您的 API URL | `"https://api.weather.com/forecast"` |
| **认证方式** | 三选一 | `"api_key"` / `"bearer"` / `"basic"` |
| **认证凭证** | 您的密钥或账密 | 见下方示例 |

---

## 📑 接口列表

### 外部数据工具接口

| 序号 | 接口 | 方法 | 说明 |
|:---:|------|------|------|
| 1 | `/api/user/external-tools` | POST | 创建外部数据工具 |
| 2 | `/api/user/external-tools/upload` | POST | 上传 JSON 文件创建工具 |
| 3 | `/api/user/external-tools` | GET | 获取工具列表 |
| 4 | `/api/user/external-tools/{tool_id}` | GET | 获取工具详情 |
| 5 | `/api/user/external-tools/{tool_id}` | PUT | 更新工具配置 |
| 6 | `/api/user/external-tools/{tool_id}` | DELETE | 删除工具 |
| 7 | `/api/user/external-tools/{tool_id}/test` | POST | 测试工具连接 |

### 工具集接口

| 序号 | 接口 | 方法 | 说明 |
|:---:|------|------|------|
| 8 | `/api/user/toolkits` | POST | 创建工具集（最多 8 个工具） |
| 9 | `/api/user/toolkits` | GET | 获取工具集列表 |
| 10 | `/api/user/toolkits/{toolkit_id}` | GET | 获取工具集详情 |
| 11 | `/api/user/toolkits/{toolkit_id}` | PUT | 更新工具集 |
| 12 | `/api/user/toolkits/{toolkit_id}` | DELETE | 删除工具集 |

### 自定义 Agent 接口

| 序号 | 接口 | 方法 | 说明 |
|:---:|------|------|------|
| 13 | `/api/user/custom-agents` | POST | 创建自定义 Agent（支持外部工具/工具集） |

---

## 1️⃣ 创建外部数据工具

### 接口

```
POST /api/user/external-tools
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `name` | string | ✅ | 工具名称（1-100字符） |
| `description` | string | ❌ | 工具描述（帮助您记忆工具用途） |
| `url` | string | ✅ | API 端点 URL |
| `auth` | object | ✅ | 认证配置（见下方示例） |
| `example` | object | ❌ | 请求参数示例（强烈建议提供） |

> 💡 **提示**：`example` 字段帮助系统理解您的 API 参数结构，强烈建议填写。

### 请求格式

```json
{
  "name": "天气查询",
  "description": "查询城市天气（可选）",
  "url": "https://api.weather.com/forecast",
  "auth": {
    "type": "api_key",
    "secret": "sk-xxxxxxxxxxxx"
  },
  "example": {
    "city": "北京",
    "units": "metric"
  }
}
```

就这么简单。系统会自动完成剩余配置。

---

## 🔐 认证方式（三选一）

### 方式 A：API Key

```json
{
  "auth": {
    "type": "api_key",
    "secret": "your-api-key-here"
  }
}
```

### 方式 B：Bearer Token

```json
{
  "auth": {
    "type": "bearer",
    "secret": "eyJhbGciOiJIUzI1NiIs..."
  }
}
```

### 方式 C：账号密码（Basic Auth）

```json
{
  "auth": {
    "type": "basic",
    "username": "admin",
    "password": "your-password"
  }
}
```

---

## 📝 完整示例

### 示例 1：天气 API

```json
{
  "name": "天气查询",
  "url": "https://api.weather.com/forecast",
  "auth": {
    "type": "api_key",
    "secret": "sk-weather-12345"
  },
  "example": {
    "city": "上海"
  }
}
```

### 示例 2：企业内部 CRM

```json
{
  "name": "客户信息查询",
  "url": "https://crm.company.com/api/customers",
  "auth": {
    "type": "bearer",
    "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "example": {
    "customer_id": "C12345"
  }
}
```

### 示例 3：数据库查询服务

```json
{
  "name": "销售数据查询",
  "url": "https://db.company.com/query",
  "auth": {
    "type": "basic",
    "username": "readonly",
    "password": "secure123"
  },
  "example": {
    "table": "sales",
    "date_range": "2026-01"
  }
}
```

---

## ✅ 响应示例

### 创建成功

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "天气查询",
    "status": "active",
    "created_at": "2026-01-23T10:00:00Z"
  },
  "message": "工具创建成功，可以开始使用了"
}
```

### 创建失败

```json
{
  "success": false,
  "error": "无法连接到您提供的 API 地址，请检查 URL 是否正确"
}
```

---

## 2️⃣ 上传 JSON 文件创建工具

### 接口

```
POST /api/user/external-tools/upload
Content-Type: multipart/form-data
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| `file` | File | ✅ | JSON 配置文件（.json） |

### JSON 文件格式

与创建接口的请求格式相同：

```json
{
  "name": "天气查询",
  "url": "https://api.weather.com/forecast",
  "auth": {
    "type": "api_key",
    "secret": "sk-weather-12345"
  },
  "example": {
    "city": "上海"
  }
}
```

---

## 3️⃣ 获取工具列表

### 接口

```
GET /api/user/external-tools
```

### 查询参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| `status` | string | ❌ | 过滤状态：active/pending/error |
| `page` | integer | ❌ | 页码，默认 1 |
| `page_size` | integer | ❌ | 每页数量，默认 20 |

### 响应示例

```json
{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "天气查询",
        "description": "查询城市天气",
        "url": "https://api.weather.com/forecast",
        "auth_type": "api_key",
        "status": "active",
        "usage_count": 15,
        "created_at": "2026-01-23T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
```

---

## 4️⃣ 获取工具详情

### 接口

```
GET /api/user/external-tools/{tool_id}
```

### 路径参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| `tool_id` | string | 工具ID（UUID） |

### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "天气查询",
    "description": "查询城市天气",
    "url": "https://api.weather.com/forecast",
    "auth_type": "api_key",
    "status": "active",
    "usage_count": 15,
    "created_at": "2026-01-23T10:00:00Z",
    "updated_at": "2026-01-23T10:00:00Z"
  }
}
```

---

## 5️⃣ 更新工具配置

### 接口

```
PUT /api/user/external-tools/{tool_id}
```

### 请求参数

与创建接口相同，支持更新以下字段：

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `name` | string | ❌ | 工具名称 |
| `description` | string | ❌ | 工具描述 |
| `url` | string | ❌ | API 端点 URL |
| `auth` | object | ❌ | 认证配置 |
| `example` | object | ❌ | 请求参数示例 |

### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "天气查询-v2",
    "status": "active",
    "updated_at": "2026-01-23T11:00:00Z"
  },
  "message": "工具更新成功"
}
```

---

## 6️⃣ 删除工具

### 接口

```
DELETE /api/user/external-tools/{tool_id}
```

### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": "工具删除成功"
}
```

---

## 7️⃣ 测试工具连接

创建后，您可以测试工具是否正常工作：

### 接口

```
POST /api/user/external-tools/{tool_id}/test
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| `test_input` | object | ❌ | 测试参数 |

### 请求示例

```json
{
  "test_input": {
    "city": "深圳"
  }
}
```

### 响应示例

```json
{
  "success": true,
  "data": {
    "connected": true,
    "response_time_ms": 156,
    "status_code": 200,
    "sample_response": {
      "status": "ok",
      "data": {
        "city": "深圳",
        "temperature": "22°C"
      }
    }
  },
  "message": "工具连接测试成功"
}
```

---

## 🧰 工具集接口

工具集允许您将多个外部数据工具组合在一起，方便部署自定义 Agent。

### 8️⃣ 创建工具集

```
POST /api/user/toolkits
```

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `name` | string | ✅ | 工具集名称（1-100字符） |
| `description` | string | ❌ | 工具集描述 |
| `tool_ids` | string[] | ✅ | 外部数据工具 ID 列表（1-8 个） |

#### 请求示例

```json
{
  "name": "数据分析工具集",
  "description": "包含数据查询和分析相关工具",
  "tool_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}
```

#### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "name": "数据分析工具集",
    "description": "包含数据查询和分析相关工具",
    "tool_count": 2,
    "created_at": "2026-01-23T10:00:00Z"
  },
  "message": "工具集创建成功"
}
```

---

### 9️⃣ 获取工具集列表

```
GET /api/user/toolkits
```

#### 查询参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `page` | integer | ❌ | 页码，默认 1 |
| `page_size` | integer | ❌ | 每页数量，默认 20，最大 100 |

#### 响应示例

```json
{
  "success": true,
  "data": {
    "toolkits": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440002",
        "name": "数据分析工具集",
        "description": "包含数据查询和分析相关工具",
        "tool_count": 2,
        "usage_count": 5,
        "created_at": "2026-01-23T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
```

---

### 🔟 获取工具集详情

```
GET /api/user/toolkits/{toolkit_id}
```

#### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "name": "数据分析工具集",
    "description": "包含数据查询和分析相关工具",
    "tool_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "550e8400-e29b-41d4-a716-446655440001"
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "天气查询",
        "description": "查询城市天气",
        "url": "https://api.weather.com/forecast",
        "status": "active"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "股票查询",
        "description": "查询股票价格",
        "url": "https://api.stock.com/price",
        "status": "active"
      }
    ],
    "usage_count": 5,
    "created_at": "2026-01-23T10:00:00Z",
    "updated_at": "2026-01-23T12:00:00Z"
  }
}
```

---

### 1️⃣1️⃣ 更新工具集

```
PUT /api/user/toolkits/{toolkit_id}
```

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `name` | string | ❌ | 工具集名称 |
| `description` | string | ❌ | 工具集描述 |
| `tool_ids` | string[] | ❌ | 工具 ID 列表（1-8 个） |

---

### 1️⃣2️⃣ 删除工具集

```
DELETE /api/user/toolkits/{toolkit_id}
```

> ⚠️ **注意**：删除工具集不会删除其中的工具，只是解除组合关系。

---

## 1️⃣3️⃣ 创建带有外部工具的自定义 Agent

### 接口

```
POST /api/user/custom-agents
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `name` | string | ✅ | Agent 名称（1-63字符） |
| `description` | string | ❌ | Agent 描述 |
| `externalTools` | string[] | ❌ | 外部数据工具 ID 列表 |
| `toolkit` | string | ❌ | 工具集 ID |
| `model` | string | ❌ | 使用的模型名称 |
| `cpuRequest` | string | ❌ | CPU 请求量，默认 "100m" |
| `memoryRequest` | string | ❌ | 内存请求量，默认 "128Mi" |

> 💡 **说明**：模板、环境变量等配置由系统自动处理，无需手动指定。

### 请求示例

使用外部数据工具：

```json
{
  "name": "my-data-agent",
  "description": "我的数据处理 Agent",
  "externalTools": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "model": "gpt-4"
}
```

使用工具集：

```json
{
  "name": "my-data-agent",
  "toolkit": "660e8400-e29b-41d4-a716-446655440002",
  "model": "gpt-4"
}
```

同时使用工具集和单独工具（会自动合并去重）：

```json
{
  "name": "my-data-agent",
  "toolkit": "660e8400-e29b-41d4-a716-446655440002",
  "externalTools": ["770e8400-e29b-41d4-a716-446655440003"],
  "model": "gpt-4"
}
```

### 响应示例

```json
{
  "success": true,
  "data": {
    "name": "my-data-agent",
    "namespace": "ai-agents",
    "status": "Pending",
    "servicePort": 8080,
    "accessInfo": {
      "domain": "my-data-agent.example.com",
      "domain_url": "https://my-data-agent.example.com"
    },
    "quotaRemaining": {
      "cpu": 0.9,
      "memory": 0.875
    }
  },
  "message": "自定义 Agent my-data-agent 创建成功"
}
```

---

## ❌ 错误响应

### 通用格式

```json
{
  "success": false,
  "error": "错误信息描述"
}
```

### 常见错误

| HTTP状态码 | 错误说明 |
|-----------|---------|
| 400 | 请求参数无效（如 URL 格式错误、名称过长等） |
| 401 | 未登录或 Token 已过期 |
| 403 | 没有操作权限或配额不足 |
| 404 | 工具或工具集不存在 |
| 409 | 工具名称已存在 |
| 500 | 服务器内部错误 |

---

## ❓ 常见问题

**Q: 我的 API 是 GET 请求，怎么办？**  
A: 不需要指定，系统会自动检测。

**Q: 我的 API 需要特殊的请求头怎么办？**  
A: 大多数情况下不需要。如果确实需要，请联系技术支持。

**Q: example 字段必须填吗？**  
A: 强烈建议填写。这帮助系统理解您的 API 参数结构。

**Q: 认证信息会被暴露吗？**  
A: 不会。您的认证凭证会被安全存储，不会在任何响应中返回。

---

## 🔧 高级配置（可选）

对于有特殊需求的用户，可以提供额外的配置：

```json
{
  "name": "...",
  "url": "...",
  "auth": { ... },
  "example": { ... },
  
  "advanced": {
    "method": "PUT",
    "headers": { "X-Custom-Header": "value" },
    "timeout": 60
  }
}
```

> ⚠️ 注意：大多数情况下不需要使用高级配置，系统会自动处理。

---

## 📊 系统自动处理

以下配置由系统自动推断，您无需关心：

| 配置项 | 自动处理方式 |
|--------|-------------|
| HTTP 方法 | 通过探测 API 自动检测 |
| Content-Type | 根据请求结构自动设置 |
| 认证头名称和位置 | 根据认证类型自动配置 |
| 请求参数结构 | 从 example 字段推断 |
| 响应解析 | 通过测试调用自动检测 |
| 超时和重试 | 使用合理默认值 |

---

**如有问题，请联系开发团队。**