AgentOS-Lite

面向多智能体系统的操作系统级用户态执行时原型。

项目简介

AgentOS-Lite 位于多智能体框架与 Linux、模型及工具资源之间，将 Agent 建模为可由 Runtime 统一创建、调度、通信、授权、观测、恢复和回收的执行对象。项目基于 openEuler/Linux 用户态能力构建，重点解决多 Agent 执行过程中的状态管理、资源治理、上下文流转和故障恢复问题，与上层 Workflow 编排框架形成清晰分工。

上层的 LangGraph、CrewAI、AutoGen AgentChat 和原生多 Agent 应用负责业务流程、角色协作或会话语义；AgentOS-Lite Runtime 负责 AgentProcess、Attempt、Invocation、ContextRef、Lease、Checkpoint 和 Trace 等运行时对象，并以 SQLite 保存权威状态。Unix Domain Socket 提供本地控制与通信通道，Runtime Console 基于权威状态生成统一观测视图。

应用场景

项目提供四个采用不同框架或执行语义的多 Agent 应用，用于验证 Runtime 的通用治理能力。

应用	上层框架或语义	Runtime 接入重点
RepoSec Workbench	LangGraph	动态修复 DAG、模型与工具调用、ContextRef、Lease 和 Trace
主机安全智能研判中心	AgentOS Native，部分决策采用 LangGraph 子流程	动态任务、Checkpoint、上下文压缩、风险语义保护、Trace 和本地模型 KV 证据
CrewNews	CrewAI 顺序 Task 结果传递	Crew/Task 映射、模型与工具治理、Context 和 Trace
TeamChat	AutoGen AgentChat `RoundRobinGroupChat`	会话隔离、本地模型单槽准入和 `waiting_user` 正常终态

TeamChat 的业务顺序为：

Team Manager
→ 回答助手
→ 审校助手
→ 整合助手
→ UserProxyAgent

TeamChat 固定接入 127.0.0.1:8080/v1 的本地 Qwen3 1.7B，并由 Runtime 统一管理模型单槽准入和会话执行状态。

主要功能

统一执行对象与生命周期：管理 Workflow、AgentProcess、Attempt 及其合法状态转换、重试、取消和终态收敛。
DAG 与动态任务：支持依赖检查、运行时派生任务、失败传播，以及无关分支继续执行。
调度与资源准入：提供单机非抢占式优先级、公平、老化、资源感知、有界绕行和反压机制，并通过 Allocation Group 与 Lease 表达资源所有权。
模型与工具调用治理：在 Provider 或工具实际执行前完成 ModelInvocation、ToolInvocation 准入，记录计量、取消、超时和资源释放。
上下文与通信：通过 AgentMessage、ContextRef 和 ContextFS 支持有序消息、内容引用、隔离、不可变快照、上下文压缩和 Semantic Guard。
故障恢复与可观测性：使用 Checkpoint、持久权威状态和 reconciliation 收敛异常状态，并从权威事实重建 Trace。
Linux 资源控制：支持 subprocess、进程组、rlimit、procfs、Unix Domain Socket，以及 systemd Delegator 管理下的 cgroup v2 CPU、内存和 pids 强制。
跨框架接入：统一接入 LangGraph、CrewAI、AutoGen AgentChat 和 AgentOS Native 应用，同时保留各框架的业务语义。

系统架构

AgentOS-Lite 系统总体架构

Runtime authority 是本项目区别于普通多 Agent 编排应用的关键边界：上层框架可以决定业务协作过程，但资源准入、执行状态、调用终态、资源所有权和故障收敛由 Runtime 统一管理。

Runtime 对象	主要职责	对应的系统概念
AgentProcess	Agent 身份、依赖、资源需求和生命周期	进程控制块
Attempt	一次具体执行、PID/PGID、超时、退出和重试	进程实例或执行代次
Allocation Group / Lease	多资源原子准入、占用与回收	资源表与租约
ModelInvocation / ToolInvocation	模型和工具调用者、准入、计量与终态	受控设备或系统调用
AgentMessage / ContextRef / ContextFS	消息、引用、隔离、快照与压缩	IPC 与文件系统
Checkpoint / Trace	恢复边界与可重建观测	检查点与审计追踪

系统环境

已验证的主要环境如下：

项目	环境
操作系统	openEuler 24.03 LTS x86_64
Linux 内核	Linux 6.6
Python	Python 3.11
资源控制	cgroup v2、systemd Delegator、rlimit、procfs
状态与通信	SQLite、Unix Domain Socket
本地模型验证	llama.cpp 与 Qwen3 1.7B

核心 Runtime 和确定性场景不要求 GPU，也不要求真实模型。cgroup v2 验证需要 Linux 主机提供相应控制器和 systemd 委托权限；本地模型、真实框架应用及外部 Provider 验证需要按场景准备可选依赖和运行环境。

