AgentX: Command for Claude Code

Agent平台与容器管理业务集成需求文档

项目背景

AgentX平台已完成基础的容器管理功能，现需要将容器管理与Agent对话流程进行深度集成，实现用户工具的自动化部署和管理。

已完成功能

1. 容器管理基础设施

• ✅ 容器模板管理：管理员可创建和管理容器模板
• ✅ 用户容器CRUD：创建、删除、启动、停止用户容器
• ✅ 容器自动清理：1天不使用暂停，5天不使用销毁
• ✅ 容器状态管理：包括CREATING、RUNNING、STOPPED、ERROR、DELETING、DELETED、SUSPENDED
• ✅ 端口管理：自动分配外部端口，避免冲突
• ✅ 数据卷挂载：为每个用户容器创建独立数据目录

2. 工具管理基础

• ✅ 工具全局状态管理：管理员可设置工具是否为全局状态
• ✅ 工具审核流程：审核容器已在系统中默认配置，无需额外开发

核心业务集成需求

1. Agent对话流程集成

根据业务流程图，需要实现以下完整流程：

1.1 对话启动阶段

开始 → 对话 → Agent是否有工具？

• 决策点：检查当前Agent是否配置了工具
• 是：继续后续流程
• 否：直接结束对话

1.2 用户工具查询阶段

查询用户已安装工具 → 查询工具集状态

• 功能：获取当前用户已安装的工具列表
• 功能：检查工具的全局/非全局状态
• 说明：暂时不实现全局工具概念，所有工具都按非全局处理

1.3 容器管理阶段

是否注册容器？ → 创建用户容器 / 查询健康状态 → 注册容器

• 检查用户容器：判断当前用户是否已有容器
• 容器创建：如果没有容器，则创建新的用户容器
• 健康检查：如果有容器，检查容器健康状态
• 容器恢复：如果容器被暂停，自动恢复运行状态
• 重新注册：确保容器可用后注册到系统

1.4 工具部署阶段

是否部署到用户容器？ → 部署到用户容器 → 发起对话

• 部署检查：检查工具是否已部署到用户容器的MCP网关
• 自动部署：将未部署的工具部署到用户容器
• 对话启动：完成部署后启动Agent对话

2. MCP网关开发

2.1 网关架构

• 部署方式：每个用户容器内运行独立的MCP网关
• 端口配置：容器内固定8080端口，映射到宿主机随机端口
• 镜像管理：使用统一的MCP网关Docker镜像

2.2 核心接口

用户已安装工具查询

GET /mcp/tools/installed?userId={userId}
Response: {
  "code": 200,
  "data": [
    {
      "toolId": "string",
      "toolName": "string", 
      "version": "string",
      "status": "deployed|pending|error"
    }
  ]
}

工具集状态查询

GET /mcp/tools/status?userId={userId}&toolIds={toolIds}
Response: {
  "code": 200,
  "data": {
    "global": false,  // 暂时固定为false
    "tools": [
      {
        "toolId": "string",
        "deployed": true|false,
        "status": "deployed|pending|error"
      }
    ]
  }
}

工具部署接口

POST /mcp/tools/deploy
Request: {
  "userId": "string",
  "tools": [
    {
      "toolId": "string",
      "toolName": "string",
      "version": "string",
      "config": {}  // 工具配置信息
    }
  ]
}
Response: {
  "code": 200,
  "message": "部署成功",
  "data": {
    "deployedTools": ["toolId1", "toolId2"],
    "failedTools": []
  }
}