Files
taiji-AI-PAD/Docs/项目文档/数据工具与自定义Agent-前端接口文档.md
T

659 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 数据工具与自定义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 表删除 |
---
**如有问题,请联系大智开发团队。**