依赖要求

核心 Runtime 仅依赖 Python 标准库。项目通过可选依赖安装不同框架：

dev：测试依赖；
langgraph：RepoSec 与相关 LangGraph 场景；
crewai：CrewNews；
autogen：TeamChat；
all-frameworks：一次安装全部框架应用依赖。

使用外部 Provider 时，请在本机通过环境变量或配置文件填写访问凭据；本地模型和运行数据按部署环境单独准备，不随代码仓库发布。

构建与安装

以下命令均从仓库根目录开始执行：

cd src
python3.11 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e '.[all-frameworks,dev]'

如需生成并校验离线发行 Wheel：

cd src
.venv/bin/python scripts/build_agentos_release_wheel.py --output-dir dist
.venv/bin/python scripts/verify_agentos_release_wheel.py dist/agentos_lite-*.whl

运行方法

最小 Runtime 验证

该流程使用确定性场景，不需要真实模型。首先启动 Runtime：

cd src
.venv/bin/agentosd

在另一个终端进入 src/，提交并检查 Workflow：

.venv/bin/agentctl run scenarios/software_engineering/workflow.json
.venv/bin/agentctl ps
.venv/bin/agentctl inspect --workflow WORKFLOW_ID --agent planner

其中 WORKFLOW_ID 应替换为 run 命令返回的实际值。CLI 通过 Unix Domain Socket 进入 Runtime，不直接修改 SQLite 权威状态。

Runtime Console 与四个应用

先检查各服务状态：

cd src
scripts/agentos_runtime.sh status
scripts/reposec_workbench.sh status
scripts/host_security_workbench.sh status
scripts/crew_news_workbench.sh status
scripts/autogen_teamchat.sh status
scripts/teamchat_local_model.sh status

准备好相应 Provider 后，可按顺序启动演示栈：

scripts/agentos_runtime.sh start
scripts/reposec_workbench.sh start
scripts/host_security_workbench.sh start
scripts/crew_news_workbench.sh start
scripts/autogen_teamchat.sh start

服务	默认地址
Runtime Console	`http://127.0.0.1:8765`
RepoSec Workbench	`http://127.0.0.1:8800`
主机安全智能研判中心	`http://127.0.0.1:8900`
CrewNews	`http://127.0.0.1:9000`
TeamChat	`http://127.0.0.1:9100`
TeamChat 本地模型健康检查	`http://127.0.0.1:8080/health`

Runtime Console 汇总展示四个应用的执行状态、资源关系、调用链路和 Trace；各服务脚本提供 start、stop、restart 和 status 管理入口，本地模型脚本另提供日志查看入口。

测试方法

测试及证据校验统一从仓库根目录执行：

# 校验实验协议和结果文件
tests/run_validation.sh evidence

# 验证 Runtime 核心执行链路
tests/run_validation.sh core

# 执行完整测试集
tests/run_validation.sh full

统一验证脚本会自动选择项目虚拟环境，并准备完整测试所需的冻结验证材料。测试覆盖 Runtime 生命周期、DAG、资源准入、上下文、模型与工具调用、框架适配、故障恢复和控制台契约。真实模型、cgroup v2 和 systemd Delegator 测试按照相应环境条件执行。根目录 tests/ 汇总决赛验证脚本、实验协议、结果文件和校验清单；完整单元测试与集成测试位于 src/tests/，基准和实验程序位于 src/benchmarks/ 与 src/experiments/。

验证证据

主要验证结果汇总于 tests/results/，覆盖调度、资源隔离、上下文、KV Cache、Trace、稳定性及跨框架应用等关键机制。

评审问题	代表性证据	验证内容
调度策略是否真实存在	`tests/results/scheduling/resource_aware_summary.json`	425 次测量与消融覆盖优先级、公平、老化、资源感知和反压机制
长时间运行后状态是否收敛	`tests/results/stability/formal_summary.json`	两小时稳定性实验覆盖生命周期、故障注入、资源回收和终态收敛
ContextRef 是否减少重复持久化	`tests/results/context/profile_comparison.csv`	覆盖线性、扇出、分支、动态任务和恢复拓扑
是否具有真实模型 KV 证据	`tests/results/kv_cache/cache_reuse_comparison.csv`	记录本地 llama.cpp/Qwen Provider 的 cache、timing、slot 和 save/restore 信号
Trace 故障是否影响业务事实	`tests/results/trace/projection_failure_recovery.json`	Trace 是可重建投影，失败不反向改变 Runtime 权威终态
是否承载跨框架应用	`tests/results/applications/main_application_summary.json`	LangGraph、CrewAI、AutoGen AgentChat 和 Native 应用进入统一 Runtime 治理边界

决赛提交材料

