# 数据工具与自定义Agent - 接口文档

> **版本**: 2026-01-13 v4  
> **基础路径**: `/api/user`  
> **认证方式**: Bearer Token（在请求头添加 `Authorization: Bearer <JWT Token>`）  
> **状态**: ✅ 已修复

---

## 📊 业务流程

```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              业务流程                                                │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│  ① 获取模板列表         ② 创建工具（基于模板）        ③ 创建Agent（选择工具）        │
│  ┌───────────────┐     ┌───────────────┐            ┌───────────────┐              │
│  │ GET           │     │ POST          │            │ POST          │              │
│  │ /templates    │────→│ /tools/create │───────────→│ /custom-agents│              │
│  └───────────────┘     └───────────────┘            └───────────────┘              │
│         │                     │                            │                       │
│         ↓                     ↓                            ↓                       │
│  返回 dataTemplates    保存到 Tool 表               从工具获取 template             │
│  [mysql_agent,         - template: mysql_agent      和 envConfig，                  │
│   postgresql_agent]    - env_config: {...}          传递给 Agent Manager            │
│                                                                                     │
│  含 env_info:                                                                       │
│  - required                                                                         │
│  - optional                                                                         │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

### 核心概念

| 概念 | 说明 |
|------|------|
| **模板 (dataTemplates)** | Agent 镜像类型，来自 Agent Manager，如 `mysql_agent`，包含 `env_info` 定义所需配置 |
| **工具 (Tool)** | 用户基于模板创建的配置实例，包含 **`template` + `env_config`** |
| **自定义 Agent** | 根据工具的模板类型和配置创建的 K8s Pod |

---

## 🔐 通用请求头

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

---

## 📑 接口列表

| 序号 | 接口 | 方法 | 说明 |
|:---:|------|------|------|
| 1 | `/api/user/custom-agents/templates` | GET | 获取自定义Agent模板 |
| 2 | `/api/user/tools/create` | POST | 创建工具 |
| 3 | `/api/user/tools` | GET | 获取用户工具列表 |
| 4 | `/api/user/tools/{tool_id}` | PUT | 更新工具 |
| 5 | `/api/user/tools/{tool_id}` | DELETE | 删除工具 |
| 6 | `/api/user/custom-agents` | POST | 创建自定义Agent |
| 7 | `/api/user/custom-agents` | GET | 获取用户自定义Agent列表 |
| 8 | `/api/user/custom-agents/{name}` | DELETE | 删除自定义Agent |

---

## 1️⃣ 获取自定义Agent模板

### 接口

```
GET /api/user/custom-agents/templates
```

### 请求参数

无

### 响应参数

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `data.frameworkTemplates` | string[] | 框架类型列表 |
| `data.dataTemplates` | array | 数据存储模板列表 |
| `data.dataTemplates[].template` | string | 模板名称 |
| `data.dataTemplates[].port` | number \| null | 服务端口 |
| `data.dataTemplates[].env_info.required` | object | 必需的环境变量 |
| `data.dataTemplates[].env_info.optional` | object | 可选的环境变量 |
| `data.dataTemplates[].description` | string | 模板描述 |

### 响应示例

```json
{
  "success": true,
  "data": {
    "frameworkTemplates": ["A2A", "langchain", "MCP"],
    "dataTemplates": [
      {
        "template": "mysql_agent",
        "port": null,
        "env_info": {
          "required": {
            "MYSQL_HOST": "MySQL数据库主机地址",
            "MYSQL_USER": "MySQL用户名",
            "MYSQL_PASSWORD": "MySQL密码",
            "MYSQL_DATABASE": "MySQL数据库名",
            "OPENAI_API_KEY": "OpenAI API密钥"
          },
          "optional": {
            "MYSQL_PORT": "MySQL端口，默认3306"
          }
        },
        "description": "MySQL 数据库 Agent，支持 SQL 查询和数据操作"
      },
      {
        "template": "postgresql_agent",
        "port": null,
        "env_info": {
          "required": {
            "POSTGRES_HOST": "PostgreSQL数据库主机地址",
            "POSTGRES_USER": "PostgreSQL用户名",
            "POSTGRES_PASSWORD": "PostgreSQL密码",
            "POSTGRES_DATABASE": "PostgreSQL数据库名",
            "OPENAI_API_KEY": "OpenAI API密钥"
          },
          "optional": {
            "POSTGRES_PORT": "PostgreSQL端口，默认5432"
          }
        },
        "description": "PostgreSQL 数据库 Agent，支持 SQL 查询和数据操作"
      }
    ]
  }
}
```

> **注意**：`OPENAI_API_KEY` 虽然在模板 `env_info.required` 中列出，但**用户无需填写**。系统会在创建 Agent 时自动注入用户的 LiteLLM 密钥。

---

## 2️⃣ 创建工具（基于模板）

### 接口

```
POST /api/user/tools/create
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `name` | string | ✅ | 工具名称 |
| `description` | string | ❌ | 工具描述 |
| `template` | string | ✅ | 模板名称（来自 `dataTemplates[].template`） |
| `envConfig` | object | ✅ | 环境变量配置（根据模板 `env_info` 填写） |

