AgentOS Runtime — 面向多智能体的操作系统级执行时

操作系统开源创新大赛参赛项目

新一代多智能体系统运行时，解决资源争抢、上下文冗余、执行黑盒三大痛点

✨ 核心特性

🎯 操作系统级调度仲裁：不同于纯用户态框架的”谁先抢到谁执行”，调度决策通过 KernelSchedulerAdapter 下沉到 cgroup 权重与 sched_ext 调度类，由内核真正执行资源仲裁，负载感知自动切换 LATENCY_FIRST / FAIRNESS_BALANCED 策略，内建公平性评分与饥饿告警。

⚡ 上下文零拷贝共享：多智能体场景中系统提示与项目背景大量重复，运行时维护 共享前缀缓存池，重复内容的 token 开销折算为缓存命中；超限时按依赖图布局与分段策略淘汰。Dashboard 的 Token Saved / Cache Hit Ratio 全部由真实事件流计算，可逐条回溯。

🔒 真实内核路径验证：在 openEuler 真机上完成 cgroup v2 / PSI 反馈环 / eBPF task map / sched_ext 自定义调度类 全链路验证，压力信号（PSI）回流调度器形成双向闭环，七阶段验收报告见 code/docs/。

📊 统一可观测层：调度决策、策略切换、缓存命中、公平性告警、内核探针、BPF map 更新全部落入 统一 EventLog（JSONL），Dashboard 每个 KPI 都能回溯到原始事件，实测 668 事件、7 次策略切换、12 次公平性告警。

🌐 四框架严格接入验证：OpenAI Agents SDK / LangGraph / AutoGen / CrewAI 四框架 保留框架自身编排引擎，仅模型调用层接入 ModelGateway，四框架 Native vs Runtime 对比均取得真实 usage 数据，国赛正式批次为 30 任务 × 4 框架（汇总见数据边界文档）。

🔧 工程级测试覆盖：110 个源文件、21935 行代码、112 个测试文件、1467 个测试用例全量通过，明文密钥扫描 0 处。

1. 项目背景

多智能体系统在真实部署中长期缺乏操作系统级的统一执行支撑。现有多智能体框架（LangGraph、AutoGen、CrewAI 等）停留在用户态编排层，普遍存在以下痛点：

痛点	现状	AgentOS Runtime 方案
资源争抢无仲裁	多智能体并发时”谁先抢到谁执行”，无系统级调度	调度决策下沉内核（cgroup 权重 + sched_ext），PSI 压力信号回流调度器
上下文大量冗余	每个智能体独立复制系统提示与项目背景	共享前缀缓存池 + 压缩淘汰 + 依赖图布局优化
执行过程黑盒	框架内部状态不可见，出问题难以定位	统一 EventLog，调度/缓存/公平性/内核探针全量追踪
隔离控制缺失	单个智能体失控无法限制资源占用	cgroup 层级 + PSI 反馈环，压力越限时收紧批量

AgentOS Runtime 针对这些痛点，提供一个位于「智能体框架」与「操作系统内核」之间的统一执行时层，把 任务调度、上下文管理、隔离控制、进程间通信和可观测性 收敛到同一个运行时中，并在 openEuler 真实内核上完成全链路验证。

2. 系统架构

AgentOS Runtime 系统架构

三层架构设计：

智能体框架层：OpenAI Agents SDK / LangGraph / AutoGen / CrewAI，经 ModelGateway 统一接入
运行时层（本项目）：六域协同 —— 调度域（DAG + 策略切换）、上下文域（前缀缓存 + 压缩淘汰）、通信域（MessageBus）、隔离域（cgroup/eBPF/sched_ext）、LLM 网关（多后端统一）、可观测域（EventLog）
内核层：cgroup v2 / PSI / eBPF / sched_ext（openEuler / openKylin 验证）

关键机制：决策下沉 + 压力回传的双向闭环 —— 调度器输出经 KernelSchedulerAdapter 下沉到 cgroup 权重与 sched_ext 调度类，内核侧压力信号（PSI）再经反馈环回流调度器，动态调整批量大小与并发度。

3. 核心模块详解

3.1 调度域（scheduler/）

DAG 任务图调度 + 负载感知策略切换