材料	位置	内容
项目说明书	`docs/项目说明书.pdf`	项目定位、系统设计、关键机制、应用实现与实验验证
项目创新说明	`docs/项目创新说明.pdf`	三项核心创新及其代码、测试和实验依据
成员分工及主要贡献说明	`docs/成员分工及主要贡献说明.pdf`	项目成员分工与主要贡献
人工智能及第三方工具使用说明	`docs/人工智能及第三方工具使用说明.pdf`	人工智能与第三方工具使用情况
决赛现场演示 PPT	`presentation/决赛现场演示PPT.pptx`	决赛答辩与现场演示材料
项目全面展示视频	`presentation/决赛演示视频-01-项目全面展示.mp4`	系统架构、四个应用与运行效果展示
核心功能展示视频	`presentation/决赛演示视频-02-核心功能展示.mp4`	Runtime Console 与核心功能演示

仓库结构

决赛版本在 master 分支以项目根目录为起点组织，统一目录及 AgentOS-Lite 内部结构如下：

项目根目录/
├── README.md                              项目总览及构建、安装、运行、测试说明
├── src/                                   项目源代码
│   ├── README.md                          源码工程安装、运行与构建说明
│   ├── agentos_lite/                      AgentOS-Lite Python 软件包
│   │   ├── runtime/                       生命周期、调度、调用治理、恢复与 Trace
│   │   ├── resource/                      Admission、Allocation Group、Lease 与资源监测
│   │   ├── context/                       ContextRef、ContextFS 与上下文存储
│   │   ├── ipc/                           Unix Domain Socket 通信
│   │   ├── store/                         SQLite 权威状态存储
│   │   ├── adapters/                      LangGraph、CrewAI 与 AutoGen 适配器
│   │   ├── cgroup_delegator/              systemd Delegator 与 cgroup v2 执行路径
│   │   ├── kv_cache/                      本地模型准入、槽位协调与 KV 证据接入
│   │   ├── runtime_console/               Runtime Console 统一观测界面
│   │   ├── reposec_workbench/             RepoSec Workbench
│   │   ├── host_security_workbench/       主机安全智能研判中心
│   │   ├── crew_news_workbench/           CrewNews
│   │   └── autogen_teamchat/              TeamChat
│   ├── scenarios/                         确定性场景和四个应用的任务定义
│   ├── scripts/                           服务管理、状态检查、构建与验收入口
│   ├── tests/                             单元、集成、资源、框架及控制台契约测试
│   ├── benchmarks/                        调度、多 Agent 与本地模型基准程序
│   ├── experiments/                       可重复实验程序
│   ├── evidence/                          Runtime 与应用验证所需的结构化结果
│   ├── third_party/                       上游快照、版本来源与许可证材料
│   ├── pyproject.toml                     Python 构建、依赖与命令入口配置
│   └── conftest.py                        Pytest 全局测试配置
├── docs/                                  决赛文档
│   ├── 项目说明书.pdf
│   ├── 项目创新说明.pdf
│   ├── 成员分工及主要贡献说明.pdf
│   ├── 人工智能及第三方工具使用说明.pdf
│   └── assets/
│       └── 系统总体架构.png               README 与决赛文档配套架构图
├── tests/                                 测试及验证材料
│   ├── README.md                          测试材料说明、执行方法和结果索引
│   ├── run_validation.sh                  核心功能、框架接入和系统能力验证入口
│   ├── protocols/                         调度、本地模型和多会话实验协议
│   ├── results/                           调度、cgroup、Context、KV、Trace 和应用验证结果
│   └── MANIFEST.sha256                    验证材料完整性校验清单
├── demo/                                  与赛道相适配的可验证交付物
│   ├── README.md                          部署条件、运行步骤和验收方法
│   ├── quickstart.sh                      安装演示包并运行确定性 Runtime 工作负载
│   ├── runner.py                          Runtime 演示驱动与结果采集
│   ├── verify.sh                          校验发行包和演示结果
│   ├── workloads/
│   │   └── native_runtime_demo.json       Native Runtime 固定演示工作负载
│   ├── expected/
│   │   └── acceptance.json                演示验收条件
│   └── release/
│       ├── agentos_lite-0.1.0-py3-none-any.whl
│       └── agentos_lite-0.1.0-py3-none-any.whl.manifest.json
├── presentation/                          决赛展示材料
│   ├── 决赛现场演示PPT.pptx
│   ├── 决赛演示视频-01-项目全面展示.mp4
│   └── 决赛演示视频-02-核心功能展示.mp4
├── 作品原创承诺书.pdf
├── .gitignore                             本地配置与运行产物忽略规则
└── .gitattributes                         仓库文本与第三方快照属性配置

已知限制

当前版本面向单机 openEuler/Linux 用户态环境，采用非抢占式调度模型。
cgroup v2 资源治理需要系统启用相应控制器，并为 Runtime 配置 systemd 委托权限。
TeamChat 本地模型演示需要预先准备 llama.cpp 和 Qwen3 1.7B 模型文件。