# Agent Manager 响应格式更新说明

> **更新日期**: 2026-03-04  
> **版本**: v2.0  
> **影响范围**: MCP-Server 所有平台 Agent 模板相关接口

---

## 📋 更新概述

Agent Manager 的 `/templates/platform` 和 `/templates/custom` 接口已更新，现在返回更丰富的模板信息：

### 新增字段

| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `displayName` | string | 模板显示名称（人类可读） | "Echo 测试服务" |
| `description` | string | 模板描述 | "简单的 Echo 服务，用于测试和调试" |
| `category` | string | 模板分类 | "testing", "assistant", "database" |

### 原有字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `template` | string | 模板技术名称 |
| `port` | integer | 服务端口 |
| `env_info` | object | 环境变量配置 |

---

## 🔄 MCP-Server 更新内容

### 1. 数据模型更新

#### `agent_manager_client.py` - TemplateInfo 数据类

```python
@dataclass
class TemplateInfo:
    """
    Template Information
    
    Agent Manager now returns:
    - template: technical name (e.g., echo_agent)
    - displayName: human-readable name (e.g., "Echo 测试服务")
    - description: template description
    - category: template category (e.g., testing, assistant)
    - port: service port
    - env_info: environment variable configuration
    """
    template: str
    display_name: Optional[str] = None
    description: Optional[str] = None
    category: Optional[str] = None
    port: Optional[int] = None
    env_info: Dict[str, Any] = field(default_factory=dict)
    template_type: Optional[str] = None  # platform or custom
```

#### `schemas.py` - TemplateInfo Pydantic 模型

```python
class TemplateInfo(BaseModel):
    """模板信息"""
    template: str
    displayName: Optional[str] = None
    description: Optional[str] = None
    category: Optional[str] = None
    port: Optional[int] = None
    env_info: Dict[str, Any] = {}
```

### 2. 接口解析更新

所有调用 Agent Manager 的方法都已更新以解析新字段：

- ✅ `list_templates()`
- ✅ `list_platform_templates()`
- ✅ `list_custom_templates()`

### 3. 路由层优先级逻辑

更新了所有使用模板信息的路由，按以下优先级使用 displayName 和 description：

**优先级顺序**：
1. **数据库管理员配置** (PlatformAgentTemplateConfig 表)
2. **Agent Manager 返回值** (新增)
3. **硬编码默认值** (TEMPLATE_DISPLAY_INFO，向后兼容)

#### 影响的路由文件

- ✅ `app/routes/admin.py` - 管理员接口
  - `_get_platform_templates_from_agent_manager()`
  - `/api/admin/platform-agents/templates`
  
- ✅ `app/routes/channel.py` - 渠道接口
  - `_get_platform_templates_from_agent_manager()`
  - `_get_custom_templates_from_agent_manager()`
  - `/api/channel/available-platform-agents`
  
- ✅ `app/routes/platform_agent_quota.py` - 平台 Agent 配额接口
  - `/api/channel/available-platform-agents` (旧版)
  
- ✅ `app/routes/agents.py` - Agent 模板接口
  - `GET /templates`
  - `GET /templates/platform`
  - `GET /templates/custom`

---

## 🎯 业务影响

### ✅ 优点

1. **无需硬编码** - 不再需要在 MCP-Server 中维护 `TEMPLATE_DISPLAY_INFO` 字典
2. **动态更新** - Agent Manager 可以在运行时更新模板名称和描述
3. **多语言支持** - Agent Manager 可以根据区域返回不同语言的 displayName 和 description
4. **统一数据源** - 模板信息集中管理，避免数据不一致

### ⚠️ 向后兼容性

- **完全向后兼容** - 如果 Agent Manager 未返回 displayName/description/category，MCP-Server 会回退到使用硬编码的 `TEMPLATE_DISPLAY_INFO`
- **渐进式升级** - Agent Manager 可以逐步为每个模板添加新字段，不影响已有功能

### 🔄 数据流向

