taijibaga/taiji-AI-PAD

Fork 0

forked from xiaohei/taiji-AI-PAD

Files

T

zhanggangyong fe69a70a3a 更新外部数据工具和工具集

2026-01-23 10:57:13 +00:00

19 KiB

Raw Blame History

外部数据工具 - 接口文档

版本: 2026-01-23 v1.0
基础路径: /api/user/external-tools
认证方式: Bearer Token（在请求头添加 Authorization: Bearer <JWT Token>）

📊 业务流程

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              外部数据工具流程                                         │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│  ① 创建外部工具           ② Agent Manager 生成         ③ 创建自定义 Agent            │
│  ┌───────────────┐        ┌───────────────┐           ┌───────────────┐            │
│  │ POST          │  ───→  │ 生成 Pydantic │    ───→   │ POST          │            │
│  │ /external-tools│        │ 工具代码文件   │           │ /custom-agents │            │
│  └───────────────┘        └───────────────┘           │ +externalTools │            │
│         │                        │                    └───────────────┘            │
│         ↓                        ↓                           │                     │
│  保存基本信息           返回 tool_ref_id              传递 tool_ref_ids             │
│  到 PostgreSQL                                        给 Agent Manager             │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘

核心概念

概念	说明
外部数据工具	用户创建的连接外部 API 的工具配置
tool_ref_id	Agent Manager 生成工具后返回的标识，部署 Agent 时传递
工具状态	pending(等待生成), active(可用), error(生成失败)

存储职责划分

存储位置	存储内容
MCP-Server (PostgreSQL)	工具基本信息（名称、URL、方法）、tool_ref_id、状态
Agent Manager	Pydantic 工具代码文件、完整配置（含敏感信息）

🔐 通用请求头

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

📑 接口列表

外部数据工具接口

序号	接口	方法	说明
1	`/api/user/external-tools`	POST	创建外部数据工具
2	`/api/user/external-tools/upload`	POST	上传 JSON 文件创建工具
3	`/api/user/external-tools`	GET	获取工具列表
4	`/api/user/external-tools/{tool_id}`	GET	获取工具详情
5	`/api/user/external-tools/{tool_id}`	PUT	更新工具配置
6	`/api/user/external-tools/{tool_id}`	DELETE	删除工具
7	`/api/user/external-tools/{tool_id}/test`	POST	测试工具连接

工具集接口

序号	接口	方法	说明
9	`/api/user/toolkits`	POST	创建工具集（最多 8 个工具）
10	`/api/user/toolkits`	GET	获取工具集列表
11	`/api/user/toolkits/{toolkit_id}`	GET	获取工具集详情
12	`/api/user/toolkits/{toolkit_id}`	PUT	更新工具集
13	`/api/user/toolkits/{toolkit_id}`	DELETE	删除工具集

自定义 Agent 接口

序号	接口	方法	说明
8	`/api/user/custom-agents`	POST	创建自定义 Agent（支持外部工具/工具集）

1️⃣ 创建外部数据工具

接口

POST /api/user/external-tools

请求参数

参数	类型	必填	说明
`name`	string	✅	工具名称（1-100字符）
`description`	string	❌	工具描述
`url`	string	✅	API 端点 URL
`method`	string	❌	HTTP 方法，默认 POST
`headers`	object	❌	自定义请求头
`auth`	object	❌	认证配置
`request_params`	object	❌	URL 查询参数定义（JSON Schema）
`request_body`	object	❌	请求体定义（JSON Schema）
`response_mapping`	object	❌	响应字段映射
`timeout`	integer	❌	超时时间（秒），默认 30
`retry`	object	❌	重试配置

认证配置 (auth)

API Key 认证

{
  "auth": {
    "type": "api_key",
    "key": "sk-xxxxxxxxxxxx",
    "in": "header",
    "name": "X-API-Key"
  }
}

Bearer Token 认证

{
  "auth": {
    "type": "bearer",
    "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Basic Auth 认证

{
  "auth": {
    "type": "basic",
    "username": "admin",
    "password": "password123"
  }
}

请求示例

{
  "name": "weather-query-tool",
  "description": "查询天气信息的外部数据工具",
  "url": "https://api.weather.com/v1/forecast",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "auth": {
    "type": "api_key",
    "key": "sk-xxxxxxxxxxxx",
    "in": "header",
    "name": "X-API-Key"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      }
    }
  },
  "timeout": 30
}

