forked from xiaohei/taiji-AI-PAD
备份
This commit is contained in:
zhanggangyong
+302
-388
@@ -1,54 +1,22 @@
|
||||
# 外部数据工具 - 接口文档
|
||||
# 外部数据工具 - 快速接入指南
|
||||
|
||||
> **版本**: 2026-01-23 v1.0
|
||||
> **版本**: 2026-01-29 v2.0
|
||||
> **基础路径**: `/api/user/external-tools`
|
||||
> **认证方式**: Bearer Token（在请求头添加 `Authorization: Bearer <JWT Token>`）
|
||||
> **设计原则**: 只需 3 步，连接您的 API
|
||||
|
||||
---
|
||||
|
||||
## 📊 业务流程
|
||||
## 🚀 快速开始
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 外部数据工具流程 │
|
||||
├─────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ① 创建外部工具 ② Agent Manager 生成 ③ 创建自定义 Agent │
|
||||
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
|
||||
│ │ POST │ ───→ │ 生成 Pydantic │ ───→ │ POST │ │
|
||||
│ │ /external-tools│ │ 工具代码文件 │ │ /custom-agents │ │
|
||||
│ └───────────────┘ └───────────────┘ │ +externalTools │ │
|
||||
│ │ │ └───────────────┘ │
|
||||
│ ↓ ↓ │ │
|
||||
│ 保存基本信息 返回 tool_ref_id 传递 tool_ref_ids │
|
||||
│ 到 PostgreSQL 给 Agent Manager │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
### 创建工具只需提供 4 个信息：
|
||||
|
||||
### 核心概念
|
||||
|
||||
| 概念 | 说明 |
|
||||
|------|------|
|
||||
| **外部数据工具** | 用户创建的连接外部 API 的工具配置 |
|
||||
| **tool_ref_id** | Agent Manager 生成工具后返回的标识，部署 Agent 时传递 |
|
||||
| **工具状态** | pending(等待生成), active(可用), error(生成失败) |
|
||||
|
||||
### 存储职责划分
|
||||
|
||||
| 存储位置 | 存储内容 |
|
||||
|---------|---------|
|
||||
| **MCP-Server (PostgreSQL)** | 工具基本信息（名称、URL、方法）、tool_ref_id、状态 |
|
||||
| **Agent Manager** | Pydantic 工具代码文件、完整配置（含敏感信息） |
|
||||
|
||||
---
|
||||
|
||||
## 🔐 通用请求头
|
||||
|
||||
```http
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer <JWT Token>
|
||||
```
|
||||
| 信息 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| **名称** | 给工具起个名字 | `"天气查询"` |
|
||||
| **API 地址** | 您的 API URL | `"https://api.weather.com/forecast"` |
|
||||
| **认证方式** | 三选一 | `"api_key"` / `"bearer"` / `"basic"` |
|
||||
| **认证凭证** | 您的密钥或账密 | 见下方示例 |
|
||||
|
||||
---
|
||||
|
||||
@@ -70,17 +38,17 @@ Authorization: Bearer <JWT Token>
|
||||
|
||||
| 序号 | 接口 | 方法 | 说明 |
|
||||
|:---:|------|------|------|
|
||||
| 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 | 删除工具集 |
|
||||
| 8 | `/api/user/toolkits` | POST | 创建工具集（最多 8 个工具） |
|
||||
| 9 | `/api/user/toolkits` | GET | 获取工具集列表 |
|
||||
| 10 | `/api/user/toolkits/{toolkit_id}` | GET | 获取工具集详情 |
|
||||
| 11 | `/api/user/toolkits/{toolkit_id}` | PUT | 更新工具集 |
|
||||
| 12 | `/api/user/toolkits/{toolkit_id}` | DELETE | 删除工具集 |
|
||||
|
||||
### 自定义 Agent 接口
|
||||
|
||||
| 序号 | 接口 | 方法 | 说明 |
|
||||
|:---:|------|------|------|
|
||||
| 8 | `/api/user/custom-agents` | POST | 创建自定义 Agent（支持外部工具/工具集） |
|
||||
| 13 | `/api/user/custom-agents` | POST | 创建自定义 Agent（支持外部工具/工具集） |
|
||||
|
||||
---
|
||||
|
||||
@@ -97,96 +65,150 @@ POST /api/user/external-tools
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|-----|------|:---:|------|
|
||||
| `name` | string | ✅ | 工具名称（1-100字符） |
|
||||
| `description` | string | ❌ | 工具描述 |
|
||||
| `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` | object | ✅ | 认证配置（见下方示例） |
|
||||
| `example` | object | ❌ | 请求参数示例（强烈建议提供） |
|
||||
|
||||
### 认证配置 (auth)
|
||||
> 💡 **提示**：`example` 字段帮助系统理解您的 API 参数结构，强烈建议填写。
|
||||
|
||||
### 请求格式
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "天气查询",
|
||||
"description": "查询城市天气（可选）",
|
||||
"url": "https://api.weather.com/forecast",
|
||||
"auth": {
|
||||
"type": "api_key",
|
||||
"secret": "sk-xxxxxxxxxxxx"
|
||||
},
|
||||
"example": {
|
||||
"city": "北京",
|
||||
"units": "metric"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
就这么简单。系统会自动完成剩余配置。
|
||||
|
||||
---
|
||||
|
||||
## 🔐 认证方式（三选一）
|
||||
|
||||
### 方式 A：API Key
|
||||
|
||||
#### API Key 认证
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"type": "api_key",
|
||||
"key": "sk-xxxxxxxxxxxx",
|
||||
"in": "header",
|
||||
"name": "X-API-Key"
|
||||
"secret": "your-api-key-here"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Bearer Token 认证
|
||||
### 方式 B：Bearer Token
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"type": "bearer",
|
||||
"key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
"secret": "eyJhbGciOiJIUzI1NiIs..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Basic Auth 认证
|
||||
### 方式 C：账号密码（Basic Auth）
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"type": "basic",
|
||||
"username": "admin",
|
||||
"password": "password123"
|
||||
"password": "your-password"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 请求示例
|
||||
---
|
||||
|
||||
## 📝 完整示例
|
||||
|
||||
### 示例 1：天气 API
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "weather-query-tool",
|
||||
"description": "查询天气信息的外部数据工具",
|
||||
"url": "https://api.weather.com/v1/forecast",
|
||||
"method": "POST",
|
||||
"headers": {
|
||||
"Content-Type": "application/json"
|
||||
},
|
||||
"name": "天气查询",
|
||||
"url": "https://api.weather.com/forecast",
|
||||
"auth": {
|
||||
"type": "api_key",
|
||||
"key": "sk-xxxxxxxxxxxx",
|
||||
"in": "header",
|
||||
"name": "X-API-Key"
|
||||
"secret": "sk-weather-12345"
|
||||
},
|
||||
"request_params": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": {
|
||||
"type": "string",
|
||||
"description": "城市名称",
|
||||
"required": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"timeout": 30
|
||||
"example": {
|
||||
"city": "上海"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
### 示例 2：企业内部 CRM
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "客户信息查询",
|
||||
"url": "https://crm.company.com/api/customers",
|
||||
"auth": {
|
||||
"type": "bearer",
|
||||
"secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
},
|
||||
"example": {
|
||||
"customer_id": "C12345"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 示例 3：数据库查询服务
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "销售数据查询",
|
||||
"url": "https://db.company.com/query",
|
||||
"auth": {
|
||||
"type": "basic",
|
||||
"username": "readonly",
|
||||
"password": "secure123"
|
||||
},
|
||||
"example": {
|
||||
"table": "sales",
|
||||
"date_range": "2026-01"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 响应示例
|
||||
|
||||
### 创建成功
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"name": "weather-query-tool",
|
||||
"tool_ref_id": "tool-weather-abc123",
|
||||
"name": "天气查询",
|
||||
"status": "active",
|
||||
"created_at": "2026-01-23T10:00:00Z"
|
||||
},
|
||||
"message": "外部数据工具创建成功"
|
||||
"message": "工具创建成功，可以开始使用了"
|
||||
}
|
||||
```
|
||||
|
||||
### 创建失败
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "无法连接到您提供的 API 地址，请检查 URL 是否正确"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -209,36 +231,22 @@ Content-Type: multipart/form-data
|
||||
|
||||
### JSON 文件格式
|
||||
|
||||
与创建接口的请求格式相同：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "weather-api",
|
||||
"description": "查询城市天气信息",
|
||||
"url": "https://api.weather.com/v1/forecast",
|
||||
"method": "GET",
|
||||
"name": "天气查询",
|
||||
"url": "https://api.weather.com/forecast",
|
||||
"auth": {
|
||||
"type": "api_key",
|
||||
"key": "your-weather-api-key",
|
||||
"in": "query",
|
||||
"name": "apikey"
|
||||
"secret": "sk-weather-12345"
|
||||
},
|
||||
"request_params": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": {
|
||||
"type": "string",
|
||||
"description": "城市名称",
|
||||
"required": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"timeout": 10
|
||||
"example": {
|
||||
"city": "上海"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
同创建接口
|
||||
|
||||
---
|
||||
|
||||
## 3️⃣ 获取工具列表
|
||||
@@ -266,10 +274,9 @@ GET /api/user/external-tools
|
||||
"tools": [
|
||||
{
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"name": "weather-query-tool",
|
||||
"description": "查询天气信息的外部数据工具",
|
||||
"url": "https://api.weather.com/v1/forecast",
|
||||
"method": "POST",
|
||||
"name": "天气查询",
|
||||
"description": "查询城市天气",
|
||||
"url": "https://api.weather.com/forecast",
|
||||
"auth_type": "api_key",
|
||||
"status": "active",
|
||||
"usage_count": 15,
|
||||
@@ -306,12 +313,10 @@ GET /api/user/external-tools/{tool_id}
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"name": "weather-query-tool",
|
||||
"description": "查询天气信息的外部数据工具",
|
||||
"url": "https://api.weather.com/v1/forecast",
|
||||
"method": "POST",
|
||||
"name": "天气查询",
|
||||
"description": "查询城市天气",
|
||||
"url": "https://api.weather.com/forecast",
|
||||
"auth_type": "api_key",
|
||||
"tool_ref_id": "tool-weather-abc123",
|
||||
"status": "active",
|
||||
"usage_count": 15,
|
||||
"created_at": "2026-01-23T10:00:00Z",
|
||||
@@ -320,8 +325,6 @@ GET /api/user/external-tools/{tool_id}
|
||||
}
|
||||
```
|
||||
|
||||
> **注意**：MCP-Server 只存储基本展示信息，不存储完整配置和敏感信息。
|
||||
|
||||
---
|
||||
|
||||
## 5️⃣ 更新工具配置
|
||||
@@ -334,7 +337,15 @@ PUT /api/user/external-tools/{tool_id}
|
||||
|
||||
### 请求参数
|
||||
|
||||
与创建接口相同，需要传递完整配置（因为 MCP-Server 不存储完整配置）。
|
||||
与创建接口相同，支持更新以下字段：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|-----|------|:---:|------|
|
||||
| `name` | string | ❌ | 工具名称 |
|
||||
| `description` | string | ❌ | 工具描述 |
|
||||
| `url` | string | ❌ | API 端点 URL |
|
||||
| `auth` | object | ❌ | 认证配置 |
|
||||
| `example` | object | ❌ | 请求参数示例 |
|
||||
|
||||
### 响应示例
|
||||
|
||||
@@ -343,12 +354,11 @@ PUT /api/user/external-tools/{tool_id}
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"name": "weather-query-tool-v2",
|
||||
"tool_ref_id": "tool-weather-abc123-v2",
|
||||
"name": "天气查询-v2",
|
||||
"status": "active",
|
||||
"updated_at": "2026-01-23T11:00:00Z"
|
||||
},
|
||||
"message": "外部数据工具更新成功"
|
||||
"message": "工具更新成功"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -370,7 +380,7 @@ DELETE /api/user/external-tools/{tool_id}
|
||||
"data": {
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
},
|
||||
"message": "外部数据工具删除成功"
|
||||
"message": "工具删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -378,6 +388,8 @@ DELETE /api/user/external-tools/{tool_id}
|
||||
|
||||
## 7️⃣ 测试工具连接
|
||||
|
||||
创建后，您可以测试工具是否正常工作：
|
||||
|
||||
### 接口
|
||||
|
||||
```
|
||||
@@ -388,14 +400,14 @@ POST /api/user/external-tools/{tool_id}/test
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| `test_params` | object | ❌ | 测试参数 |
|
||||
| `test_input` | object | ❌ | 测试参数 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"test_params": {
|
||||
"city": "北京"
|
||||
"test_input": {
|
||||
"city": "深圳"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -412,8 +424,8 @@ POST /api/user/external-tools/{tool_id}/test
|
||||
"sample_response": {
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"city": "北京",
|
||||
"temperature": "15°C"
|
||||
"city": "深圳",
|
||||
"temperature": "22°C"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -423,239 +435,11 @@ POST /api/user/external-tools/{tool_id}/test
|
||||
|
||||
---
|
||||
|
||||
## 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 | ❌ | 自定义环境变量 |
|
||||
|
||||
### 请求示例（使用外部数据工具）
|
||||
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"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 创建成功"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ❌ 错误响应
|
||||
|
||||
### 通用格式
|
||||
|
||||
```json
|
||||
{
|
||||
"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：天气查询工具
|
||||
|
||||
```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
|
||||
},
|
||||
"units": {
|
||||
"type": "string",
|
||||
"description": "温度单位",
|
||||
"enum": ["metric", "imperial"],
|
||||
"default": "metric"
|
||||
}
|
||||
}
|
||||
},
|
||||
"timeout": 10
|
||||
}
|
||||
```
|
||||
|
||||
### 示例 2：企业内部 API
|
||||
|
||||
```json
|
||||
{
|
||||
"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：数据库查询服务
|
||||
|
||||
```json
|
||||
{
|
||||
"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。
|
||||
工具集允许您将多个外部数据工具组合在一起，方便部署自定义 Agent。
|
||||
|
||||
### 9️⃣ 创建工具集
|
||||
### 8️⃣ 创建工具集
|
||||
|
||||
```
|
||||
POST /api/user/toolkits
|
||||
@@ -700,7 +484,7 @@ POST /api/user/toolkits
|
||||
|
||||
---
|
||||
|
||||
### 🔟 获取工具集列表
|
||||
### 9️⃣ 获取工具集列表
|
||||
|
||||
```
|
||||
GET /api/user/toolkits
|
||||
@@ -738,7 +522,7 @@ GET /api/user/toolkits
|
||||
|
||||
---
|
||||
|
||||
### 1️⃣1️⃣ 获取工具集详情
|
||||
### 🔟 获取工具集详情
|
||||
|
||||
```
|
||||
GET /api/user/toolkits/{toolkit_id}
|
||||
@@ -760,18 +544,16 @@ GET /api/user/toolkits/{toolkit_id}
|
||||
"tools": [
|
||||
{
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"name": "weather-api",
|
||||
"description": "天气查询 API",
|
||||
"url": "https://api.weather.com/current",
|
||||
"method": "GET",
|
||||
"name": "天气查询",
|
||||
"description": "查询城市天气",
|
||||
"url": "https://api.weather.com/forecast",
|
||||
"status": "active"
|
||||
},
|
||||
{
|
||||
"id": "550e8400-e29b-41d4-a716-446655440001",
|
||||
"name": "stock-api",
|
||||
"description": "股票查询 API",
|
||||
"name": "股票查询",
|
||||
"description": "查询股票价格",
|
||||
"url": "https://api.stock.com/price",
|
||||
"method": "GET",
|
||||
"status": "active"
|
||||
}
|
||||
],
|
||||
@@ -784,7 +566,7 @@ GET /api/user/toolkits/{toolkit_id}
|
||||
|
||||
---
|
||||
|
||||
### 1️⃣2️⃣ 更新工具集
|
||||
### 1️⃣1️⃣ 更新工具集
|
||||
|
||||
```
|
||||
PUT /api/user/toolkits/{toolkit_id}
|
||||
@@ -800,7 +582,7 @@ PUT /api/user/toolkits/{toolkit_id}
|
||||
|
||||
---
|
||||
|
||||
### 1️⃣3️⃣ 删除工具集
|
||||
### 1️⃣2️⃣ 删除工具集
|
||||
|
||||
```
|
||||
DELETE /api/user/toolkits/{toolkit_id}
|
||||
@@ -810,34 +592,166 @@ DELETE /api/user/toolkits/{toolkit_id}
|
||||
|
||||
---
|
||||
|
||||
## 📌 在自定义 Agent 中使用工具集
|
||||
## 1️⃣3️⃣ 创建带有外部工具的自定义 Agent
|
||||
|
||||
创建自定义 Agent 时，可以通过 `toolkit` 字段指定工具集：
|
||||
### 接口
|
||||
|
||||
```
|
||||
POST /api/user/custom-agents
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|-----|------|:---:|------|
|
||||
| `name` | string | ✅ | Agent 名称（1-63字符） |
|
||||
| `description` | string | ❌ | Agent 描述 |
|
||||
| `externalTools` | string[] | ❌ | 外部数据工具 ID 列表 |
|
||||
| `toolkit` | string | ❌ | 工具集 ID |
|
||||
| `model` | string | ❌ | 使用的模型名称 |
|
||||
| `cpuRequest` | string | ❌ | CPU 请求量，默认 "100m" |
|
||||
| `memoryRequest` | string | ❌ | 内存请求量，默认 "128Mi" |
|
||||
|
||||
> 💡 **说明**：模板、环境变量等配置由系统自动处理，无需手动指定。
|
||||
|
||||
### 请求示例
|
||||
|
||||
使用外部数据工具：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-data-agent",
|
||||
"template": "custom_agent",
|
||||
"toolkit": "660e8400-e29b-41d4-a716-446655440002",
|
||||
"cpuRequest": "500m",
|
||||
"memoryRequest": "512Mi"
|
||||
"description": "我的数据处理 Agent",
|
||||
"externalTools": [
|
||||
"550e8400-e29b-41d4-a716-446655440000",
|
||||
"550e8400-e29b-41d4-a716-446655440001"
|
||||
],
|
||||
"model": "gpt-4"
|
||||
}
|
||||
```
|
||||
|
||||
也可以同时使用工具集和单独的工具（会自动合并去重）：
|
||||
使用工具集：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-data-agent",
|
||||
"toolkit": "660e8400-e29b-41d4-a716-446655440002",
|
||||
"model": "gpt-4"
|
||||
}
|
||||
```
|
||||
|
||||
同时使用工具集和单独工具（会自动合并去重）：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-data-agent",
|
||||
"template": "custom_agent",
|
||||
"toolkit": "660e8400-e29b-41d4-a716-446655440002",
|
||||
"externalTools": ["770e8400-e29b-41d4-a716-446655440003"],
|
||||
"cpuRequest": "500m",
|
||||
"memoryRequest": "512Mi"
|
||||
"model": "gpt-4"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"name": "my-data-agent",
|
||||
"namespace": "ai-agents",
|
||||
"status": "Pending",
|
||||
"servicePort": 8080,
|
||||
"accessInfo": {
|
||||
"domain": "my-data-agent.example.com",
|
||||
"domain_url": "https://my-data-agent.example.com"
|
||||
},
|
||||
"quotaRemaining": {
|
||||
"cpu": 0.9,
|
||||
"memory": 0.875
|
||||
}
|
||||
},
|
||||
"message": "自定义 Agent my-data-agent 创建成功"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**如有问题，请联系开发团队。**
|
||||
## ❌ 错误响应
|
||||
|
||||
### 通用格式
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "错误信息描述"
|
||||
}
|
||||
```
|
||||
|
||||
### 常见错误
|
||||
|
||||
| HTTP状态码 | 错误说明 |
|
||||
|-----------|---------|
|
||||
| 400 | 请求参数无效（如 URL 格式错误、名称过长等） |
|
||||
| 401 | 未登录或 Token 已过期 |
|
||||
| 403 | 没有操作权限或配额不足 |
|
||||
| 404 | 工具或工具集不存在 |
|
||||
| 409 | 工具名称已存在 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
---
|
||||
|
||||
## ❓ 常见问题
|
||||
|
||||
**Q: 我的 API 是 GET 请求，怎么办？**
|
||||
A: 不需要指定，系统会自动检测。
|
||||
|
||||
**Q: 我的 API 需要特殊的请求头怎么办？**
|
||||
A: 大多数情况下不需要。如果确实需要，请联系技术支持。
|
||||
|
||||
**Q: example 字段必须填吗？**
|
||||
A: 强烈建议填写。这帮助系统理解您的 API 参数结构。
|
||||
|
||||
**Q: 认证信息会被暴露吗？**
|
||||
A: 不会。您的认证凭证会被安全存储，不会在任何响应中返回。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 高级配置（可选）
|
||||
|
||||
对于有特殊需求的用户，可以提供额外的配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "...",
|
||||
"url": "...",
|
||||
"auth": { ... },
|
||||
"example": { ... },
|
||||
|
||||
"advanced": {
|
||||
"method": "PUT",
|
||||
"headers": { "X-Custom-Header": "value" },
|
||||
"timeout": 60
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ 注意：大多数情况下不需要使用高级配置，系统会自动处理。
|
||||
|
||||
---
|
||||
|
||||
## 📊 系统自动处理
|
||||
|
||||
以下配置由系统自动推断，您无需关心：
|
||||
|
||||
| 配置项 | 自动处理方式 |
|
||||
|--------|-------------|
|
||||
| HTTP 方法 | 通过探测 API 自动检测 |
|
||||
| Content-Type | 根据请求结构自动设置 |
|
||||
| 认证头名称和位置 | 根据认证类型自动配置 |
|
||||
| 请求参数结构 | 从 example 字段推断 |
|
||||
| 响应解析 | 通过测试调用自动检测 |
|
||||
| 超时和重试 | 使用合理默认值 |
|
||||
|
||||
---
|
||||
|
||||
**如有问题，请联系开发团队。**
|
||||
|
||||
Reference in New Issue
Block a user