# 外部数据工具 - 接口文档

> **版本**: 2026-01-23 v1.0  
> **基础路径**: `/api/user/external-tools`  
> **认证方式**: Bearer Token（在请求头添加 `Authorization: Bearer <JWT Token>`）

---

## 📊 业务流程

```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              外部数据工具流程                                         │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│  ① 创建外部工具           ② Agent Manager 生成         ③ 创建自定义 Agent            │
│  ┌───────────────┐        ┌───────────────┐           ┌───────────────┐            │
│  │ POST          │  ───→  │ 生成 Pydantic │    ───→   │ POST          │            │
│  │ /external-tools│        │ 工具代码文件   │           │ /custom-agents │            │
│  └───────────────┘        └───────────────┘           │ +externalTools │            │
│         │                        │                    └───────────────┘            │
│         ↓                        ↓                           │                     │
│  保存基本信息           返回 tool_ref_id              传递 tool_ref_ids             │
│  到 PostgreSQL                                        给 Agent Manager             │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

### 核心概念

| 概念 | 说明 |
|------|------|
| **外部数据工具** | 用户创建的连接外部 API 的工具配置 |
| **tool_ref_id** | Agent Manager 生成工具后返回的标识，部署 Agent 时传递 |
| **工具状态** | pending(等待生成), active(可用), error(生成失败) |

### 存储职责划分

| 存储位置 | 存储内容 |
|---------|---------|
| **MCP-Server (PostgreSQL)** | 工具基本信息（名称、URL、方法）、tool_ref_id、状态 |
| **Agent Manager** | Pydantic 工具代码文件、完整配置（含敏感信息） |

---

## 🔐 通用请求头

```http
Content-Type: application/json
Authorization: Bearer <JWT Token>
```

---

## 📑 接口列表

### 外部数据工具接口

| 序号 | 接口 | 方法 | 说明 |
|:---:|------|------|------|
| 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 | 测试工具连接 |

### 工具集接口

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

### 自定义 Agent 接口

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

---

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

### 接口

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

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `name` | string | ✅ | 工具名称（1-100字符） |
| `description` | string | ❌ | 工具描述 |
| `url` | string | ✅ | API 端点 URL |
| `method` | string | ❌ | HTTP 方法，默认 POST |
| `headers` | object | ❌ | 自定义请求头 |
| `auth` | object | ❌ | 认证配置 |
| `request_params` | object | ❌ | URL 查询参数定义（JSON Schema） |
| `request_body` | object | ❌ | 请求体定义（JSON Schema） |
| `response_mapping` | object | ❌ | 响应字段映射 |
| `timeout` | integer | ❌ | 超时时间（秒），默认 30 |
| `retry` | object | ❌ | 重试配置 |

### 认证配置 (auth)

#### API Key 认证
```json
{
  "auth": {
    "type": "api_key",
    "key": "sk-xxxxxxxxxxxx",
    "in": "header",
    "name": "X-API-Key"
  }
}
```

#### Bearer Token 认证
```json
{
  "auth": {
    "type": "bearer",
    "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

#### Basic Auth 认证
```json
{
  "auth": {
    "type": "basic",
    "username": "admin",
    "password": "password123"
  }
}
```

### 请求示例

```json
{
  "name": "weather-query-tool",
  "description": "查询天气信息的外部数据工具",
  "url": "https://api.weather.com/v1/forecast",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "auth": {
    "type": "api_key",
    "key": "sk-xxxxxxxxxxxx",
    "in": "header",
    "name": "X-API-Key"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      }
    }
  },
  "timeout": 30
}
```

### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "weather-query-tool",
    "tool_ref_id": "tool-weather-abc123",
    "status": "active",
    "created_at": "2026-01-23T10:00:00Z"
  },
  "message": "外部数据工具创建成功"
}
```

---

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

### 接口

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

### 请求参数

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

### JSON 文件格式

```json
{
  "name": "weather-api",
  "description": "查询城市天气信息",
  "url": "https://api.weather.com/v1/forecast",
  "method": "GET",
  "auth": {
    "type": "api_key",
    "key": "your-weather-api-key",
    "in": "query",
    "name": "apikey"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      }
    }
  },
  "timeout": 10
}
```

### 响应示例

同创建接口

---

## 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": "weather-query-tool",
        "description": "查询天气信息的外部数据工具",
        "url": "https://api.weather.com/v1/forecast",
        "method": "POST",
        "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": "weather-query-tool",
    "description": "查询天气信息的外部数据工具",
    "url": "https://api.weather.com/v1/forecast",
    "method": "POST",
    "auth_type": "api_key",
    "tool_ref_id": "tool-weather-abc123",
    "status": "active",
    "usage_count": 15,
    "created_at": "2026-01-23T10:00:00Z",
    "updated_at": "2026-01-23T10:00:00Z"
  }
}
```

> **注意**：MCP-Server 只存储基本展示信息，不存储完整配置和敏感信息。

---

## 5️⃣ 更新工具配置

### 接口

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

### 请求参数

与创建接口相同，需要传递完整配置（因为 MCP-Server 不存储完整配置）。

### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "weather-query-tool-v2",
    "tool_ref_id": "tool-weather-abc123-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_params` | object | ❌ | 测试参数 |

### 请求示例

```json
{
  "test_params": {
    "city": "北京"
  }
}
```

### 响应示例

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

---

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

> **注意**: 此功能已整合到原有的自定义 Agent 创建接口中