响应示例

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "weather-query-tool",
    "tool_ref_id": "tool-weather-abc123",
    "status": "active",
    "created_at": "2026-01-23T10:00:00Z"
  },
  "message": "外部数据工具创建成功"
}

2️⃣ 上传 JSON 文件创建工具

接口

POST /api/user/external-tools/upload
Content-Type: multipart/form-data

请求参数

参数	类型	必填	说明
`file`	File	✅	JSON 配置文件（.json）

JSON 文件格式

{
  "name": "weather-api",
  "description": "查询城市天气信息",
  "url": "https://api.weather.com/v1/forecast",
  "method": "GET",
  "auth": {
    "type": "api_key",
    "key": "your-weather-api-key",
    "in": "query",
    "name": "apikey"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      }
    }
  },
  "timeout": 10
}

响应示例

同创建接口

3️⃣ 获取工具列表

接口

GET /api/user/external-tools

查询参数

参数	类型	必填	说明
`status`	string	❌	过滤状态：active/pending/error
`page`	integer	❌	页码，默认 1
`page_size`	integer	❌	每页数量，默认 20

响应示例

{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "weather-query-tool",
        "description": "查询天气信息的外部数据工具",
        "url": "https://api.weather.com/v1/forecast",
        "method": "POST",
        "auth_type": "api_key",
        "status": "active",
        "usage_count": 15,
        "created_at": "2026-01-23T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

4️⃣ 获取工具详情

接口

GET /api/user/external-tools/{tool_id}

路径参数

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

响应示例

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "weather-query-tool",
    "description": "查询天气信息的外部数据工具",
    "url": "https://api.weather.com/v1/forecast",
    "method": "POST",
    "auth_type": "api_key",
    "tool_ref_id": "tool-weather-abc123",
    "status": "active",
    "usage_count": 15,
    "created_at": "2026-01-23T10:00:00Z",
    "updated_at": "2026-01-23T10:00:00Z"
  }
}

注意：MCP-Server 只存储基本展示信息，不存储完整配置和敏感信息。

5️⃣ 更新工具配置

接口

PUT /api/user/external-tools/{tool_id}

请求参数

与创建接口相同，需要传递完整配置（因为 MCP-Server 不存储完整配置）。

响应示例

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "weather-query-tool-v2",
    "tool_ref_id": "tool-weather-abc123-v2",
    "status": "active",
    "updated_at": "2026-01-23T11:00:00Z"
  },
  "message": "外部数据工具更新成功"
}

6️⃣ 删除工具

接口

DELETE /api/user/external-tools/{tool_id}

响应示例

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": "外部数据工具删除成功"
}

7️⃣ 测试工具连接

接口

POST /api/user/external-tools/{tool_id}/test

请求参数

参数	类型	必填	说明
`test_params`	object	❌	测试参数

请求示例

{
  "test_params": {
    "city": "北京"
  }
}

响应示例

{
  "success": true,
  "data": {
    "connected": true,
    "response_time_ms": 156,
    "status_code": 200,
    "sample_response": {
      "status": "ok",
      "data": {
        "city": "北京",
        "temperature": "15°C"
      }
    }
  },
  "message": "工具连接测试成功"
}

8️⃣ 创建带有外部工具的自定义 Agent

注意: 此功能已整合到原有的自定义 Agent 创建接口中

接口

POST /api/user/custom-agents

请求参数

参数	类型	必填	说明
`name`	string	✅	Agent 名称（1-63字符）
`template`	string	✅	Agent 模板名称（从 Agent Manager 获取）
`frameworkTemplate`	string	❌	框架模板类型（A2A/langchain/MCP），默认 MCP
`description`	string	❌	Agent 描述
`externalTools`	string[]	❌	外部数据工具 ID 列表（使用新的外部工具）
`tools`	string[]	❌	内置工具 ID 列表
`cpuRequest`	string	❌	CPU 请求量，默认 "100m"
`cpuLimit`	string	❌	CPU 限制量
`memoryRequest`	string	❌	内存请求量，默认 "128Mi"
`memoryLimit`	string	❌	内存限制量
`model`	string	❌	使用的模型名称（会自动注入 LiteLLM 配置）
`envConfig`	object	❌	自定义环境变量

