更新工具说明文档

2026-01-26 06:49:28 +00:00
parent fe69a70a3a
commit 1177f696f1
1 changed files with 707 additions and 0 deletions
@@ -0,0 +1,707 @@
+# Agent Manager 外部工具接口规范
+
+> **版本**: 2026-01-26 v1.0  
+> **用途**: 本文档描述 MCP-Server 期望 Agent Manager 提供的接口规范  
+> **调用方**: MCP-Server  
+> **服务方**: Agent Manager
+
+---
+
+## 📊 系统架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────────┐
+│                              系统交互流程                                             │
+├─────────────────────────────────────────────────────────────────────────────────────┤
+│                                                                                     │
+│   ┌─────────────┐         ┌─────────────────┐         ┌─────────────────┐          │
+│   │   前端      │   ───→  │   MCP-Server    │   ───→  │  Agent Manager  │          │
+│   │   用户界面  │         │   (调用方)       │         │  (本文档规范)    │          │
+│   └─────────────┘         └─────────────────┘         └─────────────────┘          │
+│                                   │                          │                     │
+│                                   ↓                          ↓                     │
+│                           ┌─────────────┐           ┌─────────────────┐           │
+│                           │  PostgreSQL │           │   工具文件存储   │           │
+│                           │  (基本信息)  │           │   AKS 部署       │           │
+│                           └─────────────┘           └─────────────────┘           │
+│                                                                                     │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 职责划分
+
+| 组件 | 职责 |
+|------|------|
+| **MCP-Server** | 接收前端请求、存储工具基本信息和 `tool_ref_id`、调用 Agent Manager 接口 |
+| **Agent Manager** | 生成 Pydantic 工具代码文件、存储完整配置（含敏感信息）、部署 Agent 到 AKS |
+
+---
+
+## 🔐 通用规范
+
+### 基础路径
+
+```
+{AGENT_MANAGER_URL}
+```
+
+MCP-Server 通过环境变量 `AGENT_MANAGER_URL` 配置 Agent Manager 地址。
+
+### 请求头
+
+```http
+Content-Type: application/json
+```
+
+### 响应格式
+
+#### 成功响应
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "message": "操作成功"
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "success": false,
+  "error": "error_code",
+  "message": "错误描述"
+}
+```
+
+---
+
+## 📑 接口列表
+
+| 序号 | 接口 | 方法 | 说明 |
+|:---:|------|------|------|
+| 1 | `/tools/generate` | POST | 生成外部数据工具 |
+| 2 | `/tools/{tool_ref_id}` | PUT | 更新外部数据工具 |
+| 3 | `/tools/{tool_ref_id}` | DELETE | 删除外部数据工具 |
+| 4 | `/tools/{tool_ref_id}/test` | POST | 测试工具连接 |
+| 5 | `/agents` | POST | 创建 Agent（新增 tool_refs 字段） |
+
+---
+
+## 1️⃣ 生成外部数据工具
+
+### 接口
+
+```
+POST /tools/generate
+```
+
+### 功能描述
+
+MCP-Server 将用户配置的工具信息发送给 Agent Manager，Agent Manager 需要：
+1. 验证配置格式
+2. 根据配置生成 Pydantic AI 工具代码文件
+3. 存储工具代码文件和完整配置（包含敏感信息如 API Key）
+4. 返回唯一的 `tool_ref_id` 供后续引用
+
+### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| `name` | string | ✅ | 工具名称（1-100 字符，将用于生成 Python 函数名） |
+| `description` | string | ✅ | 工具描述（将作为工具的 docstring） |
+| `url` | string | ✅ | API 端点 URL |
+| `method` | string | ✅ | HTTP 方法：GET/POST/PUT/DELETE/PATCH |
+| `user_id` | string | ✅ | 用户 ID（UUID 格式） |
+| `tenant_id` | string | ❌ | 租户 ID（UUID 格式） |
+| `headers` | object | ❌ | 自定义请求头 |
+| `auth` | object | ❌ | 认证配置（详见下方） |
+| `request_params` | object | ❌ | URL 查询参数定义（JSON Schema 格式） |
+| `request_body` | object | ❌ | 请求体定义（JSON Schema 格式） |
+| `response_mapping` | object | ❌ | 响应字段映射 |
+| `timeout` | integer | ❌ | 超时时间（秒），默认 30 |
+| `retry` | object | ❌ | 重试配置 |
+
+### 认证配置 (auth) 结构
+
+#### API Key 认证
+
+```json
+{
+  "type": "api_key",
+  "key": "sk-xxxxxxxxxxxx",
+  "in": "header",       // 位置: header / query
+  "name": "X-API-Key"   // 参数名
+}
+```
+
+#### Bearer Token 认证
+
+```json
+{
+  "type": "bearer",
+  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+#### Basic Auth 认证
+
+```json
+{
+  "type": "basic",
+  "username": "admin",
+  "password": "password123"
+}
+```
+
+### 请求参数定义 (request_params / request_body) - JSON Schema 格式
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "city": {
+      "type": "string",
+      "description": "城市名称",
+      "required": true
+    },
+    "units": {
+      "type": "string",
+      "description": "温度单位",
+      "enum": ["metric", "imperial"],
+      "default": "metric"
+    }
+  }
+}
+```
+
+### 响应字段映射 (response_mapping)
+
+```json
+{
+  "success_field": "code",      // 成功标识字段
+  "success_value": 0,           // 成功值
+  "data_field": "data",         // 数据字段
+  "error_field": "message"      // 错误信息字段
+}
+```
+
+### 重试配置 (retry)
+
+```json
+{
+  "max_retries": 3,
+  "retry_delay": 1.0,
+  "backoff_multiplier": 2.0
+}
+```
+
+### 请求示例
+
+```json
+{
+  "name": "weather-query-tool",
+  "description": "查询城市天气信息的工具",
+  "url": "https://api.weather.com/v1/forecast",
+  "method": "POST",
+  "user_id": "550e8400-e29b-41d4-a716-446655440000",
+  "tenant_id": "660e8400-e29b-41d4-a716-446655440001",
+  "headers": {
+    "Content-Type": "application/json",
+    "Accept": "application/json"
+  },
+  "auth": {
+    "type": "api_key",
+    "key": "sk-weather-api-key-xxx",
+    "in": "header",
+    "name": "X-API-Key"
+  },
+  "request_params": {
+    "type": "object",
+    "properties": {
+      "city": {
+        "type": "string",
+        "description": "城市名称",
+        "required": true
+      }
+    }
+  },
+  "timeout": 30,
+  "retry": {
+    "max_retries": 3,
+    "retry_delay": 1.0
+  }
+}
+```
+
+### 响应示例
+
+#### 成功
+
+```json
+{
+  "success": true,
+  "tool_ref_id": "tool-weather-abc123",
+  "tool_name": "weather_query_tool",
+  "status": "active",
+  "message": "工具生成成功"
+}
+```
+
+#### 失败
+
+```json
+{
+  "success": false,
+  "error": "invalid_config",
+  "message": "工具配置无效: URL 格式不正确"
+}
+```
+
+### Agent Manager 需要完成的工作
+
+1. **验证配置**
+   - 验证 URL 格式是否有效
+   - 验证 HTTP 方法是否合法
+   - 验证 auth 配置格式
+
+2. **生成 Pydantic AI 工具代码**
+   - 根据 `name` 生成 Python 函数名（转换为 snake_case）
+   - 根据 `description` 生成 docstring
+   - 根据 `request_params` / `request_body` 生成函数参数
+   - 生成调用外部 API 的代码
+
+3. **存储**
+   - 存储生成的工具代码文件
+   - 存储完整配置（含敏感信息）
+   - 生成唯一的 `tool_ref_id`
+
+4. **返回**
+   - 返回 `tool_ref_id` 供 MCP-Server 记录关联
+
+---
+
+## 2️⃣ 更新外部数据工具
+
+### 接口
+
+```
+PUT /tools/{tool_ref_id}
+```
+
+### 路径参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `tool_ref_id` | string | 工具标识（由生成接口返回） |
+
+### 功能描述
+
+更新已有工具的配置。Agent Manager 会重新生成工具代码文件，可能返回新的 `tool_ref_id`。
+
+### 请求参数
+
+与「生成外部数据工具」接口相同。
+
+### 请求示例
+
+```json
+{
+  "name": "weather-query-tool-v2",
+  "description": "查询城市天气信息的工具（升级版）",
+  "url": "https://api.weather.com/v2/forecast",
+  "method": "POST",
+  "user_id": "550e8400-e29b-41d4-a716-446655440000",
+  "headers": {
+    "Content-Type": "application/json"
+  },
+  "auth": {
+    "type": "api_key",
+    "key": "sk-new-api-key-xxx",
+    "in": "header",
+    "name": "X-API-Key"
+  },
+  "timeout": 60
+}
+```
+
+### 响应示例
+
+#### 成功
+
+```json
+{
+  "success": true,
+  "tool_ref_id": "tool-weather-abc123-v2",
+  "status": "active",
+  "message": "工具更新成功"
+}
+```
+
+> **注意**: `tool_ref_id` 可能会变化，MCP-Server 会更新本地记录。
+
+---
+
+## 3️⃣ 删除外部数据工具
+
+### 接口
+
+```
+DELETE /tools/{tool_ref_id}
+```
+
+### 路径参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `tool_ref_id` | string | 工具标识 |
+
+### 功能描述
+
+删除工具代码文件和存储的配置。
+
+### 响应示例
+
+#### 成功
+
+```json
+{
+  "success": true,
+  "message": "工具删除成功"
+}
+```
+
+#### 失败（工具正在被使用）
+
+```json
+{
+  "success": false,
+  "error": "tool_in_use",
+  "message": "工具正在被 Agent 使用，无法删除"
+}
+```
+
+---
+
+## 4️⃣ 测试工具连接
+
+### 接口
+
+```
+POST /tools/{tool_ref_id}/test
+```
+
+### 路径参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `tool_ref_id` | string | 工具标识 |
+
+### 功能描述
+
+Agent Manager 使用存储的工具配置，尝试调用外部 API 并返回测试结果。
+
+### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| `test_params` | object | ❌ | 测试时使用的参数值 |
+
+### 请求示例
+
+```json
+{
+  "test_params": {
+    "city": "北京"
+  }
+}
+```
+
+### 响应示例
+
+#### 成功
+
+```json
+{
+  "success": true,
+  "connected": true,
+  "response_time_ms": 156,
+  "status_code": 200,
+  "sample_response": {
+    "status": "ok",
+    "data": {
+      "city": "北京",
+      "temperature": "15°C",
+      "weather": "晴"
+    }
+  }
+}
+```
+
+#### 连接失败
+
+```json
+{
+  "success": true,
+  "connected": false,
+  "response_time_ms": 5000,
+  "status_code": 0,
+  "error": "连接超时"
+}
+```
+
+---
+
+## 5️⃣ 创建带有外部工具的 Agent
+
+### 接口
+
+```
+POST /agents
+```
+
+### 功能描述
+
+这是 Agent Manager 已有的创建 Agent 接口，需要**新增 `tool_refs` 字段**支持。
+
+当 MCP-Server 传递 `tool_refs` 时，Agent Manager 需要：
+1. 加载对应的工具代码文件
+2. 将工具集成到 Agent 中
+3. 部署 Agent 到 AKS
+
+### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| `name` | string | ✅ | Agent 名称（1-63 字符，符合 K8s 命名规范） |
+| `template` | string | ✅ | Agent 模板名称 |
+| `tool_refs` | string[] | ❌ | **新增** 外部数据工具标识列表 |
+| `config` | object | ❌ | 资源配置 |
+| `env` | object | ❌ | 环境变量 |
+
+### 资源配置 (config) 结构
+
+```json
+{
+  "user_id": "550e8400-e29b-41d4-a716-446655440000",
+  "cpu_request": "100m",
+  "cpu_limit": "500m",
+  "memory_request": "128Mi",
+  "memory_limit": "512Mi",
+  "replicas": 1
+}
+```
+
+### 请求示例
+
+```json
+{
+  "name": "my-data-agent",
+  "template": "custom_agent",
+  "tool_refs": [
+    "tool-weather-abc123",
+    "tool-stock-def456"
+  ],
+  "config": {
+    "user_id": "550e8400-e29b-41d4-a716-446655440000",
+    "cpu_request": "500m",
+    "cpu_limit": "1000m",
+    "memory_request": "512Mi",
+    "memory_limit": "1Gi",
+    "replicas": 1
+  },
+  "env": {
+    "LLM_BASE_URL": "https://litellm.example.com",
+    "MODEL_NAME": "gpt-4"
+  }
+}
+```
+
+### 响应示例
+
+```json
+{
+  "success": true,
+  "name": "my-data-agent",
+  "namespace": "ai-agents",
+  "status": "Pending",
+  "created_at": "2026-01-26T10:00:00Z",
+  "template": "custom_agent",
+  "service_port": 8080,
+  "access_info": {
+    "domain": "my-data-agent.example.com",
+    "domain_url": "https://my-data-agent.example.com",
+    "ip_url": "http://10.0.0.100:8080"
+  },
+  "tools_attached": 2
+}
+```
+
+### Agent Manager 需要完成的工作
+
+1. **加载工具文件**
+   - 根据 `tool_refs` 列表查找对应的工具代码文件
+   - 验证所有工具都存在且可用
+
+2. **集成工具到 Agent**
+   - 将工具代码文件打包到 Agent 容器镜像中
+   - 或通过 ConfigMap/Volume 挂载工具文件
+
+3. **配置环境变量**
+   - 注入工具所需的认证信息（从存储的配置中读取）
+   - 合并 MCP-Server 传递的 `env`
+
+4. **部署到 AKS**
+   - 创建 Deployment/Pod
+   - 创建 Service
+   - 配置 Ingress（如需要）
+
+---
+
+## ❌ 错误码定义
+
+| HTTP 状态码 | 错误代码 | 说明 |
+|-----------|---------|------|
+| 400 | `invalid_config` | 配置格式无效 |
+| 400 | `invalid_url` | URL 格式无效 |
+| 400 | `invalid_method` | HTTP 方法无效 |
+| 400 | `invalid_auth` | 认证配置无效 |
+| 400 | `invalid_schema` | JSON Schema 格式无效 |
+| 404 | `tool_not_found` | 工具不存在 |
+| 409 | `tool_name_exists` | 工具名称已存在（同一用户下） |
+| 409 | `tool_in_use` | 工具正在被 Agent 使用 |
+| 500 | `generation_failed` | 工具代码生成失败 |
+| 500 | `deployment_failed` | Agent 部署失败 |
+
+---
+
+## 📋 Pydantic AI 工具代码生成示例
+
+以下是 Agent Manager 需要生成的工具代码示例，供参考：
+
+### 输入配置
+
+```json
+{
+  "name": "weather-query",
+  "description": "查询指定城市的天气信息",
+  "url": "https://api.weather.com/v1/current",
+  "method": "GET",
+  "auth": {
+    "type": "api_key",
+    "key": "sk-xxx",
+    "in": "query",
+    "name": "apikey"
+  },
+  "request_params": {
+    "type": "object",
+    "properties": {
+      "city": {
+        "type": "string",
+        "description": "城市名称",
+        "required": true
+      }
+    }
+  }
+}
+```
+
+### 生成的工具代码
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.tools import Tool
+import httpx
+from typing import Any, Dict
+
+async def weather_query(city: str) -> Dict[str, Any]:
+    """
+    查询指定城市的天气信息
+    
+    Args:
+        city: 城市名称
+        
+    Returns:
+        天气信息字典
+    """
+    url = "https://api.weather.com/v1/current"
+    params = {
+        "city": city,
+        "apikey": "sk-xxx"  # 从配置注入
+    }
+    
+    async with httpx.AsyncClient(timeout=30) as client:
+        response = await client.get(url, params=params)
+        response.raise_for_status()
+        return response.json()
+
+# 注册为 Pydantic AI 工具
+weather_query_tool = Tool(
+    name="weather_query",
+    description="查询指定城市的天气信息",
+    function=weather_query
+)
+```
+
+---
+
+## 📌 集成测试建议
+
+在 Agent Manager 实现完成后，建议进行以下测试：
+
+### 1. 工具生成测试
+
+```bash
+# 创建工具
+curl -X POST "${AGENT_MANAGER_URL}/tools/generate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "test-tool",
+    "description": "测试工具",
+    "url": "https://httpbin.org/get",
+    "method": "GET",
+    "user_id": "test-user-id"
+  }'
+```
+
+### 2. 工具测试
+
+```bash
+# 测试工具连接
+curl -X POST "${AGENT_MANAGER_URL}/tools/{tool_ref_id}/test" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+### 3. 带工具的 Agent 创建测试
+
+```bash
+# 创建 Agent
+curl -X POST "${AGENT_MANAGER_URL}/agents" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "test-agent",
+    "template": "custom_agent",
+    "tool_refs": ["tool-ref-id-1"],
+    "config": {
+      "cpu_request": "100m",
+      "memory_request": "128Mi"
+    }
+  }'
+```
+
+---
+
+## 📞 联系方式
+
+如有疑问，请联系 MCP-Server 开发团队。
+
+---
+
+**文档更新记录**
+
+| 日期 | 版本 | 更新内容 |
+|------|------|---------|
+| 2026-01-26 | v1.0 | 初始版本 |
+