forked from xiaohei/taiji-pda-v0
758 lines
15 KiB
Markdown
758 lines
15 KiB
Markdown
# 外部数据工具 - 快速接入指南
|
||
|
||
> **版本**: 2026-01-29 v2.0
|
||
> **基础路径**: `/api/user/external-tools`
|
||
> **认证方式**: Bearer Token（在请求头添加 `Authorization: Bearer <JWT Token>`）
|
||
> **设计原则**: 只需 3 步，连接您的 API
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 创建工具只需提供 4 个信息：
|
||
|
||
| 信息 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| **名称** | 给工具起个名字 | `"天气查询"` |
|
||
| **API 地址** | 您的 API URL | `"https://api.weather.com/forecast"` |
|
||
| **认证方式** | 三选一 | `"api_key"` / `"bearer"` / `"basic"` |
|
||
| **认证凭证** | 您的密钥或账密 | 见下方示例 |
|
||
|
||
---
|
||
|
||
## 📑 接口列表
|
||
|
||
### 外部数据工具接口
|
||
|
||
| 序号 | 接口 | 方法 | 说明 |
|
||
|:---:|------|------|------|
|
||
| 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 | 测试工具连接 |
|
||
|
||
### 工具集接口
|
||
|
||
| 序号 | 接口 | 方法 | 说明 |
|
||
|:---:|------|------|------|
|
||
| 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 接口
|
||
|
||
| 序号 | 接口 | 方法 | 说明 |
|
||
|:---:|------|------|------|
|
||
| 13 | `/api/user/custom-agents` | POST | 创建自定义 Agent（支持外部工具/工具集） |
|
||
|
||
---
|
||
|
||
## 1️⃣ 创建外部数据工具
|
||
|
||
### 接口
|
||
|
||
```
|
||
POST /api/user/external-tools
|
||
```
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:---:|------|
|
||
| `name` | string | ✅ | 工具名称（1-100字符） |
|
||
| `description` | string | ❌ | 工具描述（帮助您记忆工具用途） |
|
||
| `url` | string | ✅ | API 端点 URL |
|
||
| `auth` | object | ✅ | 认证配置（见下方示例） |
|
||
| `example` | object | ❌ | 请求参数示例（强烈建议提供） |
|
||
|
||
> 💡 **提示**：`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
|
||
|
||
```json
|
||
{
|
||
"auth": {
|
||
"type": "api_key",
|
||
"secret": "your-api-key-here"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 方式 B：Bearer Token
|
||
|
||
```json
|
||
{
|
||
"auth": {
|
||
"type": "bearer",
|
||
"secret": "eyJhbGciOiJIUzI1NiIs..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### 方式 C：账号密码（Basic Auth）
|
||
|
||
```json
|
||
{
|
||
"auth": {
|
||
"type": "basic",
|
||
"username": "admin",
|
||
"password": "your-password"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 完整示例
|
||
|
||
### 示例 1：天气 API
|
||
|
||
```json
|
||
{
|
||
"name": "天气查询",
|
||
"url": "https://api.weather.com/forecast",
|
||
"auth": {
|
||
"type": "api_key",
|
||
"secret": "sk-weather-12345"
|
||
},
|
||
"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": "天气查询",
|
||
"status": "active",
|
||
"created_at": "2026-01-23T10:00:00Z"
|
||
},
|
||
"message": "工具创建成功，可以开始使用了"
|
||
}
|
||
```
|
||
|
||
### 创建失败
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "无法连接到您提供的 API 地址，请检查 URL 是否正确"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2️⃣ 上传 JSON 文件创建工具
|
||
|
||
### 接口
|
||
|
||
```
|
||
POST /api/user/external-tools/upload
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:---:|------|
|
||
| `file` | File | ✅ | JSON 配置文件（.json） |
|
||
|
||
### JSON 文件格式
|
||
|
||
与创建接口的请求格式相同：
|
||
|
||
```json
|
||
{
|
||
"name": "天气查询",
|
||
"url": "https://api.weather.com/forecast",
|
||
"auth": {
|
||
"type": "api_key",
|
||
"secret": "sk-weather-12345"
|
||
},
|
||
"example": {
|
||
"city": "上海"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3️⃣ 获取工具列表
|
||
|
||
### 接口
|
||
|
||
```
|
||
GET /api/user/external-tools
|
||
```
|
||
|
||
### 查询参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:---:|------|
|
||
| `status` | string | ❌ | 过滤状态：active/pending/error |
|
||
| `page` | integer | ❌ | 页码，默认 1 |
|
||
| `page_size` | integer | ❌ | 每页数量，默认 20 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"tools": [
|
||
{
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"name": "天气查询",
|
||
"description": "查询城市天气",
|
||
"url": "https://api.weather.com/forecast",
|
||
"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） |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"name": "天气查询",
|
||
"description": "查询城市天气",
|
||
"url": "https://api.weather.com/forecast",
|
||
"auth_type": "api_key",
|
||
"status": "active",
|
||
"usage_count": 15,
|
||
"created_at": "2026-01-23T10:00:00Z",
|
||
"updated_at": "2026-01-23T10:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5️⃣ 更新工具配置
|
||
|
||
### 接口
|
||
|
||
```
|
||
PUT /api/user/external-tools/{tool_id}
|
||
```
|
||
|
||
### 请求参数
|
||
|
||
与创建接口相同，支持更新以下字段：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:---:|------|
|
||
| `name` | string | ❌ | 工具名称 |
|
||
| `description` | string | ❌ | 工具描述 |
|
||
| `url` | string | ❌ | API 端点 URL |
|
||
| `auth` | object | ❌ | 认证配置 |
|
||
| `example` | object | ❌ | 请求参数示例 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"name": "天气查询-v2",
|
||
"status": "active",
|
||
"updated_at": "2026-01-23T11:00:00Z"
|
||
},
|
||
"message": "工具更新成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6️⃣ 删除工具
|
||
|
||
### 接口
|
||
|
||
```
|
||
DELETE /api/user/external-tools/{tool_id}
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "550e8400-e29b-41d4-a716-446655440000"
|
||
},
|
||
"message": "工具删除成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7️⃣ 测试工具连接
|
||
|
||
创建后，您可以测试工具是否正常工作：
|
||
|
||
### 接口
|
||
|
||
```
|
||
POST /api/user/external-tools/{tool_id}/test
|
||
```
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:---:|------|
|
||
| `test_input` | object | ❌ | 测试参数 |
|
||
|
||
### 请求示例
|
||
|
||
```json
|
||
{
|
||
"test_input": {
|
||
"city": "深圳"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"connected": true,
|
||
"response_time_ms": 156,
|
||
"status_code": 200,
|
||
"sample_response": {
|
||
"status": "ok",
|
||
"data": {
|
||
"city": "深圳",
|
||
"temperature": "22°C"
|
||
}
|
||
}
|
||
},
|
||
"message": "工具连接测试成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧰 工具集接口
|
||
|
||
工具集允许您将多个外部数据工具组合在一起，方便部署自定义 Agent。
|
||
|
||
### 8️⃣ 创建工具集
|
||
|
||
```
|
||
POST /api/user/toolkits
|
||
```
|
||
|
||
#### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:---:|------|
|
||
| `name` | string | ✅ | 工具集名称（1-100字符） |
|
||
| `description` | string | ❌ | 工具集描述 |
|
||
| `tool_ids` | string[] | ✅ | 外部数据工具 ID 列表（1-8 个） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"name": "数据分析工具集",
|
||
"description": "包含数据查询和分析相关工具",
|
||
"tool_ids": [
|
||
"550e8400-e29b-41d4-a716-446655440000",
|
||
"550e8400-e29b-41d4-a716-446655440001"
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "660e8400-e29b-41d4-a716-446655440002",
|
||
"name": "数据分析工具集",
|
||
"description": "包含数据查询和分析相关工具",
|
||
"tool_count": 2,
|
||
"created_at": "2026-01-23T10:00:00Z"
|
||
},
|
||
"message": "工具集创建成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9️⃣ 获取工具集列表
|
||
|
||
```
|
||
GET /api/user/toolkits
|
||
```
|
||
|
||
#### 查询参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:---:|------|
|
||
| `page` | integer | ❌ | 页码，默认 1 |
|
||
| `page_size` | integer | ❌ | 每页数量，默认 20，最大 100 |
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 🔟 获取工具集详情
|
||
|
||
```
|
||
GET /api/user/toolkits/{toolkit_id}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"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": "天气查询",
|
||
"description": "查询城市天气",
|
||
"url": "https://api.weather.com/forecast",
|
||
"status": "active"
|
||
},
|
||
{
|
||
"id": "550e8400-e29b-41d4-a716-446655440001",
|
||
"name": "股票查询",
|
||
"description": "查询股票价格",
|
||
"url": "https://api.stock.com/price",
|
||
"status": "active"
|
||
}
|
||
],
|
||
"usage_count": 5,
|
||
"created_at": "2026-01-23T10:00:00Z",
|
||
"updated_at": "2026-01-23T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 1️⃣1️⃣ 更新工具集
|
||
|
||
```
|
||
PUT /api/user/toolkits/{toolkit_id}
|
||
```
|
||
|
||
#### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:---:|------|
|
||
| `name` | string | ❌ | 工具集名称 |
|
||
| `description` | string | ❌ | 工具集描述 |
|
||
| `tool_ids` | string[] | ❌ | 工具 ID 列表（1-8 个） |
|
||
|
||
---
|
||
|
||
### 1️⃣2️⃣ 删除工具集
|
||
|
||
```
|
||
DELETE /api/user/toolkits/{toolkit_id}
|
||
```
|
||
|
||
> ⚠️ **注意**：删除工具集不会删除其中的工具，只是解除组合关系。
|
||
|
||
---
|
||
|
||
## 1️⃣3️⃣ 创建带有外部工具的自定义 Agent
|
||
|
||
### 接口
|
||
|
||
```
|
||
POST /api/user/custom-agents
|
||
```
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:---:|------|
|
||
| `name` | string | ✅ | Agent 名称（1-63字符） |
|
||
| `template` | string | ✅ | Agent 模板名称 |
|
||
| `description` | string | ❌ | Agent 描述 |
|
||
| `externalTools` | string[] | ❌ | 外部数据工具 ID 列表 |
|
||
| `toolkit` | string | ❌ | 工具集 ID |
|
||
| `tools` | string[] | ❌ | 内置工具 ID 列表 |
|
||
| `model` | string | ❌ | 使用的模型名称 |
|
||
| `cpuRequest` | string | ❌ | CPU 请求量，默认 "100m" |
|
||
| `memoryRequest` | string | ❌ | 内存请求量，默认 "128Mi" |
|
||
|
||
### 请求示例
|
||
|
||
使用单独工具：
|
||
|
||
```json
|
||
{
|
||
"name": "my-data-agent",
|
||
"template": "custom_agent",
|
||
"description": "我的数据处理 Agent",
|
||
"externalTools": [
|
||
"550e8400-e29b-41d4-a716-446655440000",
|
||
"550e8400-e29b-41d4-a716-446655440001"
|
||
],
|
||
"model": "gpt-4"
|
||
}
|
||
```
|
||
|
||
使用工具集：
|
||
|
||
```json
|
||
{
|
||
"name": "my-data-agent",
|
||
"template": "custom_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"],
|
||
"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"
|
||
}
|
||
},
|
||
"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 字段推断 |
|
||
| 响应解析 | 通过测试调用自动检测 |
|
||
| 超时和重试 | 使用合理默认值 |
|
||
|
||
---
|
||
|
||
**如有问题，请联系开发团队。**
|