请求示例（使用外部数据工具）

{
  "name": "my-data-agent",
  "template": "custom_agent",
  "description": "我的数据处理 Agent",
  "externalTools": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "cpuRequest": "500m",
  "cpuLimit": "1000m",
  "memoryRequest": "512Mi",
  "memoryLimit": "1Gi",
  "model": "gpt-4"
}

响应示例

{
  "success": true,
  "data": {
    "name": "my-data-agent",
    "namespace": "ai-agents",
    "status": "Pending",
    "tools_attached": 2,
    "servicePort": 8080,
    "accessInfo": {
      "domain": "my-data-agent.example.com",
      "domain_url": "https://my-data-agent.example.com"
    },
    "modelInjected": true,
    "quotaRemaining": {
      "cpu": 3.5,
      "memory": 7.0
    }
  },
  "message": "自定义 Agent my-data-agent 创建成功"
}

❌ 错误响应

通用格式

{
  "detail": {
    "error": "错误代码",
    "message": "错误信息"
  }
}

常见错误码

HTTP状态码	错误代码	说明
400	`invalid_config`	工具配置格式无效
400	`invalid_url`	URL 格式无效
400	`invalid_tool_id`	无效的工具 ID 格式
400	`tool_not_active`	工具尚未就绪
400	`missing_tools`	必须选择至少一个工具
400	`quota_insufficient`	CPU/内存配额不足
403	`no_quota`	没有自定义Agent配额
403	`no_model_permission`	没有指定模型的使用权限
404	`tool_not_found`	工具不存在
409	`tool_name_exists`	工具名称已存在
500	`am_generate_failed`	Agent Manager 生成工具失败

📊 Agent Manager 接口（内部使用）

以下接口由 MCP-Server 内部调用，前端无需关注：

接口	方法	说明
`POST /tools/generate`	生成 Pydantic 工具文件
`PUT /tools/{tool_ref_id}`	更新工具文件
`DELETE /tools/{tool_ref_id}`	删除工具文件
`POST /tools/{tool_ref_id}/test`	测试工具连接
`POST /agents`	创建 Agent（支持 tool_refs 参数）

📋 JSON 配置文件示例

示例 1：天气查询工具

{
  "name": "weather-api",
  "description": "查询城市天气信息",
  "url": "https://api.weather.com/v1/forecast",
  "method": "GET",
  "auth": {
    "type": "api_key",
    "key": "your-weather-api-key",
    "in": "query",
    "name": "apikey"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      },
      "units": {
        "type": "string",
        "description": "温度单位",
        "enum": ["metric", "imperial"],
        "default": "metric"
      }
    }
  },
  "timeout": 10
}

示例 2：企业内部 API

{
  "name": "internal-crm-api",
  "description": "查询客户信息",
  "url": "https://internal.company.com/api/v2/customers",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "auth": {
    "type": "bearer",
    "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "request_body": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "客户ID",
        "required": true
      },
      "include_orders": {
        "type": "boolean",
        "description": "是否包含订单信息",
        "default": false
      }
    }
  },
  "response_mapping": {
    "success_field": "code",
    "success_value": 0,
    "data_field": "data",
    "error_field": "message"
  },
  "timeout": 30
}

示例 3：数据库查询服务

{
  "name": "db-query-service",
  "description": "执行 SQL 查询",
  "url": "https://db-gateway.company.com/query",
  "method": "POST",
  "auth": {
    "type": "basic",
    "username": "readonly",
    "password": "secure-password-123"
  },
  "request_body": {
    "type": "object",
    "properties": {
      "database": {
        "type": "string",
        "description": "数据库名称",
        "required": true
      },
      "sql": {
        "type": "string",
        "description": "SQL 查询语句",
        "required": true
      }
    }
  },
  "timeout": 60
}

🧰 工具集接口

工具集允许用户将多个外部数据工具组合在一起，方便部署自定义 Agent。

9️⃣ 创建工具集

POST /api/user/toolkits

请求参数

参数	类型	必填	说明
`name`	string	✅	工具集名称（1-100字符）
`description`	string	❌	工具集描述
`tool_ids`	string[]	✅	外部数据工具 ID 列表（1-8 个）

请求示例