支持动态批量提交与运行中插入任务
根据工作负载特征自动切换策略：
- LATENCY_FIRST（延迟优先）：交互式任务，单任务快速响应
- FAIRNESS_BALANCED（公平均衡）：批量任务，避免饥饿
内建公平性评分、饥饿告警与风险控制
与纯用户态框架的本质区别：调度决策通过 KernelSchedulerAdapter 下沉到 cgroup 权重（cpu.weight）与 sched_ext 自定义调度类（三类 DSQ：LATENCY / NORMAL / BATCH），由内核真正执行资源仲裁

实测数据：

策略切换次数：7 次（stress 变体触发 LATENCY_FIRST → FAIRNESS_BALANCED）
公平性告警次数：12 次（max_batch_size=2 + delay=8s 导致任务排队饥饿）

3.2 上下文域（context/）

共享前缀缓存 + 压缩与分段淘汰 + 依赖图布局优化

多智能体场景中大量智能体共享相同的系统提示与项目背景
运行时维护共享前缀缓存池，追踪命中率，将重复内容的 token 开销折算为缓存命中
上下文超限时按分段淘汰与压缩策略回收
基于依赖图的布局优化决定「谁的上下文放在哪」，降低跨智能体冗余复制

指标口径（全部由真实事件流计算，可逐条回溯）：

Cache Hit Ratio = cache_hit / (cache_hit + cache_miss)
Token Saved：从统一 EventLog 中的 context.compressed + cache_hit_tokens 计算得出

3.3 隔离域（isolation/）

cgroup v2 + PSI 反馈环 + eBPF task map + sched_ext 自定义调度类

cgroup 层级：为智能体工作负载建立 cgroup 层级，读取 PSI（Pressure Stall Information）压力信号回流调度器，压力越限时收紧批量并降低并发
eBPF task map：固定 schema 的 BPF map 记录逐任务调度决策，内核侧可读
sched_ext 适配：自定义调度类（code/native/sched_ext/agentos_scx.bpf.c），按智能体角色划分三类 DSQ（LATENCY / NORMAL / BATCH），在 openEuler 真实内核上完成加载、调度与清理全链路验证

验证状态：

openEuler 真机验收通过（机器可读证据见 code/docs/成员A-真实内核通路验收报告.md，七阶段报告见 code/docs/checkpoints/）
内核探针事件数：3 次（每变体各 1 次）
BPF map 更新次数：20 次（调度器每次决策更新）

3.4 通信域（comm/）

MessageBus 抽象 + Unix Socket IPC

统一 MessageBus 抽象同时支持进程内传输与 Unix Socket IPC
严格 JSON 消息编解码，消息历史与负载统计内建

3.5 LLM 网关（llm/）

多后端统一网关 + 自适应请求批处理 + 前缀缓存复用

统一接管 vLLM 本地推理与云端 API（DeepSeek / OpenAI-compatible）两类后端
自适应请求批处理：根据队列深度动态调整 batch size
前缀缓存复用：跨智能体共享相同前缀，减少重复计算
故障注入/恢复路径：模拟网络抖动、超时、限流等异常场景

3.6 可观测域（events/ + dashboard/）

统一事件流 EventLog + Dashboard 证据面板

调度决策、策略切换、缓存命中、公平性告警、内核探针、BPF map 更新全部落入统一 EventLog（JSONL 格式）
Dashboard 从事件流直接计算 KPI，每个展示数字都能回溯到原始事件
支持本地 Runtime 证据 + 云端框架对比两类视图

4. 快速开始

4.1 环境要求

Python >= 3.11
（可选）openEuler 真机环境（用于内核路径验证）

4.2 安装步骤

cd code

# 安装运行时核心依赖
pip install -e .

# 云端框架对比实验依赖（可选）
pip install -e ".[cloud-bench]"

4.3 验证安装

运行全量测试（1467 个用例）：

python -m pytest

当您看到输出 1467 passed 时，表示环境已准备就绪。

4.4 启动 Dashboard

# 启动 Runtime 证据 Dashboard（本地事件 + 压力负载矩阵 + 云端框架对比）
bash scripts/run_real_dashboard.sh --port 9510

# 在浏览器中打开
open http://localhost:9510

无需任何 API key 即可查看已归档的真实实验数据。Dashboard 包含：

Tab 1 本地 Runtime 证据：EventLog 事件数、策略切换、公平性告警、Token Saved、Cache Hit Ratio、Makespan
Tab 2 云端框架对比：四框架 Native vs Runtime 的 prompt tokens、completion tokens、cache hit ratio、makespan

4.5 验证 Dashboard 数据完整性

# 验证 Dashboard 三类 API 端点（15 项检查）
bash scripts/verify_real_data.sh 9510

5. 平台适配与内核验证

