taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity
Files
b754af8ba184a4ae4c5bb3b5b52963ea6783b3f5
taiji-AI-PAD/Docs/项目文档/数据工具与自定义Agent-前端接口文档.md
T

18 KiB
Raw Blame History

数据工具与自定义Agent - 接口文档

版本: 2026-01-13 v4
基础路径: /api/user
认证方式: Bearer Token（在请求头添加 Authorization: Bearer <JWT Token>）
状态: ✅ 已修复

📊 业务流程

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              业务流程                                                │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│  ① 获取模板列表         ② 创建工具（基于模板）        ③ 创建Agent（选择工具）        │
│  ┌───────────────┐     ┌───────────────┐            ┌───────────────┐              │
│  │ GET           │     │ POST          │            │ POST          │              │
│  │ /templates    │────→│ /tools/create │───────────→│ /custom-agents│              │
│  └───────────────┘     └───────────────┘            └───────────────┘              │
│         │                     │                            │                       │
│         ↓                     ↓                            ↓                       │
│  返回 dataTemplates    保存到 Tool 表               从工具获取 template             │
│  [mysql_agent,         - template: mysql_agent      和 envConfig，                  │
│   postgresql_agent]    - env_config: {...}          传递给 Agent Manager            │
│                                                                                     │
│  含 env_info:                                                                       │
│  - required                                                                         │
│  - optional                                                                         │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘

核心概念

概念 说明
模板 (dataTemplates) Agent 镜像类型，来自 Agent Manager，如 mysql_agent，包含 env_info 定义所需配置
工具 (Tool) 用户基于模板创建的配置实例，包含 template + env_config
自定义 Agent 根据工具的模板类型和配置创建的 K8s Pod

🔐 通用请求头

Content-Type: application/json
Authorization: Bearer <JWT Token>

📑 接口列表

序号 接口 方法 说明
1 /api/user/custom-agents/templates GET 获取自定义Agent模板
2 /api/user/tools/create POST 创建工具
3 /api/user/tools GET 获取用户工具列表
4 /api/user/tools/{tool_id} PUT 更新工具
5 /api/user/tools/{tool_id} DELETE 删除工具
6 /api/user/custom-agents POST 创建自定义Agent
7 /api/user/custom-agents GET 获取用户自定义Agent列表
8 /api/user/custom-agents/{name} DELETE 删除自定义Agent

1️⃣ 获取自定义Agent模板

接口

GET /api/user/custom-agents/templates

请求参数

无

响应参数

字段 类型 说明
success boolean 请求是否成功
data.frameworkTemplates string[] 框架类型列表
data.dataTemplates array 数据存储模板列表
data.dataTemplates[].template string 模板名称
data.dataTemplates[].port number | null 服务端口
data.dataTemplates[].env_info.required object 必需的环境变量
data.dataTemplates[].env_info.optional object 可选的环境变量
data.dataTemplates[].description string 模板描述

响应示例

{
  "success": true,
  "data": {
    "frameworkTemplates": ["A2A", "langchain", "MCP"],
    "dataTemplates": [
      {
        "template": "mysql_agent",
        "port": null,
        "env_info": {
          "required": {
            "MYSQL_HOST": "MySQL数据库主机地址",
            "MYSQL_USER": "MySQL用户名",
            "MYSQL_PASSWORD": "MySQL密码",
            "MYSQL_DATABASE": "MySQL数据库名",
            "OPENAI_API_KEY": "OpenAI API密钥"
          },
          "optional": {
            "MYSQL_PORT": "MySQL端口，默认3306"
          }
        },
        "description": "MySQL 数据库 Agent，支持 SQL 查询和数据操作"
      },
      {
        "template": "postgresql_agent",
        "port": null,
        "env_info": {
          "required": {
            "POSTGRES_HOST": "PostgreSQL数据库主机地址",
            "POSTGRES_USER": "PostgreSQL用户名",
            "POSTGRES_PASSWORD": "PostgreSQL密码",
            "POSTGRES_DATABASE": "PostgreSQL数据库名",
            "OPENAI_API_KEY": "OpenAI API密钥"
          },
          "optional": {
            "POSTGRES_PORT": "PostgreSQL端口，默认5432"
          }
        },
        "description": "PostgreSQL 数据库 Agent，支持 SQL 查询和数据操作"
      }
    ]
  }
}

