feat: v2.2 - 简化版工具生成接口 + TOOL_API_KEY 自动注入
新增功能: - 新增 /external-tools/generate-simple 简化版接口，默认使用 AI 辅助 - AuthConfig 支持 token 字段（与 key 等效） - TOOL_API_KEY 环境变量自动注入到 K8s Deployment - use_ai 参数默认改为 True 修复: - 修复 gitee_manager.py 缩进错误 文档: - 更新 EXTERNAL_TOOL_API.md 文档到 v2.2
This commit is contained in:
zhanggangyong
+160
-4
@@ -1,6 +1,6 @@
|
||||
# 外部工具 API 文档
|
||||
|
||||
> **版本**: 2026-01-30 v2.1
|
||||
> **版本**: 2026-01-31 v2.2
|
||||
> **服务地址**: http://20.212.121.126
|
||||
> **规范参考**: [Agent-Manager外部工具接口规范](http://gitee.ath.cx:3000/xiaohei/taiji-AI-PAD/src/branch/feature/chenchen/Docs/Agent-Manager%E5%A4%96%E9%83%A8%E5%B7%A5%E5%85%B7%E6%8E%A5%E5%8F%A3%E8%A7%84%E8%8C%83.md)
|
||||
|
||||
@@ -43,6 +43,47 @@
|
||||
|
||||
---
|
||||
|
||||
## 🆕 v2.2 新增功能
|
||||
|
||||
### 1. 简化版工具生成接口 🚀
|
||||
|
||||
新增 `/external-tools/generate-simple` 接口，**默认使用 AI 辅助生成**，只需三个核心字段：
|
||||
|
||||
| 核心字段 | 说明 |
|
||||
|----------|------|
|
||||
| `url` | API 端点 URL |
|
||||
| `auth` | 认证配置（支持 `token` 和 `key` 字段） |
|
||||
| `request_body_schema` | 请求体 Schema（JSON Schema 格式） |
|
||||
|
||||
### 2. AuthConfig 增强
|
||||
|
||||
认证配置现在同时支持 `token` 和 `key` 字段（兼容更多使用习惯）：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "bearer",
|
||||
"token": "your-api-token" // 与 "key" 等效
|
||||
}
|
||||
```
|
||||
|
||||
### 3. TOOL_API_KEY 环境变量自动注入 ⭐
|
||||
|
||||
创建 Agent 时，系统会自动从工具配置中提取 API Key，并注入到 K8s Deployment 的环境变量中：
|
||||
|
||||
```yaml
|
||||
env:
|
||||
- name: TOOL_API_KEY
|
||||
value: "your-extracted-api-key"
|
||||
```
|
||||
|
||||
工具代码可以通过 `os.getenv("TOOL_API_KEY")` 获取。
|
||||
|
||||
### 4. use_ai 默认开启
|
||||
|
||||
`/external-tools/generate` 接口的 `use_ai` 参数现在默认为 `True`，AI 会更智能地生成工具代码。
|
||||
|
||||
---
|
||||
|
||||
## 🆕 v2.1 新增功能
|
||||
|
||||
### 1. 资源配置支持
|
||||
@@ -127,7 +168,8 @@ X-User-ID: <user_id> # 可选，用于计费
|
||||
|
||||
| 序号 | 接口 | 方法 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 1 | `/external-tools/generate` | POST | 生成外部数据工具 |
|
||||
| 1 | `/external-tools/generate` | POST | 生成外部数据工具（完整版） |
|
||||
| **1.1** | **`/external-tools/generate-simple`** | **POST** | **🆕 简化版工具生成（AI 辅助，推荐）** |
|
||||
| 2 | `/external-tools/{tool_ref_id}` | GET | 获取工具详情 |
|
||||
| 3 | `/external-tools/{tool_ref_id}` | PUT | 更新外部数据工具 |
|
||||
| 4 | `/external-tools/{tool_ref_id}` | DELETE | 删除外部数据工具 |
|
||||
@@ -135,8 +177,8 @@ X-User-ID: <user_id> # 可选，用于计费
|
||||
| 6 | `/external-tools/{tool_ref_id}/code` | GET | 获取生成的代码 |
|
||||
| 7 | `/external-tools/` | GET | 列出所有工具 |
|
||||
| 8 | `/external-tools/agents/create-with-tools` | POST | 创建带工具的 Agent |
|
||||
| 9 | `/external-tools/agents/{agent_ref_id}/build-status` | GET | 🆕 查询构建状态 |
|
||||
| 10 | `/external-tools/agents/{agent_ref_id}/deployment-info` | GET | 🆕 查询部署信息 |
|
||||
| 9 | `/external-tools/agents/{agent_ref_id}/build-status` | GET | 查询构建状态 |
|
||||
| 10 | `/external-tools/agents/{agent_ref_id}/deployment-info` | GET | 查询部署信息 |
|
||||
| 11 | `/agents` | POST | 创建 Agent（支持 tool_refs 字段） |
|
||||
|
||||
---
|
||||
@@ -253,6 +295,118 @@ curl -X POST http://20.212.121.126/external-tools/generate \
|
||||
|
||||
---
|
||||
|
||||
## 1.1️⃣ 🆕 简化版工具生成（推荐）
|
||||
|
||||
### 接口
|
||||
|
||||
```
|
||||
POST /external-tools/generate-simple
|
||||
```
|
||||
|
||||
### 功能描述
|
||||
|
||||
简化版工具生成接口，**默认使用 AI 辅助生成**，只需提供三个核心字段。AI 会智能理解您的配置并生成高质量的 Pydantic AI 工具代码。
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| name | string | ✅ | 工具名称（1-100 字符） |
|
||||
| url | string | ✅ | **核心字段** - API 端点 URL |
|
||||
| method | string | ❌ | HTTP 方法，默认 `POST` |
|
||||
| user_id | string | ❌ | 用户 ID，默认 `default` |
|
||||
| auth | object | ❌ | **核心字段** - 认证配置（支持 `token` 或 `key`） |
|
||||
| request_body_schema | object | ❌ | **核心字段** - 请求体 Schema（JSON Schema 格式） |
|
||||
| request_params | object | ❌ | URL 查询参数定义 |
|
||||
| headers | object | ❌ | 自定义请求头 |
|
||||
| description | string | ❌ | 工具描述（可选，AI 会自动推断） |
|
||||
| api_key | string | ❌ | LLM API Key（可选，使用系统默认） |
|
||||
|
||||
### 认证配置（支持两种字段名）
|
||||
|
||||
```json
|
||||
// 方式1: 使用 token 字段
|
||||
{
|
||||
"type": "bearer",
|
||||
"token": "your-api-token"
|
||||
}
|
||||
|
||||
// 方式2: 使用 key 字段
|
||||
{
|
||||
"type": "bearer",
|
||||
"key": "your-api-key"
|
||||
}
|
||||
```
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST http://20.212.121.126/external-tools/generate-simple \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "jina_reader",
|
||||
"url": "https://r.jina.ai/",
|
||||
"method": "POST",
|
||||
"user_id": "test-user",
|
||||
"auth": {
|
||||
"type": "bearer",
|
||||
"token": "jina_xxxxxxxxxxxxxx"
|
||||
},
|
||||
"request_body_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"url": {
|
||||
"type": "string",
|
||||
"description": "要爬取的网页URL"
|
||||
}
|
||||
},
|
||||
"required": ["url"]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"tool_ref_id": "tool-jina_reader-d57dcc49",
|
||||
"name": "jina_reader",
|
||||
"description": "调用 jina_reader API，参数: url",
|
||||
"url": "https://r.jina.ai/",
|
||||
"method": "POST",
|
||||
"has_auth": true,
|
||||
"created_at": "2026-01-30T17:25:13.855295"
|
||||
},
|
||||
"message": "工具生成成功 (AI 辅助)"
|
||||
}
|
||||
```
|
||||
|
||||
### AI 生成的代码示例
|
||||
|
||||
AI 会智能理解 API 的调用方式，例如 Jina Reader API 需要将目标 URL 拼接到路径中：
|
||||
|
||||
```python
|
||||
async def jina_reader(url: str) -> str:
|
||||
"""调用 jina_reader API 爬取网页内容"""
|
||||
api_key = os.getenv("TOOL_API_KEY", "default_key")
|
||||
|
||||
# AI 正确理解了 URL 拼接方式
|
||||
api_url = f"https://r.jina.ai/{url}"
|
||||
|
||||
headers = {
|
||||
"Authorization": f"Bearer {api_key}",
|
||||
"Content-Type": "application/json"
|
||||
}
|
||||
|
||||
async with httpx.AsyncClient(timeout=60.0) as client:
|
||||
response = await client.post(api_url, headers=headers)
|
||||
# ... 完整的错误处理
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2️⃣ 更新外部数据工具
|
||||
|
||||
### 接口
|
||||
@@ -778,3 +932,5 @@ curl "http://${DOMAIN}/"
|
||||
|------|------|----------|
|
||||
| 2026-01-29 | v1.0 | 初始版本，实现 MCP-Server 外部工具接口规范 |
|
||||
| 2026-01-29 | v2.0 | 新增回调功能（计费）、多工具支持、构建状态查询、部署信息查询 |
|
||||
| 2026-01-30 | v2.1 | 新增资源配置参数（cpu_request, cpu_limit, memory_request, memory_limit, replicas） |
|
||||
| 2026-01-31 | v2.2 | 🆕 新增简化版工具生成接口 `/generate-simple`、AuthConfig 支持 `token` 字段、TOOL_API_KEY 环境变量自动注入、use_ai 默认开启 |
|
||||
Reference in New Issue
Block a user