forked from xiaohei/taiji-AI-PAD
887 lines
23 KiB
Markdown
887 lines
23 KiB
Markdown
# 数据与工具模块 - 前端对接文档（完整版）
|
||
|
||
> **版本**: v2.1.0
|
||
> **更新时间**: 2026-01-13
|
||
> **后端服务**: mcp-server
|
||
> **接口验证状态**: ✅ 已验证
|
||
> **重要更新**: 模板接口返回格式变更，区分数据存储模板和框架类型
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [功能概述](#功能概述)
|
||
2. [核心概念说明](#核心概念说明)
|
||
3. [接口完整清单](#接口完整清单)
|
||
4. [工具统计数据](#工具统计数据)
|
||
5. [工具注册表管理](#工具注册表管理)
|
||
6. [自定义Agent部署](#自定义agent部署)
|
||
7. [错误处理](#错误处理)
|
||
8. [完整业务流程](#完整业务流程)
|
||
|
||
---
|
||
|
||
## 功能概述
|
||
|
||
### 页面功能说明
|
||
|
||
**数据与工具模块** - API市场和工具生成平台，包括：
|
||
|
||
1. **首行统计卡片**：展示总工具数（实际为Agent数）、生成的工具、活跃的工具数
|
||
2. **工具注册表**：管理和监控生成的API工具（工具名称、类别、方法、端点、状态、创建时间、操作）
|
||
3. **自定义Agent管理**：管理已部署的自定义Agent，支持停止和删除操作
|
||
4. **部署Agent对话框**：根据Agent框架注册工具并配置Pod资源
|
||
|
||
---
|
||
|
||
## 核心概念说明
|
||
|
||
### 术语映射
|
||
|
||
| 前端术语 | 后端术语 | 说明 |
|
||
|---------|---------|------|
|
||
| **工具（Tools）** | Tools | 传入Agent的工具，具有特定功能的组件（如API调用、数据库查询等） |
|
||
| **自定义Agent** | Custom Agent | **用户自己创建和配置的Agent**，可以选择工具、框架模板、资源配置，部署后独立运行 |
|
||
| **平台Agent** | Platform Agent | **平台预置的Agent模板**，由系统管理员预先配置好，用户可直接使用 |
|
||
| **数据存储模板** | Data Template | **决定Agent镜像类型**（如 mysql_agent、postgresql_agent），对应 `template` 参数 |
|
||
| **框架类型** | Framework Template | **决定Agent运行框架**（MCP/A2A/langchain），对应 `frameworkTemplate` 参数 |
|
||
| **服务网关** | Gateway | Agent使用的通信网关类型（MCP/A2A/API） |
|
||
|
||
### ⚠️ 重要概念区分
|
||
|
||
创建自定义Agent时需要区分两个关键参数：
|
||
|
||
| 参数名 | 含义 | 来源 | 示例值 |
|
||
|-------|------|------|--------|
|
||
| `template` | 数据存储模板 | `dataTemplates[].template` | `mysql_agent`, `postgresql_agent` |
|
||
| `frameworkTemplate` | 框架类型 | `frameworkTemplates[]` | `MCP`, `A2A`, `langchain` |
|
||
|
||
**常见错误**：将框架类型（如 `a2a-agent`）误传给 `template` 参数，导致 Agent Manager 返回"无效的模板名称"错误。
|
||
|
||
### 自定义Agent vs 平台Agent
|
||
|
||
| 特性 | 自定义Agent | 平台Agent |
|
||
|------|-----------|----------|
|
||
| **创建方式** | 用户自己创建配置 | 系统管理员预置 |
|
||
| **工具选择** | 用户选择需要的工具 | 预先配置好的工具 |
|
||
| **资源配置** | 用户自定义CPU/内存 | 使用平台配置 |
|
||
| **配额管理** | 自定义Agent配额 | 平台Agent配额 |
|
||
| **使用场景** | 个性化需求，灵活配置 | 标准化功能，开箱即用 |
|
||
| **接口前缀** | `/api/user/custom-agents` | `/api/user/agents/platform` |
|
||
|
||
### 自定义Agent创建流程
|
||
|
||
```
|
||
1. 调用 GET /api/user/custom-agents/templates 获取模板信息
|
||
├── frameworkTemplates: 框架类型列表
|
||
└── dataTemplates: 数据存储模板列表（含环境变量要求）
|
||
↓
|
||
2. （可选）调用 GET /api/user/tools 获取已创建的工具列表
|
||
↓
|
||
3. 点击"创建自定义Agent"
|
||
↓
|
||
4. 选择数据存储模板（如 mysql_agent）→ 对应 template 参数
|
||
↓
|
||
5. 选择框架类型（MCP/A2A/langchain）→ 对应 frameworkTemplate 参数
|
||
↓
|
||
6. 填写基本信息（名称、描述）
|
||
↓
|
||
7. 根据 env_info.required 填写必需环境变量（如数据库连接信息）
|
||
↓
|
||
8. （可选）选择已注册的工具 → 对应 tools 参数（工具UUID列表）
|
||
↓
|
||
9. （可选）选择模型 → 对应 model 参数，会自动注入LiteLLM配置
|
||
↓
|
||
10. 配置资源（CPU、内存）
|
||
↓
|
||
11. 提交创建 POST /api/user/custom-agents
|
||
↓
|
||
12. **自动调用Agent Manager部署到K8s集群**
|
||
↓
|
||
13. Pod启动，Agent状态变为Running
|
||
↓
|
||
14. 可以使用Agent功能（停止、删除、扩缩容）
|
||
```
|
||
|
||
### 平台Agent使用流程
|
||
|
||
```
|
||
1. 查看可用的平台Agent列表
|
||
↓
|
||
2. 选择需要的平台Agent
|
||
↓
|
||
3. 检查配额是否足够
|
||
↓
|
||
4. 点击"部署"
|
||
↓
|
||
5. **自动部署平台Agent实例到K8s**
|
||
↓
|
||
6. 开始使用平台Agent功能
|
||
```
|
||
|
||
### 工具（Tools）与Agent的关系
|
||
|
||
- **工具（Tools）**：具有特定功能的组件（如天气查询工具、数据库查询工具等）
|
||
- **自定义Agent**：使用一个或多个工具来完成任务的Agent实例
|
||
- **框架模板（MCP/A2A/API）**：定义Agent的通信协议和运行框架，传递给Agent Manager服务
|
||
- **关系**：一个自定义Agent可以使用多个工具，工具是传入Agent的参数
|
||
|
||
### 统计指标说明
|
||
|
||
根据工具统计接口 `/api/user/tools/stats` 返回的数据：
|
||
- **总工具数** = 用户创建的工具总数（Tool表中owner_id为当前用户的记录数）
|
||
- **生成的工具** = 用户创建的工具总数（与totalTools相同）
|
||
- **活跃的工具数** = 所有运行中的Agent使用的工具总数（从AgentBillingRecord.tools_used字段统计，去重后）
|
||
|
||
---
|
||
|
||
## 接口完整清单
|
||
|
||
### 认证方式
|
||
|
||
所有接口都需要在请求头中携带JWT Token：
|
||
|
||
```http
|
||
Authorization: Bearer {access_token}
|
||
```
|
||
|
||
### 接口列表
|
||
|
||
| 功能模块 | 方法 | 接口路径 | 说明 |
|
||
|---------|------|---------|------|
|
||
| **工具统计** | GET | `/api/user/tools/stats` | 获取工具统计数据（用于首行统计卡片） |
|
||
| **获取工具列表** | GET | `/api/user/tools` | 获取用户创建的所有工具（Tools） |
|
||
| **创建工具** | POST | `/api/user/tools/create` | 创建工具（Tools），不含资源配置 |
|
||
| **修改工具** | PUT | `/api/user/tools/{tool_id}` | 修改工具功能和配置 |
|
||
| **删除工具** | DELETE | `/api/user/tools/{tool_id}` | 删除工具 |
|
||
| **创建自定义Agent** | POST | `/api/user/custom-agents` | 创建并部署自定义Agent到K8s集群 |
|
||
| **获取自定义Agent列表** | GET | `/api/user/custom-agents` | 获取用户的所有自定义Agent |
|
||
| **停止自定义Agent** | POST | `/api/user/custom-agents/{name}/stop` | 停止运行中的自定义Agent |
|
||
| **删除自定义Agent** | DELETE | `/api/user/custom-agents/{name}` | 删除自定义Agent |
|
||
| **扩缩容自定义Agent** | PUT | `/api/user/custom-agents/{name}/scale` | 修改自定义Agent的CPU/内存配置 |
|
||
| **获取平台Agent列表** | GET | `/api/user/agents/platform` | 获取可用的平台Agent列表 |
|
||
| **部署平台Agent** | POST | `/api/user/agents/deploy` | 部署平台Agent实例 |
|
||
| **模板信息** | GET | `/api/user/custom-agents/templates` | 获取创建Agent所需的模板信息（含数据存储模板和框架类型） |
|
||
| **模型列表** | GET | `/api/user/models` | 获取当前用户可使用的模型列表 |
|
||
|
||
---
|
||
|
||
## 工具统计数据
|
||
|
||
### 接口说明
|
||
|
||
首行统计卡片的数据来源于工具统计接口，用于展示工具的创建和使用情况。
|
||
|
||
### 请求示例
|
||
|
||
```http
|
||
GET /api/user/tools/stats
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"totalTools": 15,
|
||
"generatedTools": 15,
|
||
"activeTools": 8
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| totalTools | number | 用户创建的工具总数（Tool表） |
|
||
| generatedTools | number | 用户创建的工具总数（与totalTools相同） |
|
||
| activeTools | number | 所有运行中的Agent使用的工具总数（去重后） |
|
||
|
||
### 统计数据计算规则
|
||
|
||
- **总工具数** = 用户在Tool表中创建的工具数量
|
||
- **生成的工具** = 用户在Tool表中创建的工具数量
|
||
- **活跃的工具数** = 从所有运行中Agent的`tools_used`字段统计，去重后的唯一工具ID数量
|
||
|
||
---
|
||
|
||
## Agent统计数据
|
||
|
||
### 接口说明
|
||
|
||
Agent列表接口用于获取用户的自定义Agent信息。
|
||
|
||
### 请求示例
|
||
|
||
```http
|
||
GET /api/user/custom-agents
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"agents": [
|
||
{
|
||
"name": "my-tool-1",
|
||
"template": "python-mcp-agent",
|
||
"status": "Running",
|
||
"cpu": "1000m",
|
||
"memory": "2Gi",
|
||
"startTime": "2026-01-10T08:00:00Z",
|
||
"runningSeconds": 86400
|
||
},
|
||
{
|
||
"name": "my-tool-2",
|
||
"template": "nodejs-api-agent",
|
||
"status": "Stopped",
|
||
"cpu": "500m",
|
||
"memory": "1Gi",
|
||
"startTime": "2026-01-09T12:00:00Z",
|
||
"runningSeconds": 0
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | string | Agent名称（唯一标识） |
|
||
| template | string | 使用的框架模板（传递给Agent Manager） |
|
||
| status | string | 状态：Running（运行中）、Stopped（已停止）、unknown（未知） |
|
||
| cpu | string | CPU配置（如：1000m = 1核） |
|
||
| memory | string | 内存配置（如：2Gi = 2GB） |
|
||
| startTime | string | 创建时间（ISO 8601格式） |
|
||
| runningSeconds | number | 运行时长（秒） |
|
||
|
||
---
|
||
|
||
## 工具（Tools）管理
|
||
|
||
### 1. 获取工具列表
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
GET /api/user/tools
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"tools": [
|
||
{
|
||
"id": "tool-550e8400-e29b-41d4-a716-446655440000",
|
||
"name": "weather-query-tool",
|
||
"description": "查询天气信息的工具",
|
||
"type": "api",
|
||
"category": "api",
|
||
"endpoint": "https://api.weather.com/v1/forecast",
|
||
"method": "GET",
|
||
"created_at": "2026-01-10T08:00:00Z",
|
||
"updated_at": "2026-01-11T10:30:00Z",
|
||
"is_active": true,
|
||
"is_public": false
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 创建工具
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
POST /api/user/tools/create
|
||
Authorization: Bearer {token}
|
||
Content-Type: application/json
|
||
```
|
||
|
||
#### 请求体
|
||
|
||
```json
|
||
{
|
||
"name": "weather-query-tool",
|
||
"description": "查询天气信息的工具",
|
||
"type": "api",
|
||
"config": {
|
||
"endpoint": "https://api.weather.com/v1/forecast",
|
||
"method": "GET",
|
||
"apiKey": "your-api-key"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "tool-550e8400-e29b-41d4-a716-446655440000",
|
||
"name": "weather-query-tool",
|
||
"type": "api"
|
||
},
|
||
"message": "工具创建成功"
|
||
}
|
||
|
||
#### 使用说明
|
||
|
||
- **用途**：创建纯工具（Tools）对象，不包含资源配置
|
||
- **区别**：与 `/api/user/tools/generate` 不同，本接口只创建工具定义，不创建Agent
|
||
- **工具用途**：创建的工具可以在部署Agent时选择使用
|
||
|
||
### 3. 修改工具功能
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
PUT /api/user/tools/{tool_id}
|
||
Authorization: Bearer {token}
|
||
Content-Type: application/json
|
||
```
|
||
|
||
#### 请求体
|
||
|
||
```json
|
||
{
|
||
"description": "更新后的工具描述",
|
||
"config": {
|
||
"endpoint": "https://api.weather.com/v2/forecast",
|
||
"method": "GET",
|
||
"apiKey": "new-api-key"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "工具更新成功",
|
||
"data": {
|
||
"id": "tool-550e8400-e29b-41d4-a716-446655440000",
|
||
"name": "weather-query-tool",
|
||
"updated_at": "2026-01-11T10:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 删除工具
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
DELETE /api/user/tools/{tool_id}
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "工具已删除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 自定义Agent管理
|
||
|
||
### 1. 获取自定义Agent列表
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
GET /api/user/custom-agents
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"agents": [
|
||
{
|
||
"name": "weather-api-agent",
|
||
"template": "mcp-agent",
|
||
"status": "Running",
|
||
"cpu": "500m",
|
||
"memory": "1Gi",
|
||
"startTime": "2026-01-10T08:00:00Z",
|
||
"runningSeconds": 86400
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 创建自定义Agent（部署到K8s）
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
POST /api/user/custom-agents
|
||
Authorization: Bearer {token}
|
||
Content-Type: application/json
|
||
```
|
||
|
||
#### 说明
|
||
|
||
**本接口会实际调用Agent Manager服务，将自定义Agent部署到K8s集群。**
|
||
|
||
创建后Agent会立即启动，用户可以直接使用。
|
||
|
||
#### 请求体示例
|
||
|
||
**示例1：创建 MySQL Agent (MCP框架)**
|
||
```json
|
||
{
|
||
"name": "my-mysql-agent",
|
||
"template": "mysql_agent",
|
||
"frameworkTemplate": "MCP",
|
||
"description": "我的MySQL数据库Agent",
|
||
"cpuRequest": "500m",
|
||
"cpuLimit": "1000m",
|
||
"memoryRequest": "1Gi",
|
||
"memoryLimit": "2Gi",
|
||
"tools": ["tool-uuid-1", "tool-uuid-2"],
|
||
"model": "gpt-4",
|
||
"envConfig": {
|
||
"MYSQL_HOST": "mysql.example.com",
|
||
"MYSQL_USER": "root",
|
||
"MYSQL_PASSWORD": "password123",
|
||
"MYSQL_DATABASE": "mydb"
|
||
}
|
||
}
|
||
```
|
||
|
||
**示例2：创建 PostgreSQL Agent (A2A框架)**
|
||
```json
|
||
{
|
||
"name": "my-pgsql-agent",
|
||
"template": "postgresql_agent",
|
||
"frameworkTemplate": "A2A",
|
||
"description": "我的PostgreSQL数据库Agent",
|
||
"cpuRequest": "1000m",
|
||
"memoryRequest": "1Gi",
|
||
"tools": ["tool-uuid-1"],
|
||
"model": "gpt-4",
|
||
"agentRole": "data_analyzer",
|
||
"agentCapabilities": ["sql_query", "data_analysis"],
|
||
"envConfig": {
|
||
"PG_HOST": "postgres.example.com",
|
||
"PG_USER": "postgres",
|
||
"PG_PASSWORD": "password123",
|
||
"PG_DATABASE": "mydb"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 请求字段说明
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| name | string | ✅ | Agent名称（小写字母、数字、连字符） |
|
||
| template | string | ✅ | **数据存储模板名称**（从 `dataTemplates` 获取，如 `mysql_agent`、`postgresql_agent`） |
|
||
| frameworkTemplate | string | 否 | **框架类型**（从 `frameworkTemplates` 获取：A2A/langchain/MCP），默认MCP |
|
||
| description | string | 否 | Agent描述 |
|
||
| cpuRequest | string | ✅ | CPU请求量（如"500m"） |
|
||
| cpuLimit | string | 否 | CPU限制量（如"1000m"），默认与request相同 |
|
||
| memoryRequest | string | ✅ | 内存请求量（如"1Gi"） |
|
||
| memoryLimit | string | 否 | 内存限制量（如"2Gi"），默认与request相同 |
|
||
| tools | array | 否 | 选择的工具ID列表（从 `/api/user/tools` 获取的工具UUID） |
|
||
| model | string | 否 | 使用的模型名称（如 `gpt-4`），会自动注入LiteLLM环境变量 |
|
||
| endpoint | string | 否 | 自定义终结点 |
|
||
| apiKey | string | 否 | API密钥 |
|
||
| envConfig | object | 否 | 环境变量配置（数据库连接信息等，参考 `env_info.required`） |
|
||
| agentRole | string | 否 | A2A框架专用：Agent角色（如 `data_analyzer`） |
|
||
| agentCapabilities | array | 否 | A2A框架专用：Agent能力列表（如 `["sql_query", "data_analysis"]`） |
|
||
|
||
#### ⚠️ 重要提醒
|
||
|
||
1. **template 参数**：必须使用 `/api/user/custom-agents/templates` 返回的 `dataTemplates[].template` 值
|
||
- ✅ 正确：`"template": "mysql_agent"`
|
||
- ❌ 错误：`"template": "a2a-agent"` （这不是有效的数据存储模板）
|
||
|
||
2. **envConfig 参数**：根据选择的 template，需要填写对应的必需环境变量
|
||
- MySQL Agent 需要：`MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE`
|
||
- PostgreSQL Agent 需要：`PG_HOST`, `PG_USER`, `PG_PASSWORD`, `PG_DATABASE`
|
||
|
||
3. **tools 参数**：传递的是工具UUID列表（从 `/api/user/tools` 获取）
|
||
- 系统会自动查询工具详情并传递给Agent Manager
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"name": "my-mysql-agent",
|
||
"namespace": "ai-agents",
|
||
"status": "Pending",
|
||
"servicePort": 8080,
|
||
"accessInfo": null,
|
||
"modelInjected": true,
|
||
"quotaRemaining": {
|
||
"cpu": 3.5,
|
||
"memory": 7.0
|
||
}
|
||
},
|
||
"message": "自定义 Agent my-mysql-agent 创建成功"
|
||
}
|
||
```
|
||
|
||
### 3. 修改自定义Agent（扩缩容）
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
PUT /api/user/custom-agents/{name}/scale
|
||
Authorization: Bearer {token}
|
||
Content-Type: application/json
|
||
```
|
||
|
||
#### 请求体
|
||
|
||
```json
|
||
{
|
||
"cpuRequest": "1000m",
|
||
"cpuLimit": "2000m",
|
||
"memoryRequest": "2Gi",
|
||
"memoryLimit": "4Gi"
|
||
}
|
||
```
|
||
|
||
#### 资源单位说明
|
||
|
||
- **CPU**:
|
||
- `1000m` = 1核
|
||
- `500m` = 0.5核
|
||
- `2000m` = 2核
|
||
|
||
- **内存**:
|
||
- `1Gi` = 1GB
|
||
- `2Gi` = 2GB
|
||
- `512Mi` = 0.5GB
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Agent my-custom-agent 扩缩容成功",
|
||
"data": {
|
||
"newCpu": "1000m",
|
||
"newMemory": "2Gi",
|
||
"quotaRemaining": {
|
||
"cpu": 3.5,
|
||
"memory": 8.0
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 停止自定义Agent
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
POST /api/user/custom-agents/{name}/stop
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Agent my-custom-agent 已停止"
|
||
}
|
||
```
|
||
|
||
#### 使用说明
|
||
|
||
- ⚠️ 只有状态为"Running"的Agent可以停止
|
||
- 停止后Agent状态变为"Stopped"
|
||
- 停止的Agent不会释放配额，仍然占用资源
|
||
|
||
### 5. 删除自定义Agent
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
DELETE /api/user/custom-agents/{name}
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "自定义 Agent my-custom-agent 已删除",
|
||
"data": {
|
||
"quotaReleased": {
|
||
"cpu": 1.0,
|
||
"memory": 2.0
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Agent模板管理
|
||
|
||
### 1. 获取创建自定义Agent所需的模板信息
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
GET /api/user/custom-agents/templates
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"frameworkTemplates": ["A2A", "langchain", "MCP"],
|
||
"dataTemplates": [
|
||
{
|
||
"template": "mysql_agent",
|
||
"port": 8080,
|
||
"env_info": {
|
||
"required": {
|
||
"MYSQL_HOST": "MySQL数据库主机地址",
|
||
"MYSQL_USER": "MySQL用户名",
|
||
"MYSQL_PASSWORD": "MySQL密码",
|
||
"MYSQL_DATABASE": "MySQL数据库名"
|
||
},
|
||
"optional": {
|
||
"MYSQL_PORT": "MySQL端口，默认3306"
|
||
}
|
||
},
|
||
"description": "MySQL 数据库 Agent，支持 SQL 查询和数据操作"
|
||
},
|
||
{
|
||
"template": "postgresql_agent",
|
||
"port": 8080,
|
||
"env_info": {
|
||
"required": {
|
||
"PG_HOST": "PostgreSQL数据库主机地址",
|
||
"PG_USER": "PostgreSQL用户名",
|
||
"PG_PASSWORD": "PostgreSQL密码",
|
||
"PG_DATABASE": "PostgreSQL数据库名"
|
||
},
|
||
"optional": {
|
||
"PG_PORT": "PostgreSQL端口，默认5432"
|
||
}
|
||
},
|
||
"description": "PostgreSQL 数据库 Agent，支持 SQL 查询和数据操作"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| frameworkTemplates | array | 框架类型列表（A2A/langchain/MCP），用于 `frameworkTemplate` 参数 |
|
||
| dataTemplates | array | 数据存储模板列表，用于 `template` 参数 |
|
||
| dataTemplates[].template | string | 模板名称（如 mysql_agent） |
|
||
| dataTemplates[].port | number | 服务端口 |
|
||
| dataTemplates[].env_info | object | 环境变量配置说明 |
|
||
| dataTemplates[].env_info.required | object | 必需的环境变量 |
|
||
| dataTemplates[].env_info.optional | object | 可选的环境变量 |
|
||
| dataTemplates[].description | string | 模板描述 |
|
||
|
||
#### 使用说明
|
||
|
||
- **用途**：获取创建自定义Agent所需的两类模板信息
|
||
- **frameworkTemplates**：框架类型，决定Agent的运行框架（传递给 `frameworkTemplate` 参数）
|
||
- **dataTemplates**：数据存储模板，决定Agent镜像类型（传递给 `template` 参数）
|
||
- **业务流程**：
|
||
1. 前端调用此接口获取模板列表
|
||
2. 用户选择**数据存储模板**（如 `mysql_agent`）→ 对应 `template` 参数
|
||
3. 用户选择**框架类型**（如 `MCP`）→ 对应 `frameworkTemplate` 参数
|
||
4. 根据 `env_info.required` 提示用户填写必需的环境变量（如数据库连接信息）
|
||
5. 提交创建请求
|
||
|
||
#### ⚠️ 重要：template 与 frameworkTemplate 的区别
|
||
|
||
| 参数 | 来源 | 说明 | 示例 |
|
||
|-----|------|------|------|
|
||
| `template` | `dataTemplates[].template` | **数据存储模板**，决定Agent镜像 | `mysql_agent`, `postgresql_agent` |
|
||
| `frameworkTemplate` | `frameworkTemplates[]` | **框架类型**，决定运行框架 | `MCP`, `A2A`, `langchain` |
|
||
|
||
---
|
||
|
||
## 模型列表
|
||
|
||
### 1. 获取可用模型
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
GET /api/user/models
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"models": [
|
||
{
|
||
"id": "gpt-4o",
|
||
"name": "GPT-4o",
|
||
"description": "最新的GPT-4优化版本",
|
||
"provider": "openai",
|
||
"contextWindow": 128000
|
||
},
|
||
{
|
||
"id": "gpt-4o-mini",
|
||
"name": "GPT-4o Mini",
|
||
"description": "高性价比的GPT-4轻量版",
|
||
"provider": "openai",
|
||
"contextWindow": 128000
|
||
},
|
||
{
|
||
"id": "claude-3-5-sonnet-20241022",
|
||
"name": "Claude 3.5 Sonnet",
|
||
"description": "Anthropic最新的Claude模型",
|
||
"provider": "anthropic",
|
||
"contextWindow": 200000
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | string | 模型ID（创建Agent时使用） |
|
||
| name | string | 模型显示名称 |
|
||
| description | string | 模型描述 |
|
||
| provider | string | 模型提供商（openai/anthropic/google等） |
|
||
| contextWindow | number | 上下文窗口大小（token数） |
|
||
|
||
#### 使用说明
|
||
|
||
- **用途**：在创建Agent时选择使用的模型
|
||
- **权限控制**：根据用户的订阅级别返回可用模型列表
|
||
- **模型ID**：创建Agent时使用`id`字段作为模型参数
|
||
|
||
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
### 错误响应格式
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "error_code",
|
||
"message": "用户友好的错误信息",
|
||
"detail": {
|
||
"field": "具体字段",
|
||
"reason": "详细原因"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 常见错误码
|
||
|
||
| HTTP状态码 | error字段 | 说明 |
|
||
|-----------|-----------|------|
|
||
| 400 | `invalid_request` | 请求参数错误 |
|
||
| 400 | `quota_exceeded` | 配额不足 |
|
||
| 401 | `unauthorized` | 未授权 |
|
||
| 403 | `forbidden` | 无权限 |
|
||
| 404 | `not_found` | 资源不存在 |
|
||
| 409 | `conflict` | 资源冲突（如名称重复） |
|
||
| 500 | `internal_error` | 服务器内部错误 |
|
||
| 503 | `service_unavailable` | 服务不可用 |
|
||
|
||
### 配额不足错误详情
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "quota_exceeded",
|
||
"message": "CPU配额不足。剩余: 0.5核，请求: 1.0核",
|
||
"detail": {
|
||
"resource": "cpu",
|
||
"available": 0.5,
|
||
"requested": 1.0,
|
||
"quota": 4.0,
|
||
"used": 3.5
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 完整业务流程
|
||
|
||
### 流程1：创建和部署Agent
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[开始] --> B[点击"部署Agent"按钮]
|
||
B --> C[选择框架模板]
|
||
C --> D[填写Agent名称和描述]
|
||
D --> E[选择服务网关]
|
||
E --> F[选择已注册的工具]
|
||
F --> G[配置Pod资源]
|
||
G --> H[提交部署]
|
||
H --> I{检查配额}
|
||
I -->|不足| J[显示配额不足错误]
|
||
I -->|充足| K[创建Agent]
|
||
K --> L[Agent自动部署]
|
||
L --> M[状态变为Running]
|
||
M --> N[完成]
|
||
```
|
||
|
||
---
|
||
|
||
## 联系支持
|
||
|
||
如有问题或需要帮助，请联系：
|
||
- 技术支持：support@example.com
|
||
- 文档反馈：docs@example.com
|
||
|
||
---
|
||
|
||
**文档结束**
|