注意：OPENAI_API_KEY 虽然在模板 env_info.required 中列出，但用户无需填写。系统会在创建 Agent 时自动注入用户的 LiteLLM 密钥。

2️⃣ 创建工具（基于模板）

接口

POST /api/user/tools/create

请求参数

参数 类型 必填 说明
name string ✅ 工具名称
description string ❌ 工具描述
template string ✅ 模板名称（来自 dataTemplates[].template）
envConfig object ✅ 环境变量配置（根据模板 env_info 填写）

请求示例（MySQL 工具）

{
  "name": "my-mysql-tool",
  "description": "我的MySQL数据库连接工具",
  "template": "mysql_agent",
  "envConfig": {
    "MYSQL_HOST": "mysql.example.com",
    "MYSQL_USER": "root",
    "MYSQL_PASSWORD": "password123",
    "MYSQL_DATABASE": "mydb",
    "MYSQL_PORT": "3306"
  }
}

请求示例（PostgreSQL 工具）

{
  "name": "my-pgsql-tool",
  "description": "我的PostgreSQL数据库连接工具",
  "template": "postgresql_agent",
  "envConfig": {
    "POSTGRES_HOST": "postgres.example.com",
    "POSTGRES_USER": "postgres",
    "POSTGRES_PASSWORD": "password123",
    "POSTGRES_DATABASE": "mydb",
    "POSTGRES_PORT": "5432"
  }
}

注意：OPENAI_API_KEY 无需填写，系统会自动注入用户的 LiteLLM 密钥。

响应参数

字段 类型 说明
success boolean 请求是否成功
data.id string 工具ID（UUID）
data.name string 工具名称
data.template string 模板名称
data.type string 工具类型（database）
message string 响应消息

响应示例

{
  "success": true,
  "data": {
    "id": "d14cd898-e2cf-4150-a7f9-53b962c1c9a2",
    "name": "my-mysql-tool",
    "template": "mysql_agent",
    "type": "database"
  },
  "message": "工具创建成功"
}

3️⃣ 获取用户工具列表

接口

GET /api/user/tools

请求参数

无

响应参数

字段 类型 说明
success boolean 请求是否成功
data.tools array 工具列表
data.tools[].id string 工具ID（UUID）
data.tools[].name string 工具名称
data.tools[].description string 工具描述
data.tools[].template string 模板名称
data.tools[].category string 工具分类
data.tools[].envConfig object 环境变量配置（敏感信息已脱敏）
data.tools[].created_at string 创建时间（ISO 8601）
data.tools[].updated_at string 更新时间（ISO 8601）
data.tools[].is_active boolean 是否激活
data.tools[].is_public boolean 是否公开

响应示例

{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "d14cd898-e2cf-4150-a7f9-53b962c1c9a2",
        "name": "my-mysql-tool",
        "description": "我的MySQL数据库连接工具",
        "template": "mysql_agent",
        "category": "database",
        "envConfig": {
          "MYSQL_HOST": "mysql.example.com",
          "MYSQL_USER": "root",
          "MYSQL_PASSWORD": "pa******23",
          "MYSQL_DATABASE": "mydb",
          "MYSQL_PORT": "3306",
          "OPENAI_API_KEY": "sk******xx"
        },
        "type": "database",
        "endpoint": null,
        "method": null,
        "created_at": "2026-01-13T08:00:00Z",
        "updated_at": "2026-01-13T08:00:00Z",
        "is_active": true,
        "is_public": false
      }
    ]
  }
}

注意：响应中的 envConfig 会对敏感字段（密码、API密钥等）进行脱敏处理。

4️⃣ 更新工具

接口

PUT /api/user/tools/{tool_id}

路径参数

参数 类型 说明
tool_id string 工具ID（UUID）

请求参数