{
  "name": "数据分析工具集",
  "description": "包含数据查询和分析相关工具",
  "tool_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

响应示例

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "name": "数据分析工具集",
    "description": "包含数据查询和分析相关工具",
    "tool_count": 2,
    "created_at": "2026-01-23T10:00:00Z"
  },
  "message": "工具集创建成功"
}

🔟 获取工具集列表

GET /api/user/toolkits

查询参数

参数	类型	必填	说明
`page`	integer	❌	页码，默认 1
`page_size`	integer	❌	每页数量，默认 20，最大 100

响应示例

{
  "success": true,
  "data": {
    "toolkits": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440002",
        "name": "数据分析工具集",
        "description": "包含数据查询和分析相关工具",
        "tool_count": 2,
        "usage_count": 5,
        "created_at": "2026-01-23T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

1️⃣1️⃣ 获取工具集详情

GET /api/user/toolkits/{toolkit_id}

响应示例

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "name": "数据分析工具集",
    "description": "包含数据查询和分析相关工具",
    "tool_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "550e8400-e29b-41d4-a716-446655440001"
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "weather-api",
        "description": "天气查询 API",
        "url": "https://api.weather.com/current",
        "method": "GET",
        "status": "active"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "stock-api",
        "description": "股票查询 API",
        "url": "https://api.stock.com/price",
        "method": "GET",
        "status": "active"
      }
    ],
    "usage_count": 5,
    "created_at": "2026-01-23T10:00:00Z",
    "updated_at": "2026-01-23T12:00:00Z"
  }
}

1️⃣2️⃣ 更新工具集

PUT /api/user/toolkits/{toolkit_id}

请求参数

参数	类型	必填	说明
`name`	string	❌	工具集名称
`description`	string	❌	工具集描述
`tool_ids`	string[]	❌	工具 ID 列表（1-8 个）

1️⃣3️⃣ 删除工具集

DELETE /api/user/toolkits/{toolkit_id}

⚠️ 注意：删除工具集不会删除其中的工具，只是解除组合关系。

📌 在自定义 Agent 中使用工具集

创建自定义 Agent 时，可以通过 toolkit 字段指定工具集：

{
  "name": "my-data-agent",
  "template": "custom_agent",
  "toolkit": "660e8400-e29b-41d4-a716-446655440002",
  "cpuRequest": "500m",
  "memoryRequest": "512Mi"
}

也可以同时使用工具集和单独的工具（会自动合并去重）：

{
  "name": "my-data-agent",
  "template": "custom_agent",
  "toolkit": "660e8400-e29b-41d4-a716-446655440002",
  "externalTools": ["770e8400-e29b-41d4-a716-446655440003"],
  "cpuRequest": "500m",
  "memoryRequest": "512Mi"
}

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

19 KiB Raw Blame History Unescape Escape

外部数据工具 - 接口文档

📊 业务流程

核心概念

存储职责划分

🔐 通用请求头

📑 接口列表

外部数据工具接口

工具集接口

自定义 Agent 接口

1️⃣ 创建外部数据工具

接口

请求参数

认证配置 (auth)

API Key 认证

Bearer Token 认证

Basic Auth 认证

请求示例

响应示例

2️⃣ 上传 JSON 文件创建工具

接口

请求参数

JSON 文件格式

响应示例

3️⃣ 获取工具列表

接口

查询参数

响应示例

4️⃣ 获取工具详情

接口

路径参数

响应示例

5️⃣ 更新工具配置

接口

请求参数

响应示例

6️⃣ 删除工具

接口

响应示例

7️⃣ 测试工具连接

接口

请求参数

请求示例

响应示例

8️⃣ 创建带有外部工具的自定义 Agent

接口

请求参数

请求示例（使用外部数据工具）

响应示例

❌ 错误响应

通用格式

常见错误码

📊 Agent Manager 接口（内部使用）

📋 JSON 配置文件示例

示例 1：天气查询工具

示例 2：企业内部 API

示例 3：数据库查询服务

🧰 工具集接口

9️⃣ 创建工具集

请求参数

请求示例

响应示例

🔟 获取工具集列表

查询参数

响应示例

1️⃣1️⃣ 获取工具集详情

响应示例

1️⃣2️⃣ 更新工具集

请求参数

1️⃣3️⃣ 删除工具集

📌 在自定义 Agent 中使用工具集

19 KiB

Raw Blame History