taijibaga/taiji-AI-PAD

Fork 0

forked from xiaohei/taiji-AI-PAD

Files

T

zhanggangyong cd4dea8a0d 更新agent manager数据接口

2026-01-12 13:52:38 +00:00

13 KiB

Raw Blame History

租户用户端 - 代理工厂对接文档

版本: v1.0.0
更新时间: 2026-01-09
说明: 本文档针对代理工厂模块的前后端对接规范

功能概述

代理工厂模块是租户用户管理和部署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}

响应示例:

{
  "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}

响应示例:

{
  "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"

请求示例:

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "instances": 2,
  "model": "gpt-4",
  "gateway": "MCP"
}

响应示例（成功）:

{
  "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 部署成功"
}

错误响应:

{
  "detail": "Agent不存在或无权访问"
}

或

{
  "detail": "Pod配额已用完，无法创建新的Agent实例"
}

前端使用：

点击"部署"按钮，弹出部署配置表单
表单包含字段：
- Agent选择（下拉框，数据来自"可用列表"）
- 实例数量（数字输入框，默认1）
- 模型选择（下拉框，可从/api/user/models/available获取）
- 网关类型（单选：MCP / A2A / API）
提交前验证：
- 检查配额是否充足（podRemaining >= instances）
- 所有必填字段已填写
部署成功后，刷新实例列表

4. 获取已部署的Agent实例列表

接口: GET /api/user/platform-agents/instances

功能说明：

返回当前用户所有正在运行/已停止的平台Agent实例
包含实例状态、资源使用、运行时间等信息

请求头:

Authorization: Bearer {token}

响应示例:

{
  "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"）

请求示例:

{
  "agentType": "code-assistant"
}

响应示例（成功）:

{
  "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 启动成功"
}

错误响应:

{
  "detail": "Pod配额已用完，无法创建新的Agent实例"
}

或

{
  "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"）

响应示例（成功）:

{
  "success": true,
  "message": "Agent 实例 code-assistant-550e8400-abc123 已停止"
}

错误响应:

{
  "detail": "未找到该Agent实例"
}

或

{
  "detail": "无权操作该Agent实例"
}

前端使用：

用于"停止"按钮的操作
仅当Agent状态为Running时显示
需要二次确认："确定要停止该Agent吗？"
停止成功后刷新列表

7. 获取平台Agent资源使用统计

接口: GET /api/user/custom-agent-quota

功能说明：

返回租户当前所有正在运行的平台Agent的CPU和内存总使用量
用于展示总资源使用情况

请求头:

Authorization: Bearer {token}

响应示例:

{
  "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 个

13 KiB Raw Blame History Unescape Escape

租户用户端 - 代理工厂对接文档

目录

功能概述

业务逻辑说明

1. 可用Agent类型

2. 已部署的Agent

3. 资源统计

4. 平台原生Agent库

接口清单

接口详细说明

1. 获取可用平台Agent列表

2. 查看平台Agent配额使用情况

3. 部署Agent（手动部署）

4. 获取已部署的Agent实例列表

5. 启动平台Agent实例

6. 停止Agent实例

7. 获取平台Agent资源使用统计

13 KiB

Raw Blame History