参数 类型 必填 说明
description string ❌ 工具描述
is_active boolean ❌ 是否激活
envConfig object ❌ 更新环境变量配置

注意：template 字段创建后不可修改。

请求示例

{
  "description": "更新后的MySQL数据库工具",
  "envConfig": {
    "MYSQL_HOST": "mysql-new.example.com",
    "MYSQL_USER": "admin",
    "MYSQL_PASSWORD": "newpassword123",
    "MYSQL_DATABASE": "mydb",
    "MYSQL_PORT": "3306",
    "OPENAI_API_KEY": "sk-newkey"
  }
}

响应示例

{
  "success": true,
  "data": {
    "id": "d14cd898-e2cf-4150-a7f9-53b962c1c9a2",
    "name": "my-mysql-tool",
    "template": "mysql_agent",
    "updated_at": "2026-01-13T10:00:00Z"
  },
  "message": "工具更新成功"
}

5️⃣ 删除工具

接口

DELETE /api/user/tools/{tool_id}

路径参数

参数 类型 说明
tool_id string 工具ID（UUID）

响应示例

{
  "success": true,
  "data": {
    "id": "d14cd898-e2cf-4150-a7f9-53b962c1c9a2"
  },
  "message": "工具删除成功"
}

6️⃣ 创建自定义Agent

核心逻辑：创建 Agent 时选择已创建的工具，系统自动从工具获取 template 和 envConfig，调用 Agent Manager 创建对应类型的 Agent。

接口

POST /api/user/custom-agents

请求参数

参数 类型 必填 默认值 说明
name string ✅ - Agent名称（小写字母、数字、连字符，1-63字符）
tools string[] ✅ - 工具ID列表（第一个工具决定Agent类型和配置）
template string ❌ 从工具获取 模板名称（可选，未指定时从工具获取）
frameworkTemplate string ❌ "MCP" 框架类型（"MCP" | "A2A" | "langchain"）
description string ❌ - Agent描述
cpuRequest string ❌ "100m" CPU请求量
cpuLimit string ❌ =cpuRequest CPU限制量
memoryRequest string ❌ "128Mi" 内存请求量
memoryLimit string ❌ =memoryRequest 内存限制量
model string ❌ - 模型名称（用于注入 LiteLLM 密钥）
envConfig object ❌ {} 额外环境变量（与工具配置合并，请求中的优先）
agentRole string ❌ - A2A框架：Agent角色
agentCapabilities string[] ❌ - A2A框架：Agent能力列表

环境变量优先级

环境变量从以下来源合并，后者覆盖前者：

  1. 工具的 env_config
  2. 请求中的 envConfig

请求示例（基于已创建的工具）

{
  "name": "my-mysql-agent",
  "tools": ["d14cd898-e2cf-4150-a7f9-53b962c1c9a2"],
  "description": "我的MySQL数据库Agent",
  "cpuRequest": "500m",
  "cpuLimit": "1000m",
  "memoryRequest": "1Gi",
  "memoryLimit": "2Gi",
  "model": "gpt-4"
}

系统自动从工具获取 template: "mysql_agent" 和 envConfig: {MYSQL_HOST, ...}

请求示例（A2A框架）

{
  "name": "my-pgsql-agent",
  "tools": ["e25de999-f3dg-5261-b8ga-64c073d2d0b3"],
  "frameworkTemplate": "A2A",
  "description": "我的PostgreSQL数据分析Agent",
  "cpuRequest": "1000m",
  "memoryRequest": "2Gi",
  "model": "gpt-4",
  "agentRole": "data_analyzer",
  "agentCapabilities": ["sql_query", "data_analysis", "report_generation"]
}

响应参数

字段 类型 说明
success boolean 请求是否成功
data.name string Agent 名称
data.namespace string Kubernetes 命名空间
data.status string Agent 状态
data.servicePort number | null 服务端口
data.accessInfo object | null 访问信息
data.modelInjected boolean 是否注入了模型配置
data.quotaRemaining.cpu number 剩余 CPU（核）
data.quotaRemaining.memory number 剩余内存（GB）
message string 响应消息

响应示例

