# agent-runtime

**Repository Path**: benj4m1n/agent-runtime

## Basic Information

- **Project Name**: agent-runtime
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-20
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🛠️ Kylin Agent Runtime —— 把 AI 智能体变成操作系统的「正式员工」

> **面向多智能体的操作系统级执行时** · 团队自主研发 · 基于 openKylin · 高校赛题作品

**一句话**：现有多 Agent 系统像「临时工外包队」——没编制、没工位、各干各的还抢资源。我们给它建了一座**调度大楼**：每个 AI 智能体成为操作系统的**正式员工**——有工牌（APCB）、有工位限额（cgroup）、有看资源派活的调度（资源感知）、有团队共享记忆（KV 共享）、出错了能开除但不连累全厂（容错隔离）。

---

## 🧭 项目导航（评委先看这里）

赛题核心是我们的 **OS 级运行时内核**。整个项目分四部分：

| 部分 | 目录 | 是什么 |
|------|------|--------|
| 🏆 **赛题核心** | `os_runtime/` | OS 级运行时内核（APCB / 资源感知调度 / KV 共享 / 容错 / 可观测）|
| 🤖 Agent 框架 | 根目录（Hermes） | 多 Agent 框架，运行时承载（团队自研） |
| 🧪 实验 | `experiments/` | 基准实验 + 可视化 demo + 真实数据 |
| 🖥️ 前端 | `kylin-agent/` | Qt5 端侧 AI 助手 |

> **重点看 `os_runtime/`（赛题核心）+ `experiments/`（真实数据）**。

---

## 🎯 这是什么 / 解什么题

赛题指出，现有多 Agent 系统停留在**应用层框架**，四大痛点：

| 痛点 | 大白话 |
|------|--------|
| ① 多 Agent 无统一调度 | 一群人抢一台电脑，互相拖累 |
| ② KV Cache 冗余拷贝 | 5 个人各自把同一本手册从头背 5 遍 |
| ③ 缺统一抽象 | 模型/工具/资源各管各的，一盘散沙 |
| ④ 缺系统级可观测 | 出了问题两眼一抹黑，看不见内部 |

**我们的答案**：一个 OS 级 Agent Runtime，四大机制对症下药 👇

---

## ⚡ 四大 OS 级机制（对症赛题 + 踩创新分）

### ① APCB —— Agent 的「工牌档案」（统一执行抽象）
> 对标 OS：进程控制块 `task_struct` ｜ 赛题③ ｜ 评分：**机制创新 30%**

每个 Agent 拥有**进程控制块 APCB**：ID、6 态状态机（CREATED→READY→RUNNING→BLOCKED→TERMINATED/FAILED）、资源配额、任务依赖、生命周期。Agent 不再是临时工，而是**有编制的进程**——状态转换严格校验，非法跳转即拦截。

### ② 资源感知调度 ——「看资源派活」（CFS 式调度）
> 对标 OS：Linux CFS 调度器 ｜ 赛题② ｜ 评分：**机制创新 30% + 性能 20%**

调度器读 **psutil** 实时负载 + **cgroup** 内核级配额，按系统容量派发；资源紧张时多余任务**排队等待**，而非一股脑全派（避免过载）。支持任务依赖（DAG）、动态生成子任务、抢占。

### ③ KV Cache 共享 ——「团队共享一本手册」（上下文优化）
> 对标 OS：共享内存 ｜ 赛题⑤ ｜ 评分：**性能 20%（赛题头号痛点）**

多 Agent 共享同一前缀（团队规范），经 **KVScheduler** 统一调度到 vLLM，**radix tree 前缀匹配**复用已计算的 KV Cache——谁算过的前缀，后面的 Agent 直接用，省去重复 prefill。**直击赛题头号痛点。**

### ④ 容错隔离 ——「一个出错不开除全厂」（故障边界）
> 对标 OS：进程隔离 + cgroup ｜ 赛题④ ｜ 评分：**机制创新 30% + 性能 20%**

**双重隔离**：进程级（`subprocess start_new_session`）+ 资源级（cgroup 限额）。单个 Agent 故障被**熔断**（FAILED，不再调度），不级联拖垮全局；还支持 `BLOCKED→反馈→重派→复审` 的**故障恢复**。

---

## 📊 真实性能数据（实测，非模拟）

> **踩分：性能 20% + 实验 10%**。全部真实实测，详见 [`experiments/实验数据汇总.md`](experiments/实验数据汇总.md)。

| 实验 | 对比 | 结果 | 提升 |
|------|------|------|------|
| 🔄 资源感知调度 | 16 Agent 过载 | makespan 11.2→**1.6s**，吞吐 1.43→**9.97/s** | **6.98×** |
| 🛡️ 容错隔离 | 注入 3 故障 | makespan 1.81→**0.75s**，故障 **0.3s** 隔离 | **2.4×** |
| 🧠 KV 共享（真实 vLLM）| qwen3-30b @ L40s | TTFT 111→**38ms** | **2.91×** |
| ⚙️ cgroup 硬限额（内核级）| 真实 cgroup | CPU 限流 **46%**，内存超限 **OOM kill** | 硬限额生效 |