### 接口

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

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `name` | string | ✅ | Agent 名称（1-63字符） |
| `template` | string | ✅ | Agent 模板名称（从 Agent Manager 获取） |
| `frameworkTemplate` | string | ❌ | 框架模板类型（A2A/langchain/MCP），默认 MCP |
| `description` | string | ❌ | Agent 描述 |
| `externalTools` | string[] | ❌ | **外部数据工具 ID 列表**（使用新的外部工具） |
| `tools` | string[] | ❌ | 内置工具 ID 列表 |
| `cpuRequest` | string | ❌ | CPU 请求量，默认 "100m" |
| `cpuLimit` | string | ❌ | CPU 限制量 |
| `memoryRequest` | string | ❌ | 内存请求量，默认 "128Mi" |
| `memoryLimit` | string | ❌ | 内存限制量 |
| `model` | string | ❌ | 使用的模型名称（会自动注入 LiteLLM 配置） |
| `envConfig` | object | ❌ | 自定义环境变量 |

### 请求示例（使用外部数据工具）

```json
{
  "name": "my-data-agent",
  "template": "custom_agent",
  "description": "我的数据处理 Agent",
  "externalTools": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "cpuRequest": "500m",
  "cpuLimit": "1000m",
  "memoryRequest": "512Mi",
  "memoryLimit": "1Gi",
  "model": "gpt-4"
}
```

### 响应示例

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

---

## ❌ 错误响应

### 通用格式

```json
{
  "detail": {
    "error": "错误代码",
    "message": "错误信息"
  }
}
```

### 常见错误码

| HTTP状态码 | 错误代码 | 说明 |
|-----------|---------|------|
| 400 | `invalid_config` | 工具配置格式无效 |
| 400 | `invalid_url` | URL 格式无效 |
| 400 | `invalid_tool_id` | 无效的工具 ID 格式 |
| 400 | `tool_not_active` | 工具尚未就绪 |
| 400 | `missing_tools` | 必须选择至少一个工具 |
| 400 | `quota_insufficient` | CPU/内存配额不足 |
| 403 | `no_quota` | 没有自定义Agent配额 |
| 403 | `no_model_permission` | 没有指定模型的使用权限 |
| 404 | `tool_not_found` | 工具不存在 |
| 409 | `tool_name_exists` | 工具名称已存在 |
| 500 | `am_generate_failed` | Agent Manager 生成工具失败 |

---

## 📊 Agent Manager 接口（内部使用）

以下接口由 MCP-Server 内部调用，前端无需关注：

| 接口 | 方法 | 说明 |
|------|------|------|
| `POST /tools/generate` | 生成 Pydantic 工具文件 |
| `PUT /tools/{tool_ref_id}` | 更新工具文件 |
| `DELETE /tools/{tool_ref_id}` | 删除工具文件 |
| `POST /tools/{tool_ref_id}/test` | 测试工具连接 |
| `POST /agents` | 创建 Agent（支持 tool_refs 参数） |

---

## 📋 JSON 配置文件示例

### 示例 1：天气查询工具

```json
{
  "name": "weather-api",
  "description": "查询城市天气信息",
  "url": "https://api.weather.com/v1/forecast",
  "method": "GET",
  "auth": {
    "type": "api_key",
    "key": "your-weather-api-key",
    "in": "query",
    "name": "apikey"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      },
      "units": {
        "type": "string",
        "description": "温度单位",
        "enum": ["metric", "imperial"],
        "default": "metric"
      }
    }
  },
  "timeout": 10
}
```

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

```json
{
  "name": "internal-crm-api",
  "description": "查询客户信息",
  "url": "https://internal.company.com/api/v2/customers",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "auth": {
    "type": "bearer",
    "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "request_body": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "客户ID",
        "required": true
      },
      "include_orders": {
        "type": "boolean",
        "description": "是否包含订单信息",
        "default": false
      }
    }
  },
  "response_mapping": {
    "success_field": "code",
    "success_value": 0,
    "data_field": "data",
    "error_field": "message"
  },
  "timeout": 30
}
```

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

```json
{
  "name": "db-query-service",
  "description": "执行 SQL 查询",
  "url": "https://db-gateway.company.com/query",
  "method": "POST",
  "auth": {
    "type": "basic",
    "username": "readonly",
    "password": "secure-password-123"
  },
  "request_body": {
    "type": "object",
    "properties": {
      "database": {
        "type": "string",
        "description": "数据库名称",
        "required": true
      },
      "sql": {
        "type": "string",
        "description": "SQL 查询语句",
        "required": true
      }
    }
  },
  "timeout": 60
}
```

---

## 🧰 工具集接口

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

### 9️⃣ 创建工具集

```
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": "工具集创建成功"
}
```

---

### 🔟 获取工具集列表

```
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
  }
}
```

---

### 1️⃣1️⃣ 获取工具集详情

```
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": "weather-api",
        "description": "天气查询 API",
        "url": "https://api.weather.com/current",
        "method": "GET",
        "status": "active"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "stock-api",
        "description": "股票查询 API",
        "url": "https://api.stock.com/price",
        "method": "GET",
        "status": "active"
      }
    ],
    "usage_count": 5,
    "created_at": "2026-01-23T10:00:00Z",
    "updated_at": "2026-01-23T12:00:00Z"
  }
}
```

---

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

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

#### 请求参数

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

---

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

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

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

---

## 📌 在自定义 Agent 中使用工具集

创建自定义 Agent 时，可以通过 `toolkit` 字段指定工具集：

```json
{
  "name": "my-data-agent",
  "template": "custom_agent",
  "toolkit": "660e8400-e29b-41d4-a716-446655440002",
  "cpuRequest": "500m",
  "memoryRequest": "512Mi"
}
```

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

```json
{
  "name": "my-data-agent",
  "template": "custom_agent",
  "toolkit": "660e8400-e29b-41d4-a716-446655440002",
  "externalTools": ["770e8400-e29b-41d4-a716-446655440003"],
  "cpuRequest": "500m",
  "memoryRequest": "512Mi"
}
```

---

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