# agent-control-plane

**Repository Path**: yangchangling/agent-control-plane

## Basic Information

- **Project Name**: agent-control-plane
- **Description**: 一个专注于代理控制平面的开源项目，提供高效的资源管理和调度能力，支持多场景下的自动化控制与协同工作。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Agent 全生命周期管理及 Skills 动态加载平台

## 项目概述

AI Agent 全生命周期管理及 Skills 动态加载平台是一个基于云原生架构的 AI Agent 管理系统，提供 Agent 的完整生命周期管理（创建→路由→执行→更新→销毁）和 Skills 的动态加载能力。

### 核心目标

- 支持 Agent 全生命周期管理
- 实现 Skills 动态加载（不停机热更新）
- 保障高并发场景下的稳定性（限流、熔断、降级）
- 达到生产级可用性（99.9% SLA）

## 核心功能

### 1. Agent 生命周期管理

- **Agent 注册与创建**：用户通过前端配置创建 Agent，后端完成资源初始化
- **Agent 路由与负载均衡**：基于 Redis 实现智能路由，支持多实例负载均衡
- **Agent 执行与监控**：调用 Agent 执行任务，实时监控资源使用情况
- **Agent 更新与 Skills 动态调整**：支持动态添加/移除技能，实现不停机更新
- **Agent 注销与资源销毁**：完整清理 Agent 相关资源，确保资源释放

### 2. Skills 动态加载

- **Skills 插件化架构**：标准化可插拔功能单元
- **热加载与懒加载**：支持技能的热加载和按需懒加载
- **技能版本管理**：支持技能的多版本管理和回滚
- **技能包管理**：从 MinIO 拉取技能包，自动解压和验证

### 3. 云原生特性

- **容器化部署**：基于 Kubernetes 部署，支持弹性扩缩容
- **资源管理**：自动创建和管理 K8s 资源（Deployment、Service、HPA、ConfigMap）
- **健康检查**：内置健康检查机制，确保服务可用性
- **自动扩缩容**：基于 CPU/内存/业务指标自动扩缩容

## 技术栈

| 类别 | 技术/框架 | 版本 | 用途 |
|------|-----------|------|------|
| 后端框架 | Spring Boot | 3.2.3 | 应用主框架 |
| 数据持久化 | MyBatis Plus | 3.5.5 | ORM 框架 |
| 数据库 | MySQL | 8.0+ | 关系型数据库 |
| 缓存 | Redis | 7.0+ | 路由缓存、会话管理 |
| 容器编排 | Kubernetes | 1.24+ | 容器管理与编排 |
| 对象存储 | MinIO | 8.5.7 | 技能包存储 |
| 安全 | Spring Security | 6.0+ | 认证与授权 |
| 测试 | JUnit 5 | 5.9+ | 单元测试 |

## 系统架构

### 架构图

```mermaid
flowchart TD
    subgraph Client_Layer[客户端层]
        Client[前端应用]
    end

    subgraph Control_Plane[控制平面]
        API_Gateway[API 网关]
        Agent_Controller[Agent 控制器]
        Skill_Controller[Skill 控制器]
        Agent_Service[Agent 服务]
        Skill_Service[Skill 服务]
        K8s_Manager[K8s 资源管理器]
        Storage_Client[MinIO 存储客户端]
    end

    subgraph Data_Layer[数据层]
        MySQL[(MySQL 数据库)]
        Redis[(Redis 缓存)]
        MinIO[(MinIO 对象存储)]
    end

    subgraph Agent_Pool[Agent 池]
        Agent_1[Agent 实例 1]
        Agent_2[Agent 实例 2]
        Agent_N[Agent 实例 N]
    end

    Client -->|HTTP 请求| API_Gateway
    API_Gateway -->|路由| Agent_Controller
    API_Gateway -->|路由| Skill_Controller
    Agent_Controller -->|调用| Agent_Service
    Skill_Controller -->|调用| Skill_Service
    Agent_Service -->|操作| K8s_Manager
    Agent_Service -->|存储| Storage_Client
    Agent_Service -->|读写| MySQL
    Agent_Service -->|缓存| Redis
    Skill_Service -->|读写| MySQL
    Skill_Service -->|存储| Storage_Client
    K8s_Manager -->|管理| Agent_Pool
    Storage_Client -->|读写| MinIO
```

### 核心组件说明