### 请求示例（MySQL 工具）

```json
{
  "name": "my-mysql-tool",
  "description": "我的MySQL数据库连接工具",
  "template": "mysql_agent",
  "envConfig": {
    "MYSQL_HOST": "mysql.example.com",
    "MYSQL_USER": "root",
    "MYSQL_PASSWORD": "password123",
    "MYSQL_DATABASE": "mydb",
    "MYSQL_PORT": "3306"
  }
}
```

### 请求示例（PostgreSQL 工具）

```json
{
  "name": "my-pgsql-tool",
  "description": "我的PostgreSQL数据库连接工具",
  "template": "postgresql_agent",
  "envConfig": {
    "POSTGRES_HOST": "postgres.example.com",
    "POSTGRES_USER": "postgres",
    "POSTGRES_PASSWORD": "password123",
    "POSTGRES_DATABASE": "mydb",
    "POSTGRES_PORT": "5432"
  }
}
```

> **注意**：`OPENAI_API_KEY` 无需填写，系统会自动注入用户的 LiteLLM 密钥。

### 响应参数

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `data.id` | string | 工具ID（UUID） |
| `data.name` | string | 工具名称 |
| `data.template` | string | 模板名称 |
| `data.type` | string | 工具类型（database） |
| `message` | string | 响应消息 |

### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "d14cd898-e2cf-4150-a7f9-53b962c1c9a2",
    "name": "my-mysql-tool",
    "template": "mysql_agent",
    "type": "database"
  },
  "message": "工具创建成功"
}
```

---

## 3️⃣ 获取用户工具列表

### 接口

```
GET /api/user/tools
```

### 请求参数

无

### 响应参数

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `data.tools` | array | 工具列表 |
| `data.tools[].id` | string | 工具ID（UUID） |
| `data.tools[].name` | string | 工具名称 |
| `data.tools[].description` | string | 工具描述 |
| `data.tools[].template` | string | 模板名称 |
| `data.tools[].category` | string | 工具分类 |
| `data.tools[].envConfig` | object | 环境变量配置（敏感信息已脱敏） |
| `data.tools[].created_at` | string | 创建时间（ISO 8601） |
| `data.tools[].updated_at` | string | 更新时间（ISO 8601） |
| `data.tools[].is_active` | boolean | 是否激活 |
| `data.tools[].is_public` | boolean | 是否公开 |

### 响应示例

```json
{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "d14cd898-e2cf-4150-a7f9-53b962c1c9a2",
        "name": "my-mysql-tool",
        "description": "我的MySQL数据库连接工具",
        "template": "mysql_agent",
        "category": "database",
        "envConfig": {
          "MYSQL_HOST": "mysql.example.com",
          "MYSQL_USER": "root",
          "MYSQL_PASSWORD": "pa******23",
          "MYSQL_DATABASE": "mydb",
          "MYSQL_PORT": "3306",
          "OPENAI_API_KEY": "sk******xx"
        },
        "type": "database",
        "endpoint": null,
        "method": null,
        "created_at": "2026-01-13T08:00:00Z",
        "updated_at": "2026-01-13T08:00:00Z",
        "is_active": true,
        "is_public": false
      }
    ]
  }
}
```

> **注意**：响应中的 `envConfig` 会对敏感字段（密码、API密钥等）进行脱敏处理。

---

## 4️⃣ 更新工具

### 接口

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

### 路径参数

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

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|:---:|------|
| `description` | string | ❌ | 工具描述 |
| `is_active` | boolean | ❌ | 是否激活 |
| `envConfig` | object | ❌ | 更新环境变量配置 |

> **注意**：`template` 字段创建后不可修改。

### 请求示例

```json
{
  "description": "更新后的MySQL数据库工具",
  "envConfig": {
    "MYSQL_HOST": "mysql-new.example.com",
    "MYSQL_USER": "admin",
    "MYSQL_PASSWORD": "newpassword123",
    "MYSQL_DATABASE": "mydb",
    "MYSQL_PORT": "3306",
    "OPENAI_API_KEY": "sk-newkey"
  }
}
```

### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "d14cd898-e2cf-4150-a7f9-53b962c1c9a2",
    "name": "my-mysql-tool",
    "template": "mysql_agent",
    "updated_at": "2026-01-13T10:00:00Z"
  },
  "message": "工具更新成功"
}
```

