AgentOS Runtime

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

AgentOS Runtime 面向需要长期运行、动态协作并共享模型与系统资源的多 Agent 应用。传统 Workflow/Graph Agent 主要描述“任务怎样连接”，但不会天然处理优先级反转、突发任务准入、跨进程通信、Context 并发更新、模型并发配额、故障级联和运行证据留存等运行时问题。

本项目位于多 Agent 应用编排与模型、工具、中间件及操作系统资源之间，为 Agent、Task、Inference Request、Context 和异构资源提供统一的调度、准入、隔离、恢复与观测能力。它不是把 Agent 简单映射为 Linux 进程；Agent 是受 Runtime 管理的逻辑执行实例，只有 Runtime 创建的子进程才会进一步进入进程生命周期和 cgroup v2 治理。

仓库中的 Mini Smart City 是综合验证场景，用于同时触发动态任务、抢占、资源竞争、故障恢复、Redis Streams、Evidence 数据面、SUMO/TraCI 和 Dashboard 联动，不限定 Runtime 的最终业务边界。

核心能力

能力	当前实现
声明式能力注册	AgentSpec、SkillSpec、Registry、输入输出契约、ACL 与能力匹配
分层执行对象	AgentInstance 生命周期、Task/TaskSpec、InferenceRequest、ResourceClaim；AgentInstance 承担实例级控制记录职责，代码未另设名为 ACB 的类
Dynamic DAG	由外部事件和配置模板生成任务，支持硬依赖、软依赖、Join、Singleton 和运行时派生任务
OS-PARS 调度	综合优先级、Deadline、关键路径、资源压力和老化因子；支持 P0—P3 与 P2/P3 安全点抢占
统一资源治理	对 CPU、内存、进程、线程、I/O、LLM、Tool、Token、Context、消息、Shared Memory 和 Evidence 做声明、准入、租约与释放
Context Store	ctx:// 引用、Version Vector、ACL、CAS、增量读取、Append-only Log 与压缩视图
AgentBus	内存实现用于测试/降级；Redis Streams 实现支持优先级 Stream、Consumer Group、XREADGROUP/XACK、幂等与 Replay
Evidence 数据面	控制面只传递 EvidenceRef；媒体正文进入 POSIX Shared Memory 热层或受配额控制的持久层，并记录 SHA-256 与 Lineage
故障隔离与恢复	Subscriber 隔离、Circuit Breaker、下游 BLOCKED、Checkpoint、Context 版本校验、Replay、热备/冷恢复
LLMCoreManager	统一 Provider 适配、请求排队、槽位治理、优先级与迟到结果丢弃；支持 DeepSeek、Qwen、OpenAI、Anthropic 和本地 OpenAI-compatible 服务
可观测性	结构化 Event/Metric、JSONL/CSV/JSON 结果、运行回放、实验 Dashboard、Command Center 与 Digital Twin
openEuler 验证	openEuler 24.03 LTS 容器用户空间、宿主 cgroup v2、真实子进程 CPU/内存约束与资源释放检查

抢占边界：Runtime 可以在安全点挂起本地任务、回收本地槽位并丢弃过期 Provider 返回值，但“逻辑取消”不等于远端模型服务已经停止物理计算。

系统架构

flowchart TB
    subgraph A["Agent Application Layer"]
        APP["AgentSpec / SkillSpec / 场景配置"]
        CITY["Mini Smart City / Command Center / Digital Twin"]
    end
    subgraph K["Agent Kernel Layer"]
        LIFE["Agent 生命周期与 Dynamic DAG"]
        SCHED["OS-PARS Scheduler"]
        RES["ResourceClaim / ResourceManager"]
        CTX["Context Store"]
        BUS["AgentBus / Redis Streams"]
        EVD["EvidenceManager"]
        FAULT["FaultManager / Checkpoint / Replay"]
        LLM["LLMCoreManager"]
        OBS["Observability / Metrics"]
    end
    subgraph O["OS & Hardware Layer"]
        PROC["Python 子进程 / POSIX Shared Memory"]
        CG["Linux cgroup v2"]
        MID["Redis / SUMO / TraCI / Provider API"]
    end
    APP --> LIFE
    CITY --> LIFE
    LIFE --> SCHED --> RES
    LIFE --> CTX
    LIFE --> BUS
    LIFE --> EVD
    LIFE --> FAULT
    LIFE --> LLM
    RES --> PROC
    RES --> CG
    BUS --> MID
    LLM --> MID
    CITY --> MID
    LIFE --> OBS