1. **控制平面**：负责 Agent 的生命周期管理、技能管理和请求路由
2. **数据层**：存储 Agent 配置、技能信息和运行状态
3. **Agent 池**：运行中的 Agent 实例，处理具体的业务请求

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+
- MySQL 8.0+
- Redis 7.0+
- MinIO 8.0+
- Kubernetes 1.24+

### 本地开发

1. **克隆项目**

```bash
git clone <repository-url>
cd agent-control-plane
```

2. **配置环境变量**

复制 `application-local.yml` 文件，根据本地环境配置相应参数：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/agent_platform?useSSL=false&serverTimezone=UTC
    username: root
    password: root
  redis:
    host: localhost
    port: 6379

minio:
  endpoint: http://localhost:9000
  access-key: minioadmin
  secret-key: minioadmin
  bucket: agent-skills
```

3. **初始化数据库**

执行 `init-scripts/01-init-schema.sql` 创建数据库结构。

4. **构建项目**

```bash
mvn clean package -DskipTests
```

5. **启动应用**

```bash
java -jar target/agent-control-plane-1.0.0.jar --spring.profiles.active=local
```

## API 接口

### Agent 管理 API

| 接口 | 方法 | 路径 | 功能 |
|------|------|------|------|
| 创建 Agent | POST | /api/v1/agents | 创建新的 Agent 实例 |
| 查询 Agent 详情 | GET | /api/v1/agents/{agent_id} | 获取 Agent 详细信息 |
| 查询所有 Agent | GET | /api/v1/agents | 获取所有 Agent 列表 |
| 更新 Agent | PUT | /api/v1/agents/{agent_id} | 更新 Agent 配置 |
| 删除 Agent | DELETE | /api/v1/agents/{agent_id} | 销毁 Agent 实例 |
| 调用 Agent | POST | /api/v1/agents/{agent_id}/execute | 调用 Agent 执行任务 |
| 动态添加技能 | POST | /api/v1/agents/{agent_id}/skills | 为 Agent 添加新技能 |

### 创建 Agent 请求示例

```json
{
  "agent_name": "客服助手",
  "role_description": "专业客服Agent",
  "system_prompt": "你是一个专业的客服助手...",
  "interaction_style": "formal",
  "resource_tier": "standard",
  "skills": ["sk_123456", "sk_789012"]
}
```

### 创建 Agent 响应示例

```json
{
  "agent_id": "ag_a1b2c3d4e5f6",
  "status": "creating",
  "endpoint": "https://api.example.com/agents/ag_a1b2c3d4e5f6",
  "created_at": "2026-03-31T08:13:00Z"
}
```

## 部署指南

### Kubernetes 部署

1. **创建命名空间**

```bash
kubectl create namespace agent-pool
```

2. **部署控制平面**

```bash
kubectl apply -f k8s/control-plane-deployment.yaml
```

3. **部署基础设施**

使用 `docker-compose.infra.yml` 启动依赖服务：

```bash
docker-compose -f docker-compose.infra.yml up -d
```

### 配置说明

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| SPRING_DATASOURCE_URL | 数据库连接 URL | jdbc:mysql://localhost:3306/agent_platform |
| SPRING_REDIS_HOST | Redis 主机地址 | localhost |
| MINIO_ENDPOINT | MinIO 服务地址 | http://localhost:9000 |
| SERVER_PORT | 服务端口 | 8080 |
| AGENT_DEFAULTS_MIN_REPLICAS | Agent 最小副本数 | 1 |
| AGENT_DEFAULTS_MAX_REPLICAS | Agent 最大副本数 | 10 |

## 监控与维护

### 健康检查

- **存活检查**：`/health/live`
- **就绪检查**：`/health/ready`

### 日志管理

- 应用日志：`/var/log/agent-platform/`
- Kubernetes 日志：使用 `kubectl logs` 查看

### 常见问题

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| Agent 创建失败 | K8s 资源创建失败 | 检查 K8s 集群状态和权限 |
| 技能加载失败 | 技能包格式错误 | 检查技能包的 skill.yaml 格式 |
| 路由失败 | Redis 连接问题 | 检查 Redis 服务状态 |

## 贡献指南

1. **代码规范**：遵循 Spring Boot 代码规范
2. **提交规范**：使用 Conventional Commits 格式
3. **测试要求**：新增功能需添加相应的单元测试
4. **文档更新**：修改功能后需更新相关文档

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 联系方式

- 项目维护者：Agent Platform Team
- 邮箱：contact@agentplatform.com
- 文档：[项目文档](https://docs.agentplatform.com)