forked from xiaohei/taiji-AI-PAD
529 lines
13 KiB
Markdown
529 lines
13 KiB
Markdown
# 租户用户端 - 代理工厂对接文档
|
||
|
||
> **版本**: v1.0.0
|
||
> **更新时间**: 2026-01-09
|
||
> **说明**: 本文档针对代理工厂模块的前后端对接规范
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [功能概述](#功能概述)
|
||
2. [业务逻辑说明](#业务逻辑说明)
|
||
3. [接口清单](#接口清单)
|
||
4. [接口详细说明](#接口详细说明)
|
||
5. [前端实现指引](#前端实现指引)
|
||
6. [错误处理](#错误处理)
|
||
|
||
---
|
||
|
||
## 功能概述
|
||
|
||
代理工厂模块是租户用户管理和部署Agent的核心功能，包含以下能力：
|
||
|
||
- **查看可用Agent类型**：展示渠道分配给租户的所有Agent模板
|
||
- **部署Agent**：手动部署平台原生Agent，配置实例数、模型、网关等参数
|
||
- **管理已部署Agent**：查看、启动、停止、删除已运行的Agent实例
|
||
- **资源监控**：实时查看CPU、内存使用情况及配额剩余
|
||
|
||
---
|
||
|
||
## 业务逻辑说明
|
||
|
||
### 1. 可用Agent类型
|
||
|
||
**定义**：可用Agent类型指的是**渠道已分配给该租户的平台Agent模板**。
|
||
|
||
- 数据来源：`platform_agent_quota`表，记录了分配给租户的Agent模板及其配额
|
||
- 展示内容：模板名称、描述、配额总数、已使用数量、剩余配额
|
||
|
||
### 2. 已部署的Agent
|
||
|
||
**定义**：已部署的Agent指的是**当前用户下已经运行起来的Agent实例**。
|
||
|
||
- 包括平台Agent实例和自定义Agent实例
|
||
- 状态包括：Running（运行中）、Pending（启动中）、Failed（失败）、Stopped（已停止）
|
||
|
||
### 3. 资源统计
|
||
|
||
**总CPU和内存数**：当前租户所有已运行Agent实例的资源总和，包括副本使用的资源。
|
||
|
||
计算规则：
|
||
```
|
||
总CPU = Σ(每个Agent实例的CPU请求量 × 副本数)
|
||
总内存 = Σ(每个Agent实例的内存请求量 × 副本数)
|
||
```
|
||
|
||
### 4. 平台原生Agent库
|
||
|
||
**定义**：平台原生Agent库指的是**已分配给该租户的Agent模板列表**。
|
||
|
||
- 来源：由渠道管理员或超级管理员分配
|
||
- 用户只能部署已分配的Agent模板
|
||
- 受配额限制（Pod数量限制）
|
||
|
||
---
|
||
|
||
## 接口清单
|
||
|
||
| 序号 | 接口路径 | 方法 | 说明 | 用途 |
|
||
|------|----------|------|------|------|
|
||
| 1 | `/api/user/platform-agents/available` | GET | 获取可用平台Agent列表 | 展示可部署的Agent类型 |
|
||
| 2 | `/api/user/platform-agents/quota` | GET | 查看配额使用情况 | 展示配额和使用统计 |
|
||
| 3 | `/api/user/agents/deploy` | POST | 部署Agent | 手动部署Agent实例 |
|
||
| 4 | `/api/user/platform-agents/instances` | GET | 获取Agent实例列表 | 查看已部署的Agent |
|
||
| 5 | `/api/user/platform-agents/use` | POST | 启动平台Agent | 启动/使用Agent实例 |
|
||
| 6 | `/api/user/platform-agents/{instance_name}` | DELETE | 停止Agent实例 | 停止正在运行的Agent |
|
||
| 7 | `/api/user/custom-agent-quota` | GET | 获取自定义Agent配额 | 查看CPU/内存配额（扩展用） |
|
||
|
||
---
|
||
|
||
## 接口详细说明
|
||
|
||
### 1. 获取可用平台Agent列表
|
||
|
||
**接口**: `GET /api/user/platform-agents/available`
|
||
|
||
**功能说明**：
|
||
- 返回渠道分配给该租户的所有平台Agent模板
|
||
- 包含每个模板的配额信息（总数、已用、剩余）
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"agents": [
|
||
{
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"templateName": "code-assistant",
|
||
"displayName": "代码助手",
|
||
"description": "AI代码辅助工具",
|
||
"podQuota": 5,
|
||
"podUsed": 2,
|
||
"podRemaining": 3,
|
||
"cpuLimit": "500m",
|
||
"memoryLimit": "512Mi",
|
||
"category": "platform",
|
||
"allocatedAt": "2026-01-08T00:00:00Z"
|
||
},
|
||
{
|
||
"id": "660e8400-e29b-41d4-a716-446655440001",
|
||
"templateName": "data-analyzer",
|
||
"displayName": "数据分析助手",
|
||
"description": "数据处理和分析工具",
|
||
"podQuota": 3,
|
||
"podUsed": 1,
|
||
"podRemaining": 2,
|
||
"cpuLimit": "200m",
|
||
"memoryLimit": "256Mi",
|
||
"category": "platform",
|
||
"allocatedAt": "2026-01-08T00:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**前端使用**：
|
||
- 用于展示"平台原生Agent库"列表
|
||
- 显示每个Agent的配额使用情况（进度条）
|
||
- 当`podRemaining = 0`时，禁用部署按钮
|
||
|
||
---
|
||
|
||
### 2. 查看平台Agent配额使用情况
|
||
|
||
**接口**: `GET /api/user/platform-agents/quota`
|
||
|
||
**功能说明**：
|
||
- 返回当前租户的平台Agent配额汇总信息
|
||
- 按模板分组显示使用情况
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"userId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"quotas": [
|
||
{
|
||
"templateName": "code-assistant",
|
||
"displayName": "代码助手",
|
||
"podQuota": 5,
|
||
"podUsed": 2,
|
||
"podRemaining": 3,
|
||
"usagePercent": 40.0
|
||
},
|
||
{
|
||
"templateName": "data-analyzer",
|
||
"displayName": "数据分析助手",
|
||
"podQuota": 3,
|
||
"podUsed": 1,
|
||
"podRemaining": 2,
|
||
"usagePercent": 33.33
|
||
}
|
||
],
|
||
"totalQuota": 8,
|
||
"totalUsed": 3
|
||
}
|
||
```
|
||
|
||
**前端使用**：
|
||
- 用于页面顶部展示配额汇总信息
|
||
- 显示总配额使用情况的环形图或进度条
|
||
- 按模板展示详细的配额使用百分比
|
||
|
||
---
|
||
|
||
### 3. 部署Agent（手动部署）
|
||
|
||
**接口**: `POST /api/user/agents/deploy`
|
||
|
||
**功能说明**：
|
||
- 租户手动部署平台Agent实例
|
||
- 需要选择Agent类型、配置实例数、模型、网关
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| agentId | string | 是 | Agent模板ID（从可用列表获取） | "550e8400-e29b-41d4-a716-446655440000" |
|
||
| instances | integer | 是 | 实例数量（副本数） | 2 |
|
||
| model | string | 是 | 使用的模型名称 | "gpt-4" |
|
||
| gateway | string | 是 | 服务网关类型（不区分大小写） | "MCP" / "A2A" / "API" |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"agentId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"instances": 2,
|
||
"model": "gpt-4",
|
||
"gateway": "MCP"
|
||
}
|
||
```
|
||
|
||
**响应示例（成功）**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"agentId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"podName": "code-assistant-550e8400",
|
||
"namespace": "default",
|
||
"status": "Running",
|
||
"servicePort": 8080,
|
||
"instances": 2,
|
||
"model": "gpt-4",
|
||
"gateway": "MCP"
|
||
},
|
||
"message": "Agent code-assistant 部署成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"detail": "Agent不存在或无权访问"
|
||
}
|
||
```
|
||
|
||
或
|
||
|
||
```json
|
||
{
|
||
"detail": "Pod配额已用完，无法创建新的Agent实例"
|
||
}
|
||
```
|
||
|
||
**前端使用**：
|
||
1. 点击"部署"按钮，弹出部署配置表单
|
||
2. 表单包含字段：
|
||
- Agent选择（下拉框，数据来自"可用列表"）
|
||
- 实例数量（数字输入框，默认1）
|
||
- 模型选择（下拉框，可从`/api/user/models/available`获取）
|
||
- 网关类型（单选：MCP / A2A / API）
|
||
3. 提交前验证：
|
||
- 检查配额是否充足（`podRemaining >= instances`）
|
||
- 所有必填字段已填写
|
||
4. 部署成功后，刷新实例列表
|
||
|
||
---
|
||
|
||
### 4. 获取已部署的Agent实例列表
|
||
|
||
**接口**: `GET /api/user/platform-agents/instances`
|
||
|
||
**功能说明**：
|
||
- 返回当前用户所有正在运行/已停止的平台Agent实例
|
||
- 包含实例状态、资源使用、运行时间等信息
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"instances": [
|
||
{
|
||
"instanceName": "code-assistant-550e8400-abc123",
|
||
"templateName": "code-assistant",
|
||
"displayName": "代码助手",
|
||
"namespace": "default",
|
||
"status": "Running",
|
||
"servicePort": 8080,
|
||
"createdAt": "2026-01-08T10:00:00Z",
|
||
"model": "gpt-4",
|
||
"gateway": "MCP",
|
||
"replicas": 2,
|
||
"cpuUsage": "500m",
|
||
"memoryUsage": "1024Mi"
|
||
},
|
||
{
|
||
"instanceName": "data-analyzer-660e8400-def456",
|
||
"templateName": "data-analyzer",
|
||
"displayName": "数据分析助手",
|
||
"namespace": "default",
|
||
"status": "Pending",
|
||
"servicePort": 8080,
|
||
"createdAt": "2026-01-09T09:00:00Z",
|
||
"model": "claude-3",
|
||
"gateway": "A2A",
|
||
"replicas": 1,
|
||
"cpuUsage": "0m",
|
||
"memoryUsage": "0Mi"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态说明**:
|
||
|
||
| 状态值 | 说明 | 前端展示 | 可用操作 |
|
||
|--------|------|----------|----------|
|
||
| Running | 运行中 | 绿色标签 | 停止、查看日志 |
|
||
| Pending | 启动中 | 黄色标签 | 等待 |
|
||
| Failed | 失败 | 红色标签 | 重启、删除 |
|
||
| Stopped | 已停止 | 灰色标签 | 启动、删除 |
|
||
|
||
**前端使用**：
|
||
- 用于展示"已部署的Agent"列表
|
||
- 表格列：Agent名称、状态、副本数、CPU、内存、模型、网关、创建时间、操作
|
||
- 操作按钮：停止、启动、删除（根据状态显示不同按钮）
|
||
- 实时刷新状态（轮询或WebSocket）
|
||
|
||
---
|
||
|
||
### 5. 启动平台Agent实例
|
||
|
||
**接口**: `POST /api/user/platform-agents/use`
|
||
|
||
**功能说明**：
|
||
- 启动一个已停止的Agent实例
|
||
- 或创建一个新的Agent实例（如果该模板有剩余配额）
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| agentType | string | 是 | Agent模板名称（如"code-assistant"） |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"agentType": "code-assistant"
|
||
}
|
||
```
|
||
|
||
**响应示例（成功）**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"instanceName": "code-assistant-550e8400-abc123",
|
||
"namespace": "default",
|
||
"status": "Running",
|
||
"servicePort": 8080,
|
||
"accessInfo": {
|
||
"endpoints": {
|
||
"mcp": "http://code-assistant-550e8400-abc123.default.svc.cluster.local:8080"
|
||
}
|
||
},
|
||
"quotaRemaining": 2
|
||
},
|
||
"message": "平台 Agent code-assistant 启动成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"detail": "Pod配额已用完，无法创建新的Agent实例"
|
||
}
|
||
```
|
||
|
||
或
|
||
|
||
```json
|
||
{
|
||
"detail": "您没有使用该Agent的权限"
|
||
}
|
||
```
|
||
|
||
**前端使用**：
|
||
- 用于"启动"按钮的操作
|
||
- 仅当Agent状态为Stopped时显示
|
||
- 启动成功后刷新列表
|
||
|
||
---
|
||
|
||
### 6. 停止Agent实例
|
||
|
||
**接口**: `DELETE /api/user/platform-agents/{instance_name}`
|
||
|
||
**功能说明**：
|
||
- 停止正在运行的Agent实例
|
||
- 释放配额（`podUsed`减1）
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| instance_name | string | Agent实例名称（如"code-assistant-550e8400-abc123"） |
|
||
|
||
**响应示例（成功）**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Agent 实例 code-assistant-550e8400-abc123 已停止"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"detail": "未找到该Agent实例"
|
||
}
|
||
```
|
||
|
||
或
|
||
|
||
```json
|
||
{
|
||
"detail": "无权操作该Agent实例"
|
||
}
|
||
```
|
||
|
||
**前端使用**：
|
||
- 用于"停止"按钮的操作
|
||
- 仅当Agent状态为Running时显示
|
||
- 需要二次确认："确定要停止该Agent吗？"
|
||
- 停止成功后刷新列表
|
||
|
||
---
|
||
|
||
### 7. 获取平台Agent资源使用统计
|
||
|
||
**接口**: `GET /api/user/custom-agent-quota`
|
||
|
||
**功能说明**：
|
||
- 返回租户当前所有正在运行的平台Agent的CPU和内存总使用量
|
||
- 用于展示总资源使用情况
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"totalCpu": 1.5,
|
||
"totalMemory": 3.0,
|
||
"agentCount": 3,
|
||
"agents": [
|
||
{
|
||
"agentName": "code-assistant-550e8400-abc123",
|
||
"agentType": "platform",
|
||
"templateName": "code-assistant",
|
||
"cpuPerPod": 0.5,
|
||
"memoryPerPod": 1.0,
|
||
"replicas": 2,
|
||
"totalCpu": 1.0,
|
||
"totalMemory": 2.0,
|
||
"startTime": "2026-01-08T10:00:00"
|
||
},
|
||
{
|
||
"agentName": "data-analyzer-660e8400-def456",
|
||
"agentType": "platform",
|
||
"templateName": "data-analyzer",
|
||
"cpuPerPod": 0.5,
|
||
"memoryPerPod": 1.0,
|
||
"replicas": 1,
|
||
"totalCpu": 0.5,
|
||
"totalMemory": 1.0,
|
||
"startTime": "2026-01-09T09:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应字段说明**:
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| totalCpu | float | 所有运行中Agent的总CPU使用量（核心数） |
|
||
| totalMemory | float | 所有运行中Agent的总内存使用量（GB） |
|
||
| agentCount | integer | 正在运行的Agent实例总数（包括副本） |
|
||
| agents | array | 每个Agent的详细信息 |
|
||
| agents[].agentName | string | Agent实例名称 |
|
||
| agents[].agentType | string | Agent类型（platform） |
|
||
| agents[].templateName | string | Agent模板名称 |
|
||
| agents[].cpuPerPod | float | 单个Pod的CPU使用量（核心数） |
|
||
| agents[].memoryPerPod | float | 单个Pod的内存使用量（GB） |
|
||
| agents[].replicas | integer | 副本数量 |
|
||
| agents[].totalCpu | float | 该Agent总CPU（cpuPerPod × replicas） |
|
||
| agents[].totalMemory | float | 该Agent总内存（memoryPerPod × replicas） |
|
||
| agents[].startTime | string | 启动时间（ISO格式） |
|
||
|
||
**前端使用**：
|
||
- 用于页面顶部展示总资源统计
|
||
- 显示当前运行中Agent的CPU和内存总使用量
|
||
- 格式：
|
||
- 总CPU: 1.5 核
|
||
- 总内存: 3.0 GB
|
||
- 运行中Agent数: 3 个
|
||
|
||
---
|