三层职责：

• Agent Application Layer 定义 Agent、Skill、事件契约和业务场景，不直接控制底层资源。
• Agent Kernel Layer 负责生命周期、任务图、调度、资源准入、通信、Context、Evidence、模型请求、恢复和观测。
• OS & Hardware Layer 提供进程、内存、cgroup、Redis、SUMO/TraCI 与模型 Provider 等真实执行能力。

核心执行链为：

外部事件
→ 契约匹配
→ Dynamic DAG 生成 Task
→ OS-PARS 调度
→ ResourceClaim 准入
→ LLM / Context / Tool / AgentBus / Evidence 执行
→ 状态提交
→ 故障隔离与恢复
→ Metrics 与运行证据输出

Mini Smart City 验证场景

场景配置模拟暴雨条件下的道路事故和次生事件。Runtime 会按事件动态生成处置任务，组织 Police、Ambulance、FireTruck、Traffic、Signal、Bus、Taxi、Metro、Weather、Monitor、Forecast、Report、CameraModule 和 VisualEvidence 等 Agent 协同；SUMO/TraCI 提供交通世界状态，Dashboard 展示任务、调度、资源、通信和证据引用。

Evidence 媒体正文不经普通 AgentBus 广播。AgentBus 只携带轻量 EvidenceRef，消费者再按 ACL、生命周期和完整性信息读取 Shared Memory 或持久对象。

上图是交互界面示意，不作为调度机制或实验结论的独立证据；正式判断以结构化结果文件为准。

项目结构

agentos_runtime/
├── backend/
│   ├── app.py                       # FastAPI、WebSocket、结果回放与场景 API
│   ├── configs/                     # Runtime、场景、Agent 与实验配置
│   ├── core/                        # 较早的核心实现与兼容入口
│   ├── demo/                        # Command Center / 多事故场景
│   ├── evaluation/                  # SUMO 实验编排、指标与报告
│   ├── runtime_mock/                # Runtime Kernel、Agent、LLM、Context、Bus、Evidence
│   ├── scripts/                     # SUMO 演示和评测入口
│   ├── tests/                       # 后端与部署契约测试
│   └── workers/                     # Worker 进程入口
├── benchmark/                       # 多 Agent Command Center 基准
├── experiment/                      # 11 项 Runtime 机制实验、图表和测试
├── frontend/
│   ├── src/                         # Digital Twin 与页面逻辑
│   ├── public/                      # 城市静态资源及第三方许可文件
│   ├── proxy_server.py              # 构建产物与后端的同源网关
│   └── vite.config.js
├── scripts/                         # 部署、环境检查、openEuler/cgroup 与验证脚本
├── Dockerfile.openEuler
├── Dockerfile.experiment.openEuler
├── docker-compose.openeuler.yml
├── docker-compose.ports-override.yml
├── docker-compose.experiment-cgroup-openeuler.yml
├── run_in_docker.sh
├── .env.example
├── .env.experiments.api.example
└── README.md

环境要求

组件	仓库中的真实要求
Python	3.10 或更高；依赖见 backend/requirements.txt
Node.js	正式 Docker 构建使用 Node 20；本地前端使用 Vite 5 和 package-lock.json
Docker	Docker Engine/Desktop；脚本要求 Docker Compose v2 插件
Redis	Compose 使用 redis:7-alpine；正式 AgentBus/通信实验要求可用 Redis，不允许静默回退
SUMO/TraCI	Python 依赖声明 eclipse-sumo>=1.16、traci>=1.16；sumo/sumo-gui 需位于 PATH 或配置 SUMO_HOME
openEuler	Runtime 和实验镜像基于 openEuler 24.03 LTS 用户空间
cgroup	正式物理资源实验要求 Linux 宿主使用 cgroup v2，并允许专用实验容器写入受控 cgroup
LLM Provider	正式 11 项实验需要所选 Provider 的真实 Key，或可访问的本地 OpenAI-compatible Endpoint

