taiji-AI-PAD/plans/agent-api-integration-plan.md

AI Agent Manager API 集成计划

概述

将项目中的 Agent 管理功能与新的 AI Agent Manager API 集成，实现真正的 Kubernetes Pod 部署和资源管控。

当前状态分析

现有实现

• Agent 数据模型 (models.py)：数据库级别的 Agent 记录
• Agent 路由 (agents.py)：CRUD 操作，无真正 K8s 部署
• 资源管控 (resource_control.py)：配额检查和速率限制
• 部署功能 (user.py:deploy_agent)：仅模拟，未实际调用 K8s

新 API 能力

• 真正的 Kubernetes Pod 创建/删除/查询
• 模板系统（echo_agent, jina_search_agent, mysql_agent 等）
• 资源配置（cpu_request, cpu_limit, memory_request, memory_limit）
• Pod 状态监控和访问信息

架构设计

flowchart TB
    subgraph Frontend[前端]
        UI[用户界面]
    end
    
    subgraph MCPServer[MCP Server]
        AgentRoutes[Agent 路由]
        ResourceControl[资源管控]
        AgentClient[Agent Manager 客户端]
        DB[(PostgreSQL)]
    end
    
    subgraph K8sCluster[Kubernetes 集群]
        AgentManager[AI Agent Manager API]
        AgentPods[Agent Pods]
    end
    
    UI --> AgentRoutes
    AgentRoutes --> ResourceControl
    ResourceControl --> AgentClient
    AgentClient --> AgentManager
    AgentManager --> AgentPods
    AgentRoutes --> DB

实施任务清单

阶段一：创建 Agent Manager 客户端

• 1.1 创建 services/mcp-server/app/agent_manager_client.py

  • 封装对 AI Agent Manager API 的 HTTP 调用
  • 支持健康检查、模板列表、创建/删除/查询 Agent
  • 使用 httpx 异步客户端
  • 配置通过环境变量 AGENT_MANAGER_URL 设置

• 1.2 创建请求/响应模型（集成到 schemas.py）

  • K8sResourceConfig（cpu_request, cpu_limit, memory_request, memory_limit, env）
  • AgentStatusResponse（Pod 状态、IP、端点信息）
  • AgentMetricsResponse（资源使用情况）
  • TemplateInfo, TemplateListResponse

阶段二：修改 Agent 路由

• 2.1 更新 services/mcp-server/app/routes/agents.py

  • 修改 create_agent 函数：
    • 保留资源管控检查
    • 调用 Agent Manager API 创建 Pod
    • 同步更新数据库记录（添加 pod_name, pod_ip, template 等字段）
  • 新增 delete_agent 函数：调用 API 删除 Pod
  • 新增 get_agent_status 函数：获取 Pod 实时状态
  • 新增 get_agent_metrics 函数：获取资源使用情况
  • 新增 list_templates 和 get_template 函数

• 2.2 更新 Agent 数据模型 services/mcp-server/models.py

  • 添加字段：pod_name, pod_ip, template, service_port
  • 添加字段：cpu_request, cpu_limit, memory_request, memory_limit
  • 添加字段：k8s_status（Pending, Running, Failed 等）
  • 添加字段：k8s_namespace, access_url, endpoints, env_config, pod_created_at

• 2.3 创建数据库迁移脚本

  • services/mcp-server/migrations/004_add_k8s_agent_fields.sql

阶段三：更新资源管控

• 3.1 更新 services/mcp-server/app/resource_control.py

  • 添加 Agent 资源配额检查（用户可创建的 Agent 数量限制）
  • 添加 CPU/内存总量限制检查
  • 集成 Agent Manager 的 metrics API 获取实际资源使用

• 3.2 更新 services/mcp-server/app/routes/admin.py

  • 修改 update_agent_config 函数：
    • 支持更新 cpu_request, cpu_limit, memory_request, memory_limit
    • 注意：已运行的 Pod 需要重新创建才能更新资源配置

阶段四：更新用户侧功能

• 4.1 更新 services/mcp-server/app/routes/user.py

  • 修改 deploy_agent 函数：调用 Agent Manager API
  • 修改 generate_tool 函数：支持自定义资源配置（待完成）

• 4.2 更新 services/mcp-server/app/schemas.py

  • 更新 UpdateAgentConfigRequest：添加 K8s 资源配置字段

阶段五：模板管理

• 5.1 模板路由已集成到 services/mcp-server/app/routes/agents.py

  • GET /agents/templates：获取可用模板列表
  • GET /agents/templates/{name}：获取模板详情和所需环境变量

• 5.2 更新路由注册 services/mcp-server/app/routes/__init__.py（无需修改，已自动包含）

阶段六：资源监控集成

• 6.1 更新 services/mcp-server/app/routes/resource_monitoring.py

  • 集成 Agent Manager 的 /agents/{name}/metrics API
  • 提供实时 Pod 资源使用数据

• 6.2 更新 services/mcp-server/app/routes/monitoring.py

  • 添加 Agent Pod 健康状态监控
  • 添加 Agent Manager 服务健康检查

阶段七：配置和部署

• 7.1 更新环境变量配置

  • .env.example：添加 AGENT_MANAGER_URL
  • services/mcp-server/config.py：添加配置项

• 7.2 更新 Kubernetes 部署配置

  • k8s/mcp-server.yaml：添加环境变量
  • k8s/configmap.yaml：添加 Agent Manager URL 配置

• 7.3 更新 Docker Compose 配置

  • docker-compose.yml：添加 Agent Manager 服务依赖

API 映射关系

MCP Server 功能	AI Agent Manager API	说明
创建 Agent	POST /agents	创建 K8s Pod
删除 Agent	DELETE /agents/{name}	删除 K8s Pod
获取 Agent 状态	GET /agents/{name}/status	获取 Pod 状态和 IP
获取资源使用	GET /agents/{name}/metrics	获取 CPU/内存配置
列出所有 Agent	GET /agents	列出所有 Pod
获取模板列表	GET /templates	获取可用模板
获取模板详情	GET /templates/{name}	获取模板所需参数

资源配置映射

用户配置	API 参数	默认值
CPU 请求	cpu_request	100m
CPU 限制	cpu_limit	500m
内存请求	memory_request	128Mi
内存限制	memory_limit	512Mi

需要新增的接口

根据业务需求，建议新增以下接口：

1. Agent 日志查询

   • GET /agents/{name}/logs - 获取 Pod 日志
   • 需要 Agent Manager API 支持

2. Agent 重启

   • POST /agents/{name}/restart - 重启 Pod
   • 可通过删除后重新创建实现

3. Agent 扩缩容

   • PUT /agents/{name}/scale - 调整副本数
   • 需要 Agent Manager API 支持 replicas 参数

4. 批量操作

   • POST /agents/batch/create - 批量创建
   • DELETE /agents/batch - 批量删除

注意事项

1. 数据一致性：数据库记录和 K8s Pod 状态需要保持同步
2. 错误处理：API 调用失败时需要回滚数据库操作
3. 权限控制：保留现有的资源管控和权限检查
4. 向后兼容：保留现有 API 接口格式，扩展返回字段

测试计划

• 单元测试：Agent Manager 客户端
• 集成测试：创建/删除/查询 Agent 流程
• 端到端测试：前端到 K8s Pod 完整流程
• 性能测试：并发创建 Agent 场景