From 1177f696f1f7d704d91b5c0fab918734493b9e6a Mon Sep 17 00:00:00 2001 From: zhanggangyong Date: Mon, 26 Jan 2026 06:49:28 +0000 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E5=B7=A5=E5=85=B7=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Docs/Agent-Manager外部工具接口规范.md | 707 ++++++++++++++++++++++++++ 1 file changed, 707 insertions(+) create mode 100644 Docs/Agent-Manager外部工具接口规范.md diff --git a/Docs/Agent-Manager外部工具接口规范.md b/Docs/Agent-Manager外部工具接口规范.md new file mode 100644 index 0000000..c377d81 --- /dev/null +++ b/Docs/Agent-Manager外部工具接口规范.md @@ -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 | 初始版本 | +