默认宿主端口：

服务	端口
Redis	6379
Backend API	8008
Frontend / 同源 API 网关	5173

端口可通过 REDIS_PORT、BACKEND_PORT、FRONTEND_PORT 修改。Vite 开发服务器会把 /api 和 /ws 代理到 127.0.0.1:8008。

快速部署：Docker Compose

推荐在 Linux/openEuler 宿主以具备 Docker 权限的账号执行：

git clone http://cdn09022024.gitlink.org.cn/IGSaYJoVgI/mxdzntdczxtjzxsar.git agentos_runtime
cd agentos_runtime
chmod +x scripts/*.sh scripts/lib/*.sh run_in_docker.sh
./scripts/start_openeuler_stack.sh

该脚本同时加载基础 Compose 与端口映射文件，构建 openEuler Runtime 镜像，启动 Redis、Backend 和 Frontend，并等待容器健康。不要只使用基础 docker-compose.openeuler.yml 后再假设端口已经发布；端口映射定义在 docker-compose.ports-override.yml。

不使用启动脚本时，Linux、PowerShell 和 CMD 均可执行：

docker compose -f docker-compose.openeuler.yml -f docker-compose.ports-override.yml config
docker compose -f docker-compose.openeuler.yml -f docker-compose.ports-override.yml up -d --build
docker compose -f docker-compose.openeuler.yml -f docker-compose.ports-override.yml ps

启动后访问：

页面或接口	默认地址
Runtime Dashboard	http://127.0.0.1:5173/index.html
Command Center	http://127.0.0.1:5173/command.html
Digital Twin	http://127.0.0.1:5173/twin.html
实验 Dashboard	http://127.0.0.1:5173/experiments.html
AgentBus	http://127.0.0.1:5173/agentbus.html
Evidence	http://127.0.0.1:5173/evidence.html
Backend Health	http://127.0.0.1:8008/api/health
Frontend Gateway Health	http://127.0.0.1:5173/frontend-health

停止服务：

./scripts/stop_openeuler_stack.sh

或：

docker compose -f docker-compose.openeuler.yml -f docker-compose.ports-override.yml down

openEuler 与 cgroup v2 验证

Dockerfile.openEuler 和 Dockerfile.experiment.openEuler 提供 openEuler 24.03 LTS 容器用户空间；容器仍共享 Linux 宿主内核，项目没有替换或定制宿主内核。Windows 上的 Docker Desktop 运行在其 Linux VM 内核之上，不能等同于直接在 openEuler 宿主完成 cgroup 验收。

先检查宿主：

cat /etc/os-release
stat -fc %T /sys/fs/cgroup
docker version
docker compose version

stat 应输出 cgroup2fs。构建后可确认容器用户空间：

docker compose -f docker-compose.openeuler.yml -f docker-compose.ports-override.yml run --rm city-runtime cat /etc/os-release

不调用付费模型的核心机制自检：

sudo ./scripts/run_openeuler_core_smoke.sh

正式 Real LLM in the Loop 与统一物理资源实验：

cp .env.experiments.api.example .env.experiments.api
chmod 600 .env.experiments.api
# 编辑 .env.experiments.api，只填写实际使用 Provider 的 Key
sudo ./scripts/run_openeuler_cgroup_experiments.sh
RESULTS_DIR=experiment/results_all_api_openeuler_cgroup \
  python3 scripts/check_unified_resource_result.py

正式实验 Compose 使用 privileged: true、host PID/cgroup namespace，并把 /sys/fs/cgroup 以可写方式挂载到容器。这一入口只应在独占、临时主机或 VM 上运行，需要管理员权限；不要在承载其他重要服务的生产宿主上执行。容器内脚本会在真实 Provider 调用前检查 openEuler 用户空间、cgroup v2、CPU 限流和内存 OOM 约束。

本地开发

1. Python 环境

Linux/macOS：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r backend/requirements.txt

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r backend\requirements.txt

2. Redis

可复用 Compose 中的 Redis，并发布本机端口：

docker compose -f docker-compose.openeuler.yml -f docker-compose.ports-override.yml up -d redis

后端默认读取：

AGENTBUS_BACKEND=redis
REDIS_URL=redis://127.0.0.1:6379/0
AGENTBUS_STREAM=agentbus:events
AGENTBUS_REQUIRE_REDIS=0

本地调试允许 Redis 不可用时进入 local_fallback；正式通信实验必须保持 Redis 可用并禁止回退。

3. Backend

Linux/macOS：

AGENTBUS_BACKEND=redis REDIS_URL=redis://127.0.0.1:6379/0 python backend/app.py

Windows PowerShell：

$env:AGENTBUS_BACKEND = "redis"
$env:REDIS_URL = "redis://127.0.0.1:6379/0"
python backend\app.py

Backend 默认监听 127.0.0.1:8008。

4. Frontend

cd frontend
npm ci
npm run dev

开发服务器监听 127.0.0.1:5173。正式容器先执行 npm run build，再由 frontend/proxy_server.py 提供静态资源和同源 API/WebSocket 代理。

5. SUMO/TraCI 与场景

确认 sumo --version 可用后，在仓库根目录运行：

python backend/scripts/run_demo.py --end 900
python backend/scripts/run_demo.py --gui --speed 8

结果写入 backend/results/demo/。无 SUMO 的最小 Command Center 演示：

python backend/scripts/run_command_center_demo.py

实验复现

仓库有两套用途不同的入口：

1. experiment/run.py：面向 Runtime 机制的 11 项统一实验。
2. backend/scripts/run_all_experiments.py：面向 SUMO 场景的配置矩阵评测。

11 项 Runtime 机制实验

固定名称和执行顺序为：

os
sched
ablation
resource
fault
acl
llm_core
evidence
context
comm
ckpt

它们分别覆盖子进程/cgroup 生命周期、OS-PARS、调度消融、统一资源治理、故障隔离恢复、AgentSpec/Skill ACL、LLMCoreManager、Evidence 数据面、Context、Redis Streams 通信和 Checkpoint/Replay。

仅用于本地代码 smoke、不会调用真实 Provider 的调试命令：

python experiment/run.py all \
  --incidents 1 \
  --repeats 1 \
  --injections 3 \
  --seeds 1 \
  --allow-redis-fallback \
  --no-experiment-llm-api \
  --no-charts \
  --results experiment/results_cleanup_smoke

该命令显式启用了 Redis 回退并关闭真实 LLM，只能验证代码路径，不能作为正式比赛数据。 完整 all 路径包含 POSIX Shared Memory、进程组信号和 cgroup 相关检查，应在 Linux/openEuler 执行。Windows 只做不依赖 POSIX 进程语义的子项 smoke，例如把 all 替换为 sched；Windows 结果不能替代正式 openEuler 验收。

普通 Linux 环境的正式入口：

./scripts/setup_experiment_runtime.sh
# 编辑脚本生成的 .env.experiments.api
./scripts/check_experiment_api_environment.sh
./scripts/run_all_experiments_with_api.sh

check_experiment_api_environment.sh 默认只检查环境；只有显式设置 API_SMOKE=1 才会发起远端付费请求。正式 runner 不启用 Redis fallback、LLM fallback 或估算 usage，每个实验中的真实模型输出会直接选择随后由 Runtime 执行的动作，而不是实验结束后的装饰性 API 调用。

单项实验可将 all 替换为实验名，例如：

python experiment/run.py sched \
  --seeds 1,2,3 \
  --redis-url redis://127.0.0.1:6379/0 \
  --llm-provider deepseek \
  --llm-model deepseek-v4-flash \
  --results experiment/results_sched

正式单项命令同样需要对应 API Key 环境变量。不要加入 --allow-redis-fallback、--allow-llm-fallback、--allow-estimated-llm-usage 或 --no-experiment-llm-api。

主要输出包括：

<results>/
├── all_summary.json
├── report.csv
├── report.md                 # 运行时生成，不纳入版本控制
└── <experiment>/
    ├── summary.json
    ├── llm_in_loop_actions.csv
    ├── *.csv
    ├── *.json / *.jsonl
    └── figures/*.png / *.svg

本仓库当前不提交生成的正式结果目录，因此 README 不固化旧报告中的数值。复现实验后，应以同一结果根目录内的 all_summary.json、各实验 summary.json 和原始 CSV/JSONL 为数据来源；Dashboard 截图不能替代这些结构化证据。

SUMO 场景矩阵

快速运行两个 Seed：

python backend/scripts/run_all_experiments.py --quick

完整配置来自 backend/configs/exp_baseline.yaml，结果进入 backend/results/：

python backend/scripts/run_all_experiments.py \
  --config backend/configs/exp_baseline.yaml

配置

文件	作用
backend/configs/runtime.yaml	Runtime Kernel、Dynamic DAG、OS-PARS、资源上限、Context、Fault 与 Agent 注册
backend/configs/scenario_rainstorm.yaml	暴雨事故、动态任务与故障注入场景
backend/configs/city.sumocfg	SUMO 网络、路线和仿真入口
backend/configs/command_agents.yaml	Command Center Agent 与模型策略
backend/configs/exp_baseline.yaml	SUMO 实验矩阵
.env.example	AgentBus、Redis、Evidence 和可选 Provider 变量示例
.env.experiments.api.example	正式实验 Provider、Seed、重复次数和结果目录模板
docker-compose.openeuler.yml	Redis 与 Runtime 服务、Healthcheck、Shared Memory 和 Evidence Volume
docker-compose.ports-override.yml	宿主端口映射
frontend/vite.config.js	页面入口、构建目录和开发代理

敏感变量：

DEEPSEEK_API_KEY
DASHSCOPE_API_KEY
OPENAI_API_KEY
ANTHROPIC_API_KEY

真实密钥只应写入未跟踪的 .env.experiments.api 或部署系统的 Secret 管理设施。不要提交 .env、Token、私钥或带密钥的日志。

健康检查与故障排查

基础检查：

docker compose -f docker-compose.openeuler.yml -f docker-compose.ports-override.yml ps
docker compose -f docker-compose.openeuler.yml -f docker-compose.ports-override.yml logs --tail 200 city-runtime redis
curl -fsS http://127.0.0.1:8008/api/health
curl -fsS http://127.0.0.1:8008/api/agentbus/status
curl -fsS http://127.0.0.1:8008/api/evidence/status
curl -fsS http://127.0.0.1:5173/frontend-health

运行结果指标接口是 GET /api/metrics?run=<run>，必须先有对应的 backend/results/<run>/ 数据；项目没有声明通用 Prometheus /metrics 端点。

常见问题：

• Redis 连接失败：检查 REDIS_URL。容器内应使用 redis://redis:6379/0，宿主本地开发使用 redis://127.0.0.1:6379/0。正式模式设置 AGENTBUS_REQUIRE_REDIS=1 可避免误用回退总线。
• Provider Key 缺失：执行环境检查并确认 Provider 与 Key 变量匹配；不要为了让正式实验继续而启用 fallback。
• cgroup 目录不可写：只在 cgroup v2 Linux 宿主使用正式 cgroup Compose；确认 Docker 权限和专用实验环境。
• SUMO 未安装：确认 sumo --version、SUMO_HOME 和 PATH，无 SUMO 时只运行 Command Center 最小演示。
• 前端无法连接后端：开发模式确认 8008 可访问；容器模式优先通过 5173 同源网关访问，并检查 /frontend-health。
• Windows/Linux 路径差异：Windows 激活脚本位于 .venv\Scripts\，Linux 位于 .venv/bin/；Shell 部署脚本应在 Linux/WSL 中运行。
• openEuler 容器与宿主关系：/etc/os-release 反映容器用户空间，cgroup 与内核能力来自宿主 Linux 内核。

适用范围

AgentOS Runtime 的抽象可用于工业运维、自动编程、机器人协作、科研工作流、应急指挥和云端 Agent 服务等需要动态任务与共享资源治理的场景。当前仓库以研究原型和竞赛复现为目标，不代表上述领域均已完成生产部署。