```
┌─────────────────┐
│ Agent Manager   │
│                 │
│ - template      │
│ - displayName   │ ← 新增
│ - description   │ ← 新增
│ - category      │ ← 新增
│ - port          │
│ - env_info      │
└────────┬────────┘
         │
         ↓
┌────────────────────────────┐
│ MCP-Server                 │
│                            │
│ 优先级:                    │
│ 1. DB管理员配置            │
│ 2. Agent Manager返回 ✨新  │
│ 3. 硬编码默认值(兼容)      │
└────────┬───────────────────┘
         │
         ↓
┌─────────────────────┐
│ 前端展示            │
│                     │
│ - 管理端            │
│ - 渠道端            │
│ - 用户端            │
└─────────────────────┘
```

---

## 📊 示例对比

### Agent Manager 返回格式（旧）

```json
{
  "templates": [
    {
      "template": "echo_agent",
      "port": 8000,
      "env_info": {}
    }
  ]
}
```

### Agent Manager 返回格式（新）

```json
{
  "templates": [
    {
      "template": "echo_agent",
      "displayName": "Echo 测试服务",
      "description": "简单的 Echo 服务，用于测试和调试",
      "category": "testing",
      "port": 8000,
      "env_info": {}
    }
  ]
}
```

### MCP-Server 响应格式

```json
{
  "success": true,
  "data": {
    "templates": [
      {
        "name": "echo_agent",
        "displayName": "Echo 测试服务",
        "description": "简单的 Echo 服务，用于测试和调试",
        "category": "testing",
        "version": "1.0.0",
        "port": 8000,
        "envInfo": {},
        "status": "available",
        "cpuRequest": "100m",
        "cpuLimit": "500m",
        "memoryRequest": "128Mi",
        "memoryLimit": "512Mi"
      }
    ]
  }
}
```

---

## ✅ 测试清单

### Agent Manager 端

- [ ] `/templates/platform` 返回 displayName、description、category
- [ ] `/templates/custom` 返回 displayName、description、category
- [ ] 所有现有模板都添加了这些字段
- [ ] 新增模板自动包含这些字段

### MCP-Server 端

- [x] agent_manager_client.py 正确解析新字段
- [x] schemas.py 包含新字段定义
- [x] admin.py 优先使用 Agent Manager 返回的字段
- [x] channel.py 优先使用 Agent Manager 返回的字段
- [x] platform_agent_quota.py 使用新字段
- [x] agents.py 返回新字段
- [ ] 向后兼容测试（Agent Manager 未返回新字段时）
- [ ] 前端接口测试（各端正确显示）

### 前端端

- [ ] 管理端正确显示 displayName 和 description
- [ ] 渠道端正确显示 displayName 和 description
- [ ] 用户端正确显示 displayName 和 description

---

## 🚀 部署建议

1. **先更新 Agent Manager** - 确保返回新字段
2. **部署 MCP-Server** - 支持接收新字段（已完成）
3. **验证接口** - 检查各端接口返回是否正确
4. **前端适配** - 确保前端正确使用新字段

---

## 📝 注意事项

1. **硬编码的 TEMPLATE_DISPLAY_INFO 仍然保留** - 用于向后兼容和降级逻辑
2. **数据库管理员配置优先级最高** - 管理员可以覆盖 Agent Manager 的默认值
3. **category 分类建议** - testing, assistant, development, search, database, general

---

## 🔗 相关文件

- `services/mcp-server/app/agent_manager_client.py` - Agent Manager 客户端
- `services/mcp-server/schemas.py` - API 响应模型
- `services/mcp-server/app/routes/admin.py` - 管理员路由
- `services/mcp-server/app/routes/channel.py` - 渠道路由
- `services/mcp-server/app/routes/platform_agent_quota.py` - 平台 Agent 配额路由
- `services/mcp-server/app/routes/agents.py` - Agent 模板路由
- `services/mcp-server/models.py` - 数据库模型（PlatformAgentTemplateConfig）

---

**结论**: MCP-Server 已完全适配 Agent Manager 的新响应格式，并保持向后兼容性。✅