{
  "success": true,
  "data": {
    "name": "my-mysql-agent",
    "namespace": "ai-agents",
    "status": "Pending",
    "servicePort": 8080,
    "accessInfo": {
      "endpoints": {
        "http": "http://my-mysql-agent.ai-agents.svc.cluster.local:8080"
      }
    },
    "modelInjected": true,
    "quotaRemaining": {
      "cpu": 3.5,
      "memory": 7.0
    }
  },
  "message": "自定义 Agent my-mysql-agent 创建成功"
}

7️⃣ 获取用户自定义Agent列表

接口

GET /api/user/custom-agents

请求参数

无

响应参数

字段 类型 说明
success boolean 请求是否成功
data.agents array Agent列表
data.agents[].name string Agent名称
data.agents[].template string 模板名称
data.agents[].status string 状态
data.agents[].cpu string CPU请求量
data.agents[].memory string 内存请求量
data.agents[].startTime string | null 启动时间
data.agents[].runningSeconds number 运行时长（秒）

响应示例

{
  "success": true,
  "data": {
    "agents": [
      {
        "name": "my-mysql-agent",
        "template": "mysql_agent",
        "status": "Running",
        "cpu": "500m",
        "memory": "1Gi",
        "startTime": "2026-01-13T08:00:00Z",
        "runningSeconds": 3600
      }
    ]
  }
}

8️⃣ 删除自定义Agent

接口

DELETE /api/user/custom-agents/{name}

路径参数

参数 类型 说明
name string Agent名称

响应参数

字段 类型 说明
success boolean 请求是否成功
data.name string 已删除的Agent名称
data.quotaReleased.cpu number 释放的CPU（核）
data.quotaReleased.memory number 释放的内存（GB）
data.cost number 产生的费用
data.duration number 运行时长（秒）
message string 响应消息

响应示例

{
  "success": true,
  "data": {
    "name": "my-mysql-agent",
    "quotaReleased": {
      "cpu": 0.5,
      "memory": 1.0
    },
    "cost": 0.05,
    "duration": 3600
  },
  "message": "自定义 Agent my-mysql-agent 删除成功，已释放配额"
}

❌ 错误响应

通用格式

{
  "detail": {
    "error": "错误代码",
    "message": "错误信息",
    "detail": "详细信息（可选）"
  }
}

常见错误码

HTTP状态码 错误代码 说明
400 invalid_template 无效的模板名称
400 quota_insufficient CPU/内存配额不足
400 invalid_tool_id 无效的工具ID格式
400 missing_template 必须指定 template 参数或选择包含模板配置的工具
403 no_quota 用户没有自定义Agent配额
403 no_model_permission 没有指定模型的使用权限
404 agent_not_found Agent不存在或不属于当前用户
404 tool_not_found 工具不存在
409 name_exists 工具/Agent名称已存在
500 create_agent_failed Agent Manager创建失败

错误示例

{
  "detail": {
    "error": "quota_insufficient",
    "message": "CPU 配额不足。剩余: 0.50 核，请求: 1.00 核"
  }
}

📊 后端服务调用关系

┌─────────┐      ┌─────────────┐      ┌───────────────┐      ┌─────────┐
│  前端   │ ←──→ │  MCP-Server │ ←──→ │ Agent Manager │ ←──→ │   K8s   │
└─────────┘      └─────────────┘      └───────────────┘      └─────────┘
                        │
                        ↓
                   ┌─────────┐
                   │ 数据库  │
                   │PostgreSQL│
                   └─────────┘

MCP-Server 转发到 Agent Manager 的接口

前端接口 Agent Manager 接口
GET /custom-agents/templates GET /templates/custom
POST /custom-agents POST /agents
GET /custom-agents GET /agents/{name}/status
DELETE /custom-agents/{name} DELETE /agents/{name}

MCP-Server 本地处理的接口

接口 说明
POST /tools/create 保存到 Tool 表
GET /tools 从 Tool 表查询
PUT /tools/{tool_id} 更新 Tool 表
DELETE /tools/{tool_id} 从 Tool 表删除

如有问题，请联系大智开发团队。

View Git Blame Copy Permalink