# 租户用户端 - 代理工厂对接文档 > **版本**: 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 个 ---