taijibaga/taiji-pda-v0

Fork 0

forked from xiaohei/taiji-pda-v0

Files

T

zhanggangyong f4bbe7b862 备份

2026-01-29 09:03:17 +00:00

15 KiB

Raw Blame History

外部数据工具 - 快速接入指南

版本: 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 参数结构，强烈建议填写。

请求格式

{
  "name": "天气查询",
  "description": "查询城市天气（可选）",
  "url": "https://api.weather.com/forecast",
  "auth": {
    "type": "api_key",
    "secret": "sk-xxxxxxxxxxxx"
  },
  "example": {
    "city": "北京",
    "units": "metric"
  }
}

就这么简单。系统会自动完成剩余配置。

🔐 认证方式（三选一）

方式 A：API Key

{
  "auth": {
    "type": "api_key",
    "secret": "your-api-key-here"
  }
}

方式 B：Bearer Token

{
  "auth": {
    "type": "bearer",
    "secret": "eyJhbGciOiJIUzI1NiIs..."
  }
}

方式 C：账号密码（Basic Auth）

{
  "auth": {
    "type": "basic",
    "username": "admin",
    "password": "your-password"
  }
}

📝 完整示例

示例 1：天气 API

{
  "name": "天气查询",
  "url": "https://api.weather.com/forecast",
  "auth": {
    "type": "api_key",
    "secret": "sk-weather-12345"
  },
  "example": {
    "city": "上海"
  }
}

示例 2：企业内部 CRM

{
  "name": "客户信息查询",
  "url": "https://crm.company.com/api/customers",
  "auth": {
    "type": "bearer",
    "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "example": {
    "customer_id": "C12345"
  }
}

示例 3：数据库查询服务

{
  "name": "销售数据查询",
  "url": "https://db.company.com/query",
  "auth": {
    "type": "basic",
    "username": "readonly",
    "password": "secure123"
  },
  "example": {
    "table": "sales",
    "date_range": "2026-01"
  }
}

✅ 响应示例

创建成功

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "天气查询",
    "status": "active",
    "created_at": "2026-01-23T10:00:00Z"
  },
  "message": "工具创建成功，可以开始使用了"
}

创建失败

{
  "success": false,
  "error": "无法连接到您提供的 API 地址，请检查 URL 是否正确"
}

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

接口

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

请求参数

参数	类型	必填	说明
`file`	File	✅	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

响应示例

{
  "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）

响应示例

{
  "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	❌	请求参数示例

响应示例

{
  "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}

响应示例

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

7️⃣ 测试工具连接

创建后，您可以测试工具是否正常工作：

接口

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

请求参数

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

请求示例

{
  "test_input": {
    "city": "深圳"
  }
}

响应示例

{
  "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 个）

请求示例

{
  "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": "工具集创建成功"
}

9️⃣ 获取工具集列表

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
  }
}

🔟 获取工具集详情

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": "天气查询",
        "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"

请求示例

使用单独工具：

{
  "name": "my-data-agent",
  "template": "custom_agent",
  "description": "我的数据处理 Agent",
  "externalTools": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "model": "gpt-4"
}

使用工具集：

{
  "name": "my-data-agent",
  "template": "custom_agent",
  "toolkit": "660e8400-e29b-41d4-a716-446655440002",
  "model": "gpt-4"
}

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

{
  "name": "my-data-agent",
  "template": "custom_agent",
  "toolkit": "660e8400-e29b-41d4-a716-446655440002",
  "externalTools": ["770e8400-e29b-41d4-a716-446655440003"],
  "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"
    }
  },
  "message": "自定义 Agent my-data-agent 创建成功"
}

❌ 错误响应

通用格式

{
  "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: 不会。您的认证凭证会被安全存储，不会在任何响应中返回。

🔧 高级配置（可选）

对于有特殊需求的用户，可以提供额外的配置：

{
  "name": "...",
  "url": "...",
  "auth": { ... },
  "example": { ... },
  
  "advanced": {
    "method": "PUT",
    "headers": { "X-Custom-Header": "value" },
    "timeout": 60
  }
}

⚠️ 注意：大多数情况下不需要使用高级配置，系统会自动处理。

📊 系统自动处理

以下配置由系统自动推断，您无需关心：

配置项	自动处理方式
HTTP 方法	通过探测 API 自动检测
Content-Type	根据请求结构自动设置
认证头名称和位置	根据认证类型自动配置
请求参数结构	从 example 字段推断
响应解析	通过测试调用自动检测
超时和重试	使用合理默认值

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

15 KiB Raw Blame History Unescape Escape

外部数据工具 - 快速接入指南

🚀 快速开始

创建工具只需提供 4 个信息：

📑 接口列表

外部数据工具接口

工具集接口

自定义 Agent 接口

1️⃣ 创建外部数据工具

接口

请求参数

请求格式

🔐 认证方式（三选一）

方式 A：API Key

方式 B：Bearer Token

方式 C：账号密码（Basic Auth）

📝 完整示例

示例 1：天气 API

示例 2：企业内部 CRM

示例 3：数据库查询服务

✅ 响应示例

创建成功

创建失败

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

接口

请求参数

JSON 文件格式

3️⃣ 获取工具列表

接口

查询参数

响应示例

4️⃣ 获取工具详情

接口

路径参数

响应示例

5️⃣ 更新工具配置

接口

请求参数

响应示例

6️⃣ 删除工具

接口

响应示例

7️⃣ 测试工具连接

接口

请求参数

请求示例

响应示例

🧰 工具集接口

8️⃣ 创建工具集

请求参数

请求示例

响应示例

9️⃣ 获取工具集列表

查询参数

响应示例

🔟 获取工具集详情

响应示例

1️⃣1️⃣ 更新工具集

请求参数

1️⃣2️⃣ 删除工具集

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

接口

请求参数

请求示例

响应示例

❌ 错误响应

通用格式

常见错误

❓ 常见问题

🔧 高级配置（可选）

📊 系统自动处理

15 KiB

Raw Blame History