diff --git a/外部数据工具接口文档.md b/外部数据工具接口文档.md new file mode 100644 index 0000000..a21e80c --- /dev/null +++ b/外部数据工具接口文档.md @@ -0,0 +1,757 @@ +# 外部数据工具 - 快速接入指南 + +> **版本**: 2026-01-29 v2.0 +> **基础路径**: `/api/user/external-tools` +> **认证方式**: Bearer Token（在请求头添加 `Authorization: Bearer `） +> **设计原则**: 只需 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 字段推断 | +| 响应解析 | 通过测试调用自动检测 | +| 超时和重试 | 使用合理默认值 | + +--- + +**如有问题，请联系开发团队。**