**重点**：KV **2.91×** 是**真实 vLLM**（30B 模型，L40s GPU）实测，不是模拟——直接回应赛题头号痛点。

---

## 🏗️ 系统架构（分布式 Runtime）

```
   ┌───────────────────────────┐          ┌───────────────────────────┐
   │   openKylin 调度节点       │          │     GPU 推理节点           │
   │   （OS 级运行时内核）       │  HTTP    │    （推理加速）             │
   │  ┌───────────────────────┐ │ ───────► │  ┌───────────────────────┐ │
   │  │ APCB + 状态机         │ │          │  │ vLLM 推理引擎          │ │
   │  │ 资源感知调度器         │ │ ◄─────── │  │ APC 前缀缓存           │ │
   │  │ cgroup 资源管理       │ │  KV 共享  │  │ radix tree 前缀匹配    │ │
   │  │ 容错熔断 + 可观测      │ │          │  │ 推理请求统一调度       │ │
   │  └───────────────────────┘ │          │  └───────────────────────┘ │
   │   kylin-agent (Qt5 前端)   │          └───────────────────────────┘
   └───────────────────────────┘
```

调度与推理分离——正是 **OS 调度异构资源**（本地 CPU + 远程 GPU）的体现。

---

## 📁 目录结构

```
agent-runtime/
├─ os_runtime/           # 🧠 OS 级运行时内核（赛题核心）
│  ├─ apcb.py             #   APCB + 状态机
│  ├─ scheduler.py        #   资源感知调度
│  ├─ resource_manager.py #   cgroup + psutil
│  ├─ fault_tolerance.py  #   容错熔断
│  ├─ kv_scheduler/       #   KV 共享调度（radix tree + vLLM）
│  ├─ ipc/                #   Agent 间通信
│  └─ observer/           #   可观测（procfs + dashboard）
├─ experiments/          # 🧪 实验 + 可视化（真实数据在 results/，mock 在 results/mock/）
│  ├─ e2e_demo_viz.py     #   答辩 demo（软件工程多 Agent 协作）
│  ├─ dashboard.py        #   实时 dashboard
│  └─ cgroup_real_test.py #   cgroup 真实硬限额测试
├─ kylin-agent/          # 🖥️ Qt5 前端
└─ README.md / 实验数据汇总.md
```

---

## 🚀 运行说明

### 环境
- **OS**：openKylin（主开发）/ Ubuntu（GPU 节点）/ 通用 Linux
- **Python 3.11+**（内核）｜ **Qt5**（前端，可选）｜ **GPU + vLLM**（KV 真实，可选，无则 mock 降级）

### ① 30 秒跑起来：可视化 demo
```bash
pip install psutil
python3 experiments/e2e_demo_viz.py     # 浏览器自动开 dashboard
# PAUSE=4 python3 experiments/e2e_demo_viz.py   # 更慢，适合录视频
```
你会看到：**7 个 AI Agent 像开发团队协作**完成软件任务（需求→架构→编码/测试/文档→集成→验收），含动态子任务、KV 共享、故障熔断、反馈循环，全程 dashboard 可视化。

### ② 复现真实数据
```bash
cd experiments
python3 scheduling_benchmark.py         # 调度 6.98×
python3 fault_experiment.py             # 容错 2.4×
sudo python3 cgroup_real_test.py        # cgroup 真实硬限额（需 root）
# KV 2.91×：部署 vLLM 后跑 os_runtime/kv_scheduler/scripts/benchmark_kv.py
```

### ③ Qt5 前端
```bash
cd kylin-agent && mkdir build && cd build && cmake .. && make -j$(nproc) && ./kylin-agent
```

---

## 🎯 评分点对应（踩分自查）

| 评分维度 | 分值 | 我们的对应 |
|---------|------|-----------|
| **系统设计与机制创新** | **30%** | APCB 进程化抽象 + 资源感知调度 + 运行时层 KV 共享 + 容错恢复（四大机制均 OS 级，区别于应用层框架）|
| **功能完整性与实现深度** | **25%** | 8 核心模块全实现 + radix tree / cgroup / 状态机深入落地 + 5000+ 行测试 |
| **性能优化效果** | **20%** | 调度 **6.98×** / 容错 **2.4×** / KV **2.91×**（真实 vLLM）/ cgroup 内核级 |
| **工程实现质量** | **15%** | 分布式架构 + 模块化 `os_runtime/` + 国产 openKylin + dashboard 可观测 + 完整接口约定 |
| **实验与分析质量** | **10%** | 真实对比实验（baseline vs ours）+ 内核级 cgroup 证据 + 严谨分析（见实验数据汇总）|

---

## 👥 团队分工
- **A**：调度内核（APCB / 状态机 / 资源感知调度 / 容错 / 可观测）
- **B**：KV 共享调度（radix tree / vLLM 适配 / Agent 间通信）
- **C**：实验框架（调度/容错/资源基准 + 真实数据 + 可视化 dashboard）

## License
团队自主研发，采用 MIT 开源协议。详见 [LICENSE](LICENSE)。

---

> 💡 **一句话总结**：我们把多 Agent 系统从「应用层临时工」升级成「操作系统正式员工」——有编制、有工位、有调度、有团队记忆、出错能隔离。真实数据证明：**快 2.91× 到 6.98×**。