taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity
Files
cd4dea8a0d288a85f88556f0bdffa93047ca34be
taiji-AI-PAD/Docs/项目文档/数据与工具-前端对接文档(完整版).md
T

17 KiB
Raw Blame History

数据与工具模块 - 前端对接文档（完整版）

版本: v2.0.0
更新时间: 2026-01-11
后端服务: mcp-server
接口验证状态: ✅ 已验证

📋 目录

  1. 功能概述
  2. 核心概念说明
  3. 接口完整清单
  4. 工具统计数据
  5. 工具注册表管理
  6. 自定义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模板，由系统管理员预先配置好，用户可直接使用
Agent框架模板 Framework Template Agent的框架类型（MCP/A2A/langchain），传递给Agent Manager进行部署
服务网关 Gateway Agent使用的通信网关类型（MCP/A2A/API）

自定义Agent vs 平台Agent

特性 自定义Agent 平台Agent
创建方式 用户自己创建配置 系统管理员预置
工具选择 用户选择需要的工具 预先配置好的工具
资源配置 用户自定义CPU/内存 使用平台配置
配额管理 自定义Agent配额 平台Agent配额
使用场景 个性化需求，灵活配置 标准化功能，开箱即用
接口前缀 /api/user/custom-agents /api/user/agents/platform

自定义Agent创建流程

1. （可选）创建工具（Tools）- 显示在工具注册表中
   ↓
2. 点击"创建自定义Agent"
   ↓
3. 填写基本信息（名称、描述、模板）
   ↓
4. 选择框架模板（MCP/A2A/langchain）
   ↓
5. （可选）选择已注册的工具
   ↓
6. 配置资源（CPU、内存）
   ↓
7. （可选）配置环境变量、API Key等
   ↓
8. 提交创建
   ↓
9. **自动调用Agent Manager部署到K8s集群**
   ↓
10. Pod启动，Agent状态变为Running
   ↓
11. 可以使用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：

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框架模板列表（传递给Agent Manager）
模型列表 GET /api/user/models 获取当前用户可使用的模型列表

工具统计数据

接口说明

首行统计卡片的数据来源于工具统计接口，用于展示工具的创建和使用情况。

请求示例

GET /api/user/tools/stats
Authorization: Bearer {token}

响应示例

{
  "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信息。

请求示例

GET /api/user/custom-agents
Authorization: Bearer {token}

响应示例

{
  "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. 获取工具列表

接口

GET /api/user/tools
Authorization: Bearer {token}

响应示例

{
  "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. 创建工具

接口

POST /api/user/tools/create
Authorization: Bearer {token}
Content-Type: application/json

请求体

{
  "name": "weather-query-tool",
  "description": "查询天气信息的工具",
  "type": "api",
  "config": {
    "endpoint": "https://api.weather.com/v1/forecast",
    "method": "GET",
    "apiKey": "your-api-key"
  }
}

响应示例

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

请求体

{
  "description": "更新后的工具描述",
  "config": {
    "endpoint": "https://api.weather.com/v2/forecast",
    "method": "GET",
    "apiKey": "new-api-key"
  }
}

响应示例

{
  "success": true,
  "message": "工具更新成功",
  "data": {
    "id": "tool-550e8400-e29b-41d4-a716-446655440000",
    "name": "weather-query-tool",
    "updated_at": "2026-01-11T10:30:00Z"
  }
}

4. 删除工具

接口

DELETE /api/user/tools/{tool_id}
Authorization: Bearer {token}

响应示例

{
  "success": true,
  "message": "工具已删除"
}

自定义Agent管理

1. 获取自定义Agent列表

接口

GET /api/user/custom-agents
Authorization: Bearer {token}

响应示例

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

接口

POST /api/user/custom-agents
Authorization: Bearer {token}
Content-Type: application/json

说明

本接口会实际调用Agent Manager服务，将自定义Agent部署到K8s集群。

创建后Agent会立即启动，用户可以直接使用。

请求体示例

{
  "name": "my-custom-agent",
  "template": "python-agent",
  "frameworkTemplate": "MCP",
  "description": "我的自定义Agent",
  "cpuRequest": "500m",
  "cpuLimit": "1000m",
  "memoryRequest": "1Gi",
  "memoryLimit": "2Gi",
  "tools": ["tool-id-1", "tool-id-2"],
  "envConfig": {
    "CUSTOM_VAR": "value"
  }
}

请求字段说明

字段 类型 必填 说明
name string 是 Agent名称（小写字母、数字、连字符）
template string 是 模板名称
frameworkTemplate string 否 框架类型（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列表
endpoint string 否 自定义终结点
apiKey string 否 API密钥
envConfig object 否 环境变量配置

响应示例

{
  "success": true,
  "data": {
    "name": "my-custom-agent",
    "status": "deploying",
    "podName": "my-custom-agent-7d8f9b-abc123"
  },
  "message": "自定义Agent创建成功，正在部署"
}

3. 修改自定义Agent（扩缩容）

接口

PUT /api/user/custom-agents/{name}/scale
Authorization: Bearer {token}
Content-Type: application/json

请求体

{
  "cpuRequest": "1000m",
  "cpuLimit": "2000m",
  "memoryRequest": "2Gi",
  "memoryLimit": "4Gi"
}

资源单位说明

  • CPU:

    • 1000m = 1核
    • 500m = 0.5核
    • 2000m = 2核

  • 内存:

    • 1Gi = 1GB
    • 2Gi = 2GB
    • 512Mi = 0.5GB

响应示例

{
  "success": true,
  "message": "Agent my-custom-agent 扩缩容成功",
  "data": {
    "newCpu": "1000m",
    "newMemory": "2Gi",
    "quotaRemaining": {
      "cpu": 3.5,
      "memory": 8.0
    }
  }
}

4. 停止自定义Agent

接口

POST /api/user/custom-agents/{name}/stop
Authorization: Bearer {token}

响应示例

{
  "success": true,
  "message": "Agent my-custom-agent 已停止"
}

使用说明

  • ⚠️ 只有状态为"Running"的Agent可以停止
  • 停止后Agent状态变为"Stopped"
  • 停止的Agent不会释放配额，仍然占用资源

5. 删除自定义Agent

接口

DELETE /api/user/custom-agents/{name}
Authorization: Bearer {token}

响应示例

{
  "success": true,
  "message": "自定义 Agent my-custom-agent 已删除",
  "data": {
    "quotaReleased": {
      "cpu": 1.0,
      "memory": 2.0
    }
  }
}

Agent框架模板管理

1. 获取可用框架模板

接口

GET /api/user/custom-agents/templates
Authorization: Bearer {token}

响应示例

{
  "success": true,
  "data": {
    "templates": [
      "A2A",
      "langchain",
      "MCP"
    ]
  }
}

使用说明

  • 用途：用于Agent框架模板选择，传递给AKS启动对应的Agent
  • 与工具注册表的关系：与工具注册表及数据模板无关，仅用于Agent框架类型
  • 可用框架：A2A、langchain、MCP
  • 业务流程：
    1. 前端获取框架列表
    2. 用户创建Agent时选择框架类型
    3. 前端传递给mcp-server
    4. mcp-server转发给Agent Manager服务进行部署

模型列表

1. 获取可用模型

接口

GET /api/user/models
Authorization: Bearer {token}

响应示例

{
  "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字段作为模型参数

错误处理

错误响应格式

{
  "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 服务不可用

配额不足错误详情

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

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[完成]

联系支持

如有问题或需要帮助，请联系：

文档结束

View Git Blame Copy Permalink