forked from xiaohei/taiji-AI-PAD
更新外部数据工具和工具集
This commit is contained in:
zhanggangyong
@@ -0,0 +1,843 @@
|
||||
# 外部数据工具 - 接口文档
|
||||
|
||||
> **版本**: 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"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**如有问题，请联系开发团队。**
|
||||
|
||||
Reference in New Issue
Block a user