---

## 5️⃣ 删除工具

### 接口

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

### 路径参数

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

### 响应示例

```json
{
  "success": true,
  "data": {
    "id": "d14cd898-e2cf-4150-a7f9-53b962c1c9a2"
  },
  "message": "工具删除成功"
}
```

---

## 6️⃣ 创建自定义Agent

> **核心逻辑**：创建 Agent 时选择已创建的工具，系统自动从工具获取 `template` 和 `envConfig`，调用 Agent Manager 创建对应类型的 Agent。

### 接口

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

### 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----|------|:---:|:---:|------|
| `name` | string | ✅ | - | Agent名称（小写字母、数字、连字符，1-63字符） |
| `tools` | string[] | ✅ | - | **工具ID列表（第一个工具决定Agent类型和配置）** |
| `template` | string | ❌ | 从工具获取 | 模板名称（可选，未指定时从工具获取） |
| `frameworkTemplate` | string | ❌ | "MCP" | 框架类型（"MCP" \| "A2A" \| "langchain"） |
| `description` | string | ❌ | - | Agent描述 |
| `cpuRequest` | string | ❌ | "100m" | CPU请求量 |
| `cpuLimit` | string | ❌ | =cpuRequest | CPU限制量 |
| `memoryRequest` | string | ❌ | "128Mi" | 内存请求量 |
| `memoryLimit` | string | ❌ | =memoryRequest | 内存限制量 |
| `model` | string | ❌ | - | 模型名称（用于注入 LiteLLM 密钥） |
| `envConfig` | object | ❌ | {} | 额外环境变量（与工具配置合并，请求中的优先） |
| `agentRole` | string | ❌ | - | A2A框架：Agent角色 |
| `agentCapabilities` | string[] | ❌ | - | A2A框架：Agent能力列表 |

### 环境变量优先级

环境变量从以下来源合并，后者覆盖前者：
1. 工具的 `env_config`
2. 请求中的 `envConfig`

### 请求示例（基于已创建的工具）

```json
{
  "name": "my-mysql-agent",
  "tools": ["d14cd898-e2cf-4150-a7f9-53b962c1c9a2"],
  "description": "我的MySQL数据库Agent",
  "cpuRequest": "500m",
  "cpuLimit": "1000m",
  "memoryRequest": "1Gi",
  "memoryLimit": "2Gi",
  "model": "gpt-4"
}
```

> 系统自动从工具获取 `template: "mysql_agent"` 和 `envConfig: {MYSQL_HOST, ...}`

### 请求示例（A2A框架）

```json
{
  "name": "my-pgsql-agent",
  "tools": ["e25de999-f3dg-5261-b8ga-64c073d2d0b3"],
  "frameworkTemplate": "A2A",
  "description": "我的PostgreSQL数据分析Agent",
  "cpuRequest": "1000m",
  "memoryRequest": "2Gi",
  "model": "gpt-4",
  "agentRole": "data_analyzer",
  "agentCapabilities": ["sql_query", "data_analysis", "report_generation"]
}
```

### 响应参数

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `data.name` | string | Agent 名称 |
| `data.namespace` | string | Kubernetes 命名空间 |
| `data.status` | string | Agent 状态 |
| `data.servicePort` | number \| null | 服务端口 |
| `data.accessInfo` | object \| null | 访问信息 |
| `data.modelInjected` | boolean | 是否注入了模型配置 |
| `data.quotaRemaining.cpu` | number | 剩余 CPU（核） |
| `data.quotaRemaining.memory` | number | 剩余内存（GB） |
| `message` | string | 响应消息 |

### 响应示例

```json
{
  "success": true,
  "data": {
    "name": "my-mysql-agent",
    "namespace": "ai-agents",
    "status": "Pending",
    "servicePort": 8080,
    "accessInfo": {
      "endpoints": {
        "http": "http://my-mysql-agent.ai-agents.svc.cluster.local:8080"
      }
    },
    "modelInjected": true,
    "quotaRemaining": {
      "cpu": 3.5,
      "memory": 7.0
    }
  },
  "message": "自定义 Agent my-mysql-agent 创建成功"
}
```

