taijibaga/taiji-AI-PAD

Fork 0

forked from xiaohei/taiji-AI-PAD

Files

T

zhanggangyong a540e6d61a 更新计费

2026-03-10 06:40:38 +00:00

7.9 KiB

Raw Blame History

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 数据类

@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 模型

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：

优先级顺序：

数据库管理员配置 (PlatformAgentTemplateConfig 表)
Agent Manager 返回值 (新增)
硬编码默认值 (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

🎯 业务影响

✅ 优点

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

⚠️ 向后兼容性

完全向后兼容 - 如果 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 返回格式（旧）

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

Agent Manager 返回格式（新）

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

MCP-Server 响应格式

{
  "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 端

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

前端端

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

🚀 部署建议

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

📝 注意事项

硬编码的 TEMPLATE_DISPLAY_INFO 仍然保留 - 用于向后兼容和降级逻辑
数据库管理员配置优先级最高 - 管理员可以覆盖 Agent Manager 的默认值
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 的新响应格式，并保持向后兼容性。✅

7.9 KiB Raw Blame History Unescape Escape