# 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 | 初始版本 |