---

## 7️⃣ 获取用户自定义Agent列表

### 接口

```
GET /api/user/custom-agents
```

### 请求参数

无

### 响应参数

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `data.agents` | array | Agent列表 |
| `data.agents[].name` | string | Agent名称 |
| `data.agents[].template` | string | 模板名称 |
| `data.agents[].status` | string | 状态 |
| `data.agents[].cpu` | string | CPU请求量 |
| `data.agents[].memory` | string | 内存请求量 |
| `data.agents[].startTime` | string \| null | 启动时间 |
| `data.agents[].runningSeconds` | number | 运行时长（秒） |

### 响应示例

```json
{
  "success": true,
  "data": {
    "agents": [
      {
        "name": "my-mysql-agent",
        "template": "mysql_agent",
        "status": "Running",
        "cpu": "500m",
        "memory": "1Gi",
        "startTime": "2026-01-13T08:00:00Z",
        "runningSeconds": 3600
      }
    ]
  }
}
```

---

## 8️⃣ 删除自定义Agent

### 接口

```
DELETE /api/user/custom-agents/{name}
```

### 路径参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| `name` | string | Agent名称 |

### 响应参数

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `data.name` | string | 已删除的Agent名称 |
| `data.quotaReleased.cpu` | number | 释放的CPU（核） |
| `data.quotaReleased.memory` | number | 释放的内存（GB） |
| `data.cost` | number | 产生的费用 |
| `data.duration` | number | 运行时长（秒） |
| `message` | string | 响应消息 |

### 响应示例

```json
{
  "success": true,
  "data": {
    "name": "my-mysql-agent",
    "quotaReleased": {
      "cpu": 0.5,
      "memory": 1.0
    },
    "cost": 0.05,
    "duration": 3600
  },
  "message": "自定义 Agent my-mysql-agent 删除成功，已释放配额"
}
```

---

## ❌ 错误响应

### 通用格式

```json
{
  "detail": {
    "error": "错误代码",
    "message": "错误信息",
    "detail": "详细信息（可选）"
  }
}
```

### 常见错误码

| HTTP状态码 | 错误代码 | 说明 |
|-----------|---------|------|
| 400 | `invalid_template` | 无效的模板名称 |
| 400 | `quota_insufficient` | CPU/内存配额不足 |
| 400 | `invalid_tool_id` | 无效的工具ID格式 |
| 400 | `missing_template` | 必须指定 template 参数或选择包含模板配置的工具 |
| 403 | `no_quota` | 用户没有自定义Agent配额 |
| 403 | `no_model_permission` | 没有指定模型的使用权限 |
| 404 | `agent_not_found` | Agent不存在或不属于当前用户 |
| 404 | `tool_not_found` | 工具不存在 |
| 409 | `name_exists` | 工具/Agent名称已存在 |
| 500 | `create_agent_failed` | Agent Manager创建失败 |

### 错误示例

```json
{
  "detail": {
    "error": "quota_insufficient",
    "message": "CPU 配额不足。剩余: 0.50 核，请求: 1.00 核"
  }
}
```

---

## 📊 后端服务调用关系

```
┌─────────┐      ┌─────────────┐      ┌───────────────┐      ┌─────────┐
│  前端   │ ←──→ │  MCP-Server │ ←──→ │ Agent Manager │ ←──→ │   K8s   │
└─────────┘      └─────────────┘      └───────────────┘      └─────────┘
                        │
                        ↓
                   ┌─────────┐
                   │ 数据库  │
                   │PostgreSQL│
                   └─────────┘
```

### MCP-Server 转发到 Agent Manager 的接口

| 前端接口 | Agent Manager 接口 |
|---------|-------------------|
| `GET /custom-agents/templates` | `GET /templates/custom` |
| `POST /custom-agents` | `POST /agents` |
| `GET /custom-agents` | `GET /agents/{name}/status` |
| `DELETE /custom-agents/{name}` | `DELETE /agents/{name}` |

### MCP-Server 本地处理的接口

| 接口 | 说明 |
|------|------|
| `POST /tools/create` | 保存到 Tool 表 |
| `GET /tools` | 从 Tool 表查询 |
| `PUT /tools/{tool_id}` | 更新 Tool 表 |
| `DELETE /tools/{tool_id}` | 从 Tool 表删除 |

---

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