平台	方式	验证内容	状态
openEuler	`code/Dockerfile.openeuler` + 真机验证	cgroup v2 / PSI / eBPF / sched_ext 全链路	✅ 七阶段验收通过
openKylin	`code/Dockerfile.openkylin`	构建与测试套件	✅ 1467 用例通过

5.1 openEuler 真实内核路径验证

七阶段递进验收（0→6，各阶段报告见 code/docs/ 与 code/docs/checkpoints/）：

阶段 0：基线保护（重构前全量测试基线固化）
阶段 1：KernelSchedulerAdapter 抽象层（调度决策统一出口）
阶段 2：真实 cgroup 控制接入 Runtime（cpu.weight 写入与回读）
阶段 3：PSI 与 cgroup 反馈闭环（压力信号回流调度器）
阶段 4：Kernel-facing BPF 与探针（固定 schema task map）
阶段 5：实验矩阵与答辩证据接入
阶段 6：最终回归与交付固化（sched_ext 三类 DSQ 全链路）

验证内核：linux-6.12.y（validated release 6.12.95-agentos-scx，见 code/native/sched_ext/README.md）。

一键验证命令：

cd code

# 容器内构建 + 测试
bash scripts/openeuler-verify.sh

# 内核路径证据一致性校验
python scripts/verify_member_a_all.py

5.2 非 openEuler 环境说明

通用 Linux：全量测试与 Dashboard 均可运行；内核路径验证需 sched_ext 支持（linux-6.12.y 及以上，构建方式见 code/native/sched_ext/README.md）。
容器方式：无真机时可用 code/Dockerfile.openeuler / code/Dockerfile.openkylin 完成构建与测试套件验证（内核相关路径在容器内自动降级为探测模式并如实记录）。

6. 实验与评测体系

6.1 工程基准：SWE-bench

流水线脚本：code/scripts/swe_bench/honest_bench.py
国赛正式批次：30 任务 × 4 框架（实验产物体积较大，未随仓库分发）
汇总口径：见 code/REAL_DATA_BOUNDARIES.md，数据规模边界与正式批次说明

6.2 系统压力负载矩阵

四类压力测试（脚本：code/scripts/run_workload_matrix.py）：AI 推理 / 编译 / 压缩 / 网络，每类对比 baseline → runtime 的 makespan、throughput、cache_hit_ratio、fault_recovered 四项指标。汇总产物 runs/workload_matrix_deepseek_real/summary.json（体积较大未随仓库分发，Dashboard 直接加载展示）。

6.3 云端框架对比

四框架严格接入对比：

框架	Native 实现	Runtime 接入方式	Token 提取方式
OpenAI Agents SDK	Agent + Runner + OpenAIChatCompletionsModel	保留 Runner 编排，模型层接入 ModelGateway	response.usage
LangGraph	StateGraph + DeepSeekBackend	保留 StateGraph 编排，Backend 接入 ModelGateway	DeepSeekBackend.usage
AutoGen	AssistantAgent + OpenAIChatCompletionClient	保留 AssistantAgent 编排，Client 接入 ModelGateway	message.models_usage
CrewAI	Agent + Task + Crew + kickoff_async	保留 Crew 编排，模型层接入 ModelGateway	CrewOutput.token_usage

数据质量：四框架 Native vs Runtime 均取得真实 usage 数据（status = “ok”，token_source = “usage”）

6.4 消融实验

逐项验证调度策略的独立贡献（code/scripts/ablation_scheduling.py），配合压力矩阵与框架对比构成三层证据链。

7. 项目结构

