# 数据与工具模块 - 前端对接文档(完整版) > **版本**: v2.1.0 > **更新时间**: 2026-01-13 > **后端服务**: mcp-server > **接口验证状态**: ✅ 已验证 > **重要更新**: 模板接口返回格式变更,区分数据存储模板和框架类型 --- ## 📋 目录 1. [功能概述](#功能概述) 2. [核心概念说明](#核心概念说明) 3. [接口完整清单](#接口完整清单) 4. [工具统计数据](#工具统计数据) 5. [工具注册表管理](#工具注册表管理) 6. [自定义Agent部署](#自定义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模板**,由系统管理员预先配置好,用户可直接使用 | | **数据存储模板** | Data Template | **决定Agent镜像类型**(如 mysql_agent、postgresql_agent),对应 `template` 参数 | | **框架类型** | Framework Template | **决定Agent运行框架**(MCP/A2A/langchain),对应 `frameworkTemplate` 参数 | | **服务网关** | Gateway | Agent使用的通信网关类型(MCP/A2A/API) | ### ⚠️ 重要概念区分 创建自定义Agent时需要区分两个关键参数: | 参数名 | 含义 | 来源 | 示例值 | |-------|------|------|--------| | `template` | 数据存储模板 | `dataTemplates[].template` | `mysql_agent`, `postgresql_agent` | | `frameworkTemplate` | 框架类型 | `frameworkTemplates[]` | `MCP`, `A2A`, `langchain` | **常见错误**:将框架类型(如 `a2a-agent`)误传给 `template` 参数,导致 Agent Manager 返回"无效的模板名称"错误。 ### 自定义Agent vs 平台Agent | 特性 | 自定义Agent | 平台Agent | |------|-----------|----------| | **创建方式** | 用户自己创建配置 | 系统管理员预置 | | **工具选择** | 用户选择需要的工具 | 预先配置好的工具 | | **资源配置** | 用户自定义CPU/内存 | 使用平台配置 | | **配额管理** | 自定义Agent配额 | 平台Agent配额 | | **使用场景** | 个性化需求,灵活配置 | 标准化功能,开箱即用 | | **接口前缀** | `/api/user/custom-agents` | `/api/user/agents/platform` | ### 自定义Agent创建流程 ``` 1. 调用 GET /api/user/custom-agents/templates 获取模板信息 ├── frameworkTemplates: 框架类型列表 └── dataTemplates: 数据存储模板列表(含环境变量要求) ↓ 2. (可选)调用 GET /api/user/tools 获取已创建的工具列表 ↓ 3. 点击"创建自定义Agent" ↓ 4. 选择数据存储模板(如 mysql_agent)→ 对应 template 参数 ↓ 5. 选择框架类型(MCP/A2A/langchain)→ 对应 frameworkTemplate 参数 ↓ 6. 填写基本信息(名称、描述) ↓ 7. 根据 env_info.required 填写必需环境变量(如数据库连接信息) ↓ 8. (可选)选择已注册的工具 → 对应 tools 参数(工具UUID列表) ↓ 9. (可选)选择模型 → 对应 model 参数,会自动注入LiteLLM配置 ↓ 10. 配置资源(CPU、内存) ↓ 11. 提交创建 POST /api/user/custom-agents ↓ 12. **自动调用Agent Manager部署到K8s集群** ↓ 13. Pod启动,Agent状态变为Running ↓ 14. 可以使用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: ```http 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所需的模板信息(含数据存储模板和框架类型) | | **模型列表** | GET | `/api/user/models` | 获取当前用户可使用的模型列表 | --- ## 工具统计数据 ### 接口说明 首行统计卡片的数据来源于工具统计接口,用于展示工具的创建和使用情况。 ### 请求示例 ```http GET /api/user/tools/stats Authorization: Bearer {token} ``` ### 响应示例 ```json { "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信息。 ### 请求示例 ```http GET /api/user/custom-agents Authorization: Bearer {token} ``` ### 响应示例 ```json { "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. 获取工具列表 #### 接口 ```http GET /api/user/tools Authorization: Bearer {token} ``` #### 响应示例 ```json { "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. 创建工具 #### 接口 ```http POST /api/user/tools/create Authorization: Bearer {token} Content-Type: application/json ``` #### 请求体 ```json { "name": "weather-query-tool", "description": "查询天气信息的工具", "type": "api", "config": { "endpoint": "https://api.weather.com/v1/forecast", "method": "GET", "apiKey": "your-api-key" } } ``` #### 响应示例 ```json { "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 ``` #### 请求体 ```json { "description": "更新后的工具描述", "config": { "endpoint": "https://api.weather.com/v2/forecast", "method": "GET", "apiKey": "new-api-key" } } ``` #### 响应示例 ```json { "success": true, "message": "工具更新成功", "data": { "id": "tool-550e8400-e29b-41d4-a716-446655440000", "name": "weather-query-tool", "updated_at": "2026-01-11T10:30:00Z" } } ``` ### 4. 删除工具 #### 接口 ```http DELETE /api/user/tools/{tool_id} Authorization: Bearer {token} ``` #### 响应示例 ```json { "success": true, "message": "工具已删除" } ``` --- ## 自定义Agent管理 ### 1. 获取自定义Agent列表 #### 接口 ```http GET /api/user/custom-agents Authorization: Bearer {token} ``` #### 响应示例 ```json { "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) #### 接口 ```http POST /api/user/custom-agents Authorization: Bearer {token} Content-Type: application/json ``` #### 说明 **本接口会实际调用Agent Manager服务,将自定义Agent部署到K8s集群。** 创建后Agent会立即启动,用户可以直接使用。 #### 请求体示例 **示例1:创建 MySQL Agent (MCP框架)** ```json { "name": "my-mysql-agent", "template": "mysql_agent", "frameworkTemplate": "MCP", "description": "我的MySQL数据库Agent", "cpuRequest": "500m", "cpuLimit": "1000m", "memoryRequest": "1Gi", "memoryLimit": "2Gi", "tools": ["tool-uuid-1", "tool-uuid-2"], "model": "gpt-4", "envConfig": { "MYSQL_HOST": "mysql.example.com", "MYSQL_USER": "root", "MYSQL_PASSWORD": "password123", "MYSQL_DATABASE": "mydb" } } ``` **示例2:创建 PostgreSQL Agent (A2A框架)** ```json { "name": "my-pgsql-agent", "template": "postgresql_agent", "frameworkTemplate": "A2A", "description": "我的PostgreSQL数据库Agent", "cpuRequest": "1000m", "memoryRequest": "1Gi", "tools": ["tool-uuid-1"], "model": "gpt-4", "agentRole": "data_analyzer", "agentCapabilities": ["sql_query", "data_analysis"], "envConfig": { "PG_HOST": "postgres.example.com", "PG_USER": "postgres", "PG_PASSWORD": "password123", "PG_DATABASE": "mydb" } } ``` #### 请求字段说明 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | ✅ | Agent名称(小写字母、数字、连字符) | | template | string | ✅ | **数据存储模板名称**(从 `dataTemplates` 获取,如 `mysql_agent`、`postgresql_agent`) | | frameworkTemplate | string | 否 | **框架类型**(从 `frameworkTemplates` 获取: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列表(从 `/api/user/tools` 获取的工具UUID) | | model | string | 否 | 使用的模型名称(如 `gpt-4`),会自动注入LiteLLM环境变量 | | endpoint | string | 否 | 自定义终结点 | | apiKey | string | 否 | API密钥 | | envConfig | object | 否 | 环境变量配置(数据库连接信息等,参考 `env_info.required`) | | agentRole | string | 否 | A2A框架专用:Agent角色(如 `data_analyzer`) | | agentCapabilities | array | 否 | A2A框架专用:Agent能力列表(如 `["sql_query", "data_analysis"]`) | #### ⚠️ 重要提醒 1. **template 参数**:必须使用 `/api/user/custom-agents/templates` 返回的 `dataTemplates[].template` 值 - ✅ 正确:`"template": "mysql_agent"` - ❌ 错误:`"template": "a2a-agent"` (这不是有效的数据存储模板) 2. **envConfig 参数**:根据选择的 template,需要填写对应的必需环境变量 - MySQL Agent 需要:`MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE` - PostgreSQL Agent 需要:`PG_HOST`, `PG_USER`, `PG_PASSWORD`, `PG_DATABASE` 3. **tools 参数**:传递的是工具UUID列表(从 `/api/user/tools` 获取) - 系统会自动查询工具详情并传递给Agent Manager #### 响应示例 ```json { "success": true, "data": { "name": "my-mysql-agent", "namespace": "ai-agents", "status": "Pending", "servicePort": 8080, "accessInfo": null, "modelInjected": true, "quotaRemaining": { "cpu": 3.5, "memory": 7.0 } }, "message": "自定义 Agent my-mysql-agent 创建成功" } ``` ### 3. 修改自定义Agent(扩缩容) #### 接口 ```http PUT /api/user/custom-agents/{name}/scale Authorization: Bearer {token} Content-Type: application/json ``` #### 请求体 ```json { "cpuRequest": "1000m", "cpuLimit": "2000m", "memoryRequest": "2Gi", "memoryLimit": "4Gi" } ``` #### 资源单位说明 - **CPU**: - `1000m` = 1核 - `500m` = 0.5核 - `2000m` = 2核 - **内存**: - `1Gi` = 1GB - `2Gi` = 2GB - `512Mi` = 0.5GB #### 响应示例 ```json { "success": true, "message": "Agent my-custom-agent 扩缩容成功", "data": { "newCpu": "1000m", "newMemory": "2Gi", "quotaRemaining": { "cpu": 3.5, "memory": 8.0 } } } ``` ### 4. 停止自定义Agent #### 接口 ```http POST /api/user/custom-agents/{name}/stop Authorization: Bearer {token} ``` #### 响应示例 ```json { "success": true, "message": "Agent my-custom-agent 已停止" } ``` #### 使用说明 - ⚠️ 只有状态为"Running"的Agent可以停止 - 停止后Agent状态变为"Stopped" - 停止的Agent不会释放配额,仍然占用资源 ### 5. 删除自定义Agent #### 接口 ```http DELETE /api/user/custom-agents/{name} Authorization: Bearer {token} ``` #### 响应示例 ```json { "success": true, "message": "自定义 Agent my-custom-agent 已删除", "data": { "quotaReleased": { "cpu": 1.0, "memory": 2.0 } } } ``` --- ## Agent模板管理 ### 1. 获取创建自定义Agent所需的模板信息 #### 接口 ```http GET /api/user/custom-agents/templates Authorization: Bearer {token} ``` #### 响应示例 ```json { "success": true, "data": { "frameworkTemplates": ["A2A", "langchain", "MCP"], "dataTemplates": [ { "template": "mysql_agent", "port": 8080, "env_info": { "required": { "MYSQL_HOST": "MySQL数据库主机地址", "MYSQL_USER": "MySQL用户名", "MYSQL_PASSWORD": "MySQL密码", "MYSQL_DATABASE": "MySQL数据库名" }, "optional": { "MYSQL_PORT": "MySQL端口,默认3306" } }, "description": "MySQL 数据库 Agent,支持 SQL 查询和数据操作" }, { "template": "postgresql_agent", "port": 8080, "env_info": { "required": { "PG_HOST": "PostgreSQL数据库主机地址", "PG_USER": "PostgreSQL用户名", "PG_PASSWORD": "PostgreSQL密码", "PG_DATABASE": "PostgreSQL数据库名" }, "optional": { "PG_PORT": "PostgreSQL端口,默认5432" } }, "description": "PostgreSQL 数据库 Agent,支持 SQL 查询和数据操作" } ] } } ``` #### 响应字段说明 | 字段 | 类型 | 说明 | |------|------|------| | frameworkTemplates | array | 框架类型列表(A2A/langchain/MCP),用于 `frameworkTemplate` 参数 | | dataTemplates | array | 数据存储模板列表,用于 `template` 参数 | | dataTemplates[].template | string | 模板名称(如 mysql_agent) | | dataTemplates[].port | number | 服务端口 | | dataTemplates[].env_info | object | 环境变量配置说明 | | dataTemplates[].env_info.required | object | 必需的环境变量 | | dataTemplates[].env_info.optional | object | 可选的环境变量 | | dataTemplates[].description | string | 模板描述 | #### 使用说明 - **用途**:获取创建自定义Agent所需的两类模板信息 - **frameworkTemplates**:框架类型,决定Agent的运行框架(传递给 `frameworkTemplate` 参数) - **dataTemplates**:数据存储模板,决定Agent镜像类型(传递给 `template` 参数) - **业务流程**: 1. 前端调用此接口获取模板列表 2. 用户选择**数据存储模板**(如 `mysql_agent`)→ 对应 `template` 参数 3. 用户选择**框架类型**(如 `MCP`)→ 对应 `frameworkTemplate` 参数 4. 根据 `env_info.required` 提示用户填写必需的环境变量(如数据库连接信息) 5. 提交创建请求 #### ⚠️ 重要:template 与 frameworkTemplate 的区别 | 参数 | 来源 | 说明 | 示例 | |-----|------|------|------| | `template` | `dataTemplates[].template` | **数据存储模板**,决定Agent镜像 | `mysql_agent`, `postgresql_agent` | | `frameworkTemplate` | `frameworkTemplates[]` | **框架类型**,决定运行框架 | `MCP`, `A2A`, `langchain` | --- ## 模型列表 ### 1. 获取可用模型 #### 接口 ```http GET /api/user/models Authorization: Bearer {token} ``` #### 响应示例 ```json { "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`字段作为模型参数 --- ## 错误处理 ### 错误响应格式 ```json { "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` | 服务不可用 | ### 配额不足错误详情 ```json { "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 ```mermaid 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[完成] ``` --- ## 联系支持 如有问题或需要帮助,请联系: - 技术支持:support@example.com - 文档反馈:docs@example.com --- **文档结束**