更新代码

2025-12-31 05:52:19 +00:00
parent ddecf5ec5e
commit 94b2140a2c
14 changed files with 1978 additions and 44 deletions
@@ -0,0 +1,191 @@
+# AI Agent Manager API 集成计划
+
+## 概述
+
+将项目中的 Agent 管理功能与新的 AI Agent Manager API 集成，实现真正的 Kubernetes Pod 部署和资源管控。
+
+## 当前状态分析
+
+### 现有实现
+- **Agent 数据模型** ([`models.py`](../services/mcp-server/models.py:122))：数据库级别的 Agent 记录
+- **Agent 路由** ([`agents.py`](../services/mcp-server/app/routes/agents.py:1))：CRUD 操作，无真正 K8s 部署
+- **资源管控** ([`resource_control.py`](../services/mcp-server/app/resource_control.py:1))：配额检查和速率限制
+- **部署功能** ([`user.py:deploy_agent`](../services/mcp-server/app/routes/user.py:327))：仅模拟，未实际调用 K8s
+
+### 新 API 能力
+- 真正的 Kubernetes Pod 创建/删除/查询
+- 模板系统（echo_agent, jina_search_agent, mysql_agent 等）
+- 资源配置（cpu_request, cpu_limit, memory_request, memory_limit）
+- Pod 状态监控和访问信息
+
+## 架构设计
+
+```mermaid
+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 客户端
+
+- [x] **1.1** 创建 `services/mcp-server/app/agent_manager_client.py`
+  - 封装对 AI Agent Manager API 的 HTTP 调用
+  - 支持健康检查、模板列表、创建/删除/查询 Agent
+  - 使用 httpx 异步客户端
+  - 配置通过环境变量 `AGENT_MANAGER_URL` 设置
+
+- [x] **1.2** 创建请求/响应模型（集成到 `schemas.py`）
+  - K8sResourceConfig（cpu_request, cpu_limit, memory_request, memory_limit, env）
+  - AgentStatusResponse（Pod 状态、IP、端点信息）
+  - AgentMetricsResponse（资源使用情况）
+  - TemplateInfo, TemplateListResponse
+
+### 阶段二：修改 Agent 路由
+
+- [x] **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` 函数
+
+- [x] **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`
+
+- [x] **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 获取实际资源使用
+
+- [x] **3.2** 更新 `services/mcp-server/app/routes/admin.py`
+  - 修改 `update_agent_config` 函数：
+    - 支持更新 cpu_request, cpu_limit, memory_request, memory_limit
+    - 注意：已运行的 Pod 需要重新创建才能更新资源配置
+
+### 阶段四：更新用户侧功能
+
+- [x] **4.1** 更新 `services/mcp-server/app/routes/user.py`
+  - 修改 `deploy_agent` 函数：调用 Agent Manager API
+  - 修改 `generate_tool` 函数：支持自定义资源配置（待完成）
+
+- [x] **4.2** 更新 `services/mcp-server/app/schemas.py`
+  - 更新 `UpdateAgentConfigRequest`：添加 K8s 资源配置字段
+
+### 阶段五：模板管理
+
+- [x] **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 服务健康检查
+
+### 阶段七：配置和部署
+
+- [x] **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 场景