仓库根/
├── code/                              # 全部源代码与技术文档
│   ├── agentos/                       # 运行时核心包（110 文件，21935 行）
│   │   ├── scheduler/                 # DAG 调度、策略切换、公平性与风险控制
│   │   ├── context/                   # 前缀缓存、上下文压缩、分段淘汰、依赖布局
│   │   ├── isolation/                 # cgroup / eBPF / sched_ext 内核适配层
│   │   ├── comm/                      # MessageBus 与 Unix Socket IPC
│   │   ├── llm/                       # 模型网关、自适应批处理、vLLM 与云端后端
│   │   ├── runtime/                   # 执行引擎与故障恢复
│   │   ├── worker/                    # 工作进程生命周期管理
│   │   ├── events/                    # 统一事件流（EventLog）类型与记录
│   │   ├── fault/                     # 故障注入与恢复路径
│   │   ├── scenarios/                 # software_eng / devops / research 等内置场景
│   │   ├── benchmarks/                # 实验与统计模块
│   │   ├── dashboard/                 # 证据面板（本地 Runtime + 云端框架对比）
│   │   ├── metrics/                   # 指标聚合
│   │   ├── core/ · tools/             # 基础抽象与工具调用
│   │   └── ...
│   ├── native/sched_ext/              # sched_ext 内核侧组件（BPF C 源码 + Makefile）
│   │   ├── agentos_scx.bpf.c          # 自定义调度类（三类 DSQ）
│   │   ├── agentos_scx.c              # 用户态控制器
│   │   ├── agentos_scx_worker.c       # 压测 worker
│   │   └── Makefile                   # 构建脚本
│   ├── scripts/                       # 77 个实验、验证与演示脚本
│   │   ├── run_real_dashboard.sh      # 一键启动证据 Dashboard
│   │   ├── verify_real_data.sh        # Dashboard 三类 API 端点验证（15 项检查）
│   │   ├── run_workload_matrix.py     # 四类系统压力负载矩阵
│   │   ├── openeuler-verify.sh        # openEuler 容器内构建 + 测试
│   │   ├── verify_member_a_all.py     # 内核路径证据一致性校验
│   │   ├── swe_bench/                 # SWE-bench 工程基准流水线
│   │   ├── ablation_*.py              # 消融实验脚本
│   │   └── ...
│   ├── tests/                         # 112 个测试文件，1467 个测试用例
│   ├── examples/coding_pipeline.py    # 端到端编码流水线示例
│   ├── docs/                          # 设计文档、实验计划与分阶段验收报告
│   │   ├── 成员A-真实内核通路验收报告.md
│   │   ├── 成员A-openEuler真实环境重跑指南.md
│   │   ├── 成员A-scheduler-evidence.md
│   │   ├── 成员C-真实环境验证说明.md
│   │   └── ...
│   ├── Dockerfile.openeuler           # openEuler 构建与验证环境
│   ├── Dockerfile.openkylin           # openKylin 构建与验证环境
│   ├── README.md                      # 代码层说明与完整快速开始
│   ├── FINAL_DELIVERY.md              # 交付索引、真实数据产物清单与验证记录
│   └── REAL_DATA_BOUNDARIES.md        # 真实数据 / 参考口径边界逐项说明
├── assets/                            # 资源文件
│   └── architecture.png               # 系统架构图
├── 作品介绍PPT.pptx                    # 作品介绍演示文稿
├── 作品介绍PPT-图片版.pptx             # 作品介绍演示文稿（图片版）
├── 项目说明书.docx                     # 项目说明书
├── 原创承诺书.docx                     # 原创承诺书
├── 演示视频.mp4                        # 项目演示视频
└── README.md                          # 本文件（项目总览）

8. 工程规模与验证状态

维度	数值
运行时源码	110 个文件、21935 行
测试	112 个文件、1467 个用例，全量通过
实验与验证脚本	77 个
内核侧组件	sched_ext BPF 调度器 + 压测 worker（C）
明文密钥扫描	0 处（全历史扫描 `.env` / `.pem` / `id_rsa` / `sk-*` 模式）

测定命令见 code/FINAL_DELIVERY.md。

9. 文档导览

文档	内容
code/README.md	代码层完整说明：目录结构、快速开始、答辩证据入口
code/FINAL_DELIVERY.md	交付索引：真实数据产物清单、一键命令、验证记录与 FAQ
code/REAL_DATA_BOUNDARIES.md	真实数据 / 降级 / 参考口径逐项边界
code/docs/	设计文档、七阶段内核路径验收报告、实验计划与答辩口径
code/native/sched_ext/README.md	sched_ext 内核侧组件构建与加载说明

10. 团队分工

成员 A：内核路径（cgroup / PSI / eBPF / sched_ext）设计与验证、P1/P2 实验体系
成员 B：上下文管理、LLM 网关、云端框架对比与 SWE-bench 工程基准
成员 C：openEuler / openKylin 平台适配、真实环境验证与演示

11. 开源协议

本项目基于 Apache License 2.0 许可证开源。

12. 鸣谢

openEuler / openKylin 社区 — 国产操作系统构建与真实内核验证环境
Linux sched_ext / eBPF 子系统 — 可扩展调度类与内核可编程基础设施
vLLM — 本地推理后端与前缀缓存能力
DeepSeek — 云端模型 API 后端
pydantic / litellm / httpx / pytest — 项目核心依赖