AgentRT-Lite

AgentRT-Lite: A Lightweight Multi-Agent Runtime for openEuler

AgentRT-Lite 是一个可在 openEuler/Linux 用户态运行、同时兼容 Windows 的多智能体运行时原型。它把 Agent 表示为统一的 Agent Control Block（ACB），通过 DAG 管理依赖和优先级，用独立子进程隔离执行，以 Context-COW 保存增量上下文，并统一记录事件与指标。项目只依赖 Python 3.10+ 标准库，不需要 GPU、在线模型或外部服务。

问题背景

多 Agent 应用通常把编排、上下文和错误处理散落在业务代码中，难以回答“哪个任务正在运行、为什么被阻塞、失败后如何恢复、上下文占用多少空间”。本项目从操作系统执行时管理的视角提供一个小而完整的用户态实验平台，但不修改内核，也不声称替代 Linux CFS。

系统架构

flowchart LR
    CLI[Demo / Benchmark] --> RT[AgentRuntime]
    RT --> SCH[DAG Scheduler]
    RT --> FM[Fault Manager]
    SCH --> ACB[Agent Control Blocks]
    RT --> W1[Spawn Worker 1]
    RT --> W2[Spawn Worker 2]
    W1 --> Q[Result Queues]
    W2 --> Q
    Q --> RT
    RT --> CS[Context-COW Store]
    RT --> EB[EventBus]
    EB --> MET[JSON / CSV Metrics]

演示 DAG：

flowchart TD
    P[Planner] --> C[Coder]
    P --> D[Documenter]
    C --> T[Tester]
    T --> R[Reviewer]
    D --> R

核心创新点

统一 ACB 与状态机：一个对象描述身份、资源请求、依赖、进程、超时、重试、上下文和结果。
确定性资源感知 DAG 调度：综合 priority、依赖深度、重试惩罚、并发压力、CPU 和内存声明评分；相同输入的选择顺序稳定。
进程级故障边界：每次尝试使用 multiprocessing 的 spawn 子进程，异常和超时不会终止 Runtime 主进程。
Context-COW：SHA-256 内容寻址、zlib 压缩、增量链、内容去重、命名空间隔离及命中统计。
事件驱动可观测性：生命周期、重试、超时、上下文和工作流完成均进入带序号的历史。

Context-COW 是 Prompt/Context 层面的写时复制思想、增量存储和压缩复用，不是真实的大模型 GPU KV Cache 共享。ModelAdapter 为未来接入 vLLM 或其他推理引擎预留边界，目前 Demo 使用确定性 Python 函数/MockLLM，不发起在线请求。

Agent 生命周期

CREATED → READY → RUNNING → SUCCESS 是正常路径。运行失败且仍有预算时走 RUNNING → RETRYING → READY；超时走 RUNNING → TIMEOUT → RETRYING，预算耗尽后为 FAILED。失败分支的下游任务变为 BLOCKED，也支持 CANCELLED。每次转换均带 UTC 时间和原因，并输出到终端。

模块说明

models.py：ACB、状态枚举、转换规则和工作流结果。
scheduler.py：DAG 校验、深度计算、评分和并发/资源准入。
runtime.py、worker.py：主进程事件循环、spawn 子进程、超时终止和结果回传。
context_store.py：Context-COW 内容寻址存储。
event_bus.py、metrics.py：事件历史及 JSON/CSV 输出。
fault_manager.py：按 Agent/尝试次数注入故障和重试决策。
model_adapter.py：可扩展模型接口和离线 MockLLM。
examples/software_pipeline.py：五 Agent 软件开发流水线。

项目目录

.
├── agentrt/                 # 核心运行时
├── examples/                # 演示工作流
├── tests/                   # unittest 测试
├── docs/                    # 架构、报告、演示和提交材料
├── results/                 # 程序真实生成的 JSON/CSV
├── run_demo.py
├── run_benchmark.py
├── Dockerfile
└── PROJECT_SPEC.md

快速开始

无需安装第三方依赖：

python -m unittest discover -s tests -v
python run_demo.py
python run_demo.py --inject-failure
python run_benchmark.py --runs 5

Windows 可用 py -3 替换 python。Linux/openEuler 可用 python3。所有执行入口都有 if __name__ == "__main__": 保护，兼容 Windows spawn。

openEuler Docker：

docker build -t agentrt-lite .
docker run --rm -v "$(pwd)/results:/app/results" agentrt-lite
docker run --rm agentrt-lite python3 run_demo.py --inject-failure
docker run --rm agentrt-lite python3 -m unittest discover -s tests -v

Demo 输出解释

终端的 [STATE] 行显示 Agent 名、旧状态、新状态和原因。--inject-failure 让 Tester 第一次在子进程中抛出异常；主进程记录 AgentRetrying，第二次执行成功，Reviewer 随后完成。汇总包含总耗时、并行峰值、每个 Agent 的重试次数和上下文统计。

运行会覆盖：

results/demo_result.json：完整 ACB、转换、指标和事件；
results/events.json：便于查看的事件列表；
results/benchmark.json、results/benchmark.csv：基准汇总和逐轮原始记录。

Benchmark 方法与实际结果

run_benchmark.py 默认固定种子 2026、执行 5 轮，并以 0.4 的确定性随机故障计划生成 [true, false, false, false, true]。Baseline 串行执行、保存每步完整上下文、不压缩、不去重、失败立即停止；AgentRT-Lite 使用 DAG 并行、Context-COW、进程隔离和一次重试。计时包含 Windows 子进程启动开销。

本仓库中的结果是 2026-07-30 在 Windows、Python 3.12.13 上由程序实际运行生成：

指标	Baseline	AgentRT-Lite
平均耗时（秒）	0.2763	1.0346
工作流成功率	0.60	1.00
原始上下文字节	10,835	5,360
存储上下文字节	10,835	4,275
去重字节	0	535
压缩比（存储/原始）	1.0000	0.7976
上下文缓存命中	0	25
峰值并发 Agent	1	2

对这种仅几十毫秒的模拟任务，spawn 成本占主导，因此 AgentRT-Lite 实测更慢；数据不支持“性能加速”结论。该实验验证的是隔离、并发、故障恢复和上下文存储机制。重新运行后以 results/benchmark.json 为准，硬件和系统负载会影响耗时。

局限性

调度器只做用户态声明式资源准入，不实施内核级 CPU/内存强隔离。
EventBus 和 ContextStore 位于单一主进程内，没有持久数据库或分布式一致性。
zlib 适合验证机制，不代表生产推理系统的最佳压缩策略。
MockLLM/确定性函数不体现真实模型延迟、token 计费或生成质量。
Windows spawn 对微任务开销显著；本原型没有常驻 worker 池。
动态创建 BugFixer Agent 仅列为扩展方向，基础 Demo 使用更可靠的重试机制。

后续工作

可扩展 cgroup v2 资源约束、持久化事件日志、动态 DAG、取消传播、常驻 worker、vLLM 适配器、token 级指标和跨主机事件传输。所有扩展应保持 ModelAdapter 与 ACB 边界。

参赛作品真实性说明

本仓库实现的是 openEuler/Linux 用户态原型，不是内核级 Agent 调度器；没有实现或模拟 GPU KV Cache 管理。演示输出来自离线确定性函数，基准文件由当前程序实际运行生成，没有硬编码性能提升百分比。Dockerfile 已提供，但若本机没有 Docker，当前提交不声称镜像已经在该机器验证。