StructAgentOS

面向多 Agent 协作的低开销通信、引用式状态传递与共享记忆运行时

StructAgentOS 是面向中国研究生操作系统开源创新大赛研发的多 Agent 协作 Runtime 与机制验证平台。项目基于 openEuler 环境完成研发与实验，围绕多 Agent 系统中通信开销高、中间状态反复转换、历史经验难以复用三类问题，设计了 ASCP-G 结构化通信协议、StateRef 引用式状态交接、共享记忆与 Fast Path 快速路径，并提供 CodeAct 安全执行、全链路追踪和Benchmark。

StructAgentOS 借鉴操作系统对通信、状态、调度和资源的管理思想，但它不是传统操作系统内核，也不负责进程调度、内存管理或硬件虚拟化。

核心成绩

指标	实验结果	说明
相对 Text CS 的 Token 节省	77%–82%	连续协议设计实验，DeepSeek 与 MiMo 两种模型
完整系统相对 M0 的 Token 降幅	75.7%	消融实验：982,471 → 238,517 Token
StateRef 引用大小	约 200 B	替代约 2–15 KB 的完整状态负载
跨模型任务完成率	99.0%	96 次任务中完成 95 次
跨模型总体准确率	91.7%	96 次任务中答对 88 次
StateRef 成功率	100.0%	所有成功任务中的引用传递均正常
记忆检索 Recall	1.000	冻结语料专项检索实验
Fast Path 非法触发	0 次	3 个允许任务正确触发，3 个禁止任务正确关闭
模型 API 适配	4 类	DeepSeek、MiMo、Qwen、Gemini

上述数据来自不同实验组，不能合并为单一综合指标。Mock 回归、真实 API 实验和 WSL2 环境下的耗时数据在本文后半部分分别说明。

目录

• 项目背景
• 系统架构
• 核心机制
• 五-Agent-协作流水线
• CodeAct-与可观测性
• 性能与实验结果
• 快速开始
• 运行与复现
• 项目结构
• 实验口径与当前边界
• 团队信息

项目背景

传统多 Agent 系统通常通过自然语言全文或通用 JSON 传递上下文。随着 Agent 数量和任务轮次增加，系统会逐步暴露三个问题：

1. 通信上下文持续膨胀：后续 Agent 重复接收和解析前序完整输出，Token、延迟和总线负载随流水线长度增长。
2. 中间状态反复转换：结构化状态被序列化为文本，再由下游 Agent 重新解释，既产生额外模型调用，也可能造成信息损失。
3. 经验无法安全复用：诊断、修复策略和验证结论难以跨任务持久化，遇到相似问题时仍需从头执行。

StructAgentOS 将 Agent 视为任务执行单元，由 Runtime 统一管理通信协议、状态生命周期、共享记忆、执行安全和可观测性，使 Agent 之间传递高密度语义与紧凑引用，而不是不断复制全文。

系统架构

系统由六个层次组成：

层次	主要组件	职责
评测层	MetricsCollector、BenchmarkRunner、ReportGenerator、Dashboard	采集 80+ 项指标，生成 JSON/Markdown 报告并可视化
Runtime 层	StructAgentRuntime、Scheduler、Message Bus、AgentRegistry	编排 Agent、路由消息、管理生命周期与运行模式
协议层	ASCPMessage、Handshake、ProtocolRouter、Validator	标准化消息、能力发现、三级路由、版本与字段校验
Agent 层	Planner、Retriever、Executor、Verifier、Summarizer	完成规划、检索、执行、验证、总结五阶段流水线
状态与记忆层	State Store、StateRef、Memory Store、Vector Index	管理中间状态、嵌入引用、共享记忆和 Fast Path
模型与执行层	OpenAI-compatible Provider、PythonSandboxRunner	接入不同模型 API，并在受控环境中执行 CodeAct

系统提供三类主要运行模式：

• text：自然语言全文传递，作为通信开销基线；
• structured_no_memory：启用 ASCP-G 与 StateRef，不启用共享记忆；
• structured：启用结构化通信、StateRef、共享记忆与安全 Fast Path。

核心机制

1. ASCP-G 结构化通信协议

ASCP-G（Agent Structured Communication Protocol - General）将 Agent 间交流从自由文本收敛为结构化消息，统一动作、参数、结果、能力、引用和错误语义。

协议包含五种核心生命周期消息：

HELLO
  └─ CAPABILITY_ANNOUNCE
       └─ ACTION_REQUEST
            └─ ACTION_RESULT
                 └─ FINAL_RESULT

协议同时提供独立的 ERROR 消息、trace_id、parent_msg_id、版本协商、Schema 校验以及按目标 Agent、消息动作和能力匹配的路由策略。实验中，仅启用 ASCP-G 即实现约 49% 的 Token 节省。

2. StateRef 引用式状态交接

每个 Agent 将执行结果写为 StateRecord，下游消息只携带 state_ref：

{
  "state_id": "state_tool_result_<uuid>",
  "embedding_ref": "embedding_<uuid>",
  "role": "execution_result"
}

State Store 负责负载存储、校验和验证、TTL、访问计数和生命周期管理。下游 Agent 仅在确有需要时解引用完整状态，从而实现“一次写入、按需引用”。

• 引用大小约 200 B；
• 原始完整负载通常为 2–15 KB；
• 在 ASCP-G 基础上，StateRef 进一步降低约 50.8% 的 Token 消耗；
• 跨模型端到端实验中，成功任务的 StateRef 传递成功率为 **100.0%**。

3. 共享记忆与 Fast Path

Summarizer 将任务摘要、证据链、置信度和可复用载荷写入 MemoryRecord。Retriever 在后续任务开始时融合以下信号进行检索：

• 语义或嵌入相似度；
• 关键词匹配；
• 标签相似度；
• 记忆置信度；
• 时间衰减。

只有在任务主题、关键约束、记忆状态、TTL、协议或代码版本、置信度、可复用载荷和风险等级等条件全部满足时，Fast Path 才允许复用历史结论并跳过冗余验证。任何约束变化、载荷损坏、环境变化或用户强制验证都会回退到完整 Verifier 路径。

专项门控实验中，3 个允许复用的任务全部触发 Fast Path，3 个禁止复用的任务全部被正确拦截，未观察到非法触发。

5 Agent 协作流水线

Agent	主要职责	典型输出
Planner	分析用户任务并生成结构化执行计划	plan_state
Retriever	检索外部知识与历史共享记忆	retrieval_state
Executor	调用模型、工具、数据库或 CodeAct	tool_result_state
Verifier	校验结果的正确性、完整性和一致性	verification_state
Summarizer	汇总最终结果并沉淀可复用经验	summary_state、MemoryRecord

流水线内部传递的是 StateRef、EmbeddingRef 和角色标签，而非完整状态副本；协议 Trace 则贯穿全部 Agent，支持运行回放与问题定位。

CodeAct 与可观测性

CodeAct 执行闭环

Executor 可让 LLM 生成 Python 代码，并通过“思考—执行—观察”闭环获得真实运行结果。

代码首先经过 SandboxPolicy 校验，再由 PythonSandboxRunner 在独立子进程中执行：

• 禁止危险模块、危险 API、动态执行和明显的无限循环模式；
• 限制代码与文件大小、CPU 时间和内存；
• 捕获 stdout、stderr、退出码和执行延迟；
• 支持超时终止、输出长度截断和进程组隔离；
• 在 Linux 环境中可选接入 cgroup v2，进一步约束内存、CPU 和进程数。

当前方案主要提供进程级隔离和资源约束，不等同于 Docker 容器或虚拟机级强隔离，不应直接运行不可信任的攻击性代码。

全链路可观测性

• 每条 ASCP-G 消息携带 trace_id 与 parent_msg_id；
• TraceLogger 将 Agent 通信、延迟、错误和负载写为 JSONL；
• MetricsCollector 采集 80+ 项协议、状态、记忆、沙箱、延迟和质量指标；
• Streamlit Dashboard 支持按任务主题筛选，并展示模式对比、消息分布、Agent 延迟和资源消耗。

性能与实验结果

项目通过四组实验验证协议、状态、记忆、Fast Path 和跨模型适配能力。

实验一：连续协议设计

在 5 轮连续协议设计任务中，使用 DeepSeek v4-pro 与 MiMo v2.5-pro 对比 AgentScope、Text CS 和 Full CS：

方法	DeepSeek 正确数	DeepSeek 质量	MiMo 正确数	MiMo 质量
AgentScope	1/5	0.58	1/5	0.53
Text CS	5/5	0.92	5/5	0.97
Full CS	3/5	0.82	2/5	0.77

Full CS 相对 Text CS 节省 77%–82% Token，且 Context Projector 将逐轮输入维持在相对稳定范围。不过，Full CS 在“当前轮要求满足度”上低于 Text CS，说明结构化压缩与完整上下文质量之间仍存在权衡。项目没有将 Token 降低等同于质量无损。

实验二：消融实验

两组各 10 轮的连续任务分别覆盖协议与记忆设计、Python 代码诊断与修复。

模式	ASCP-G	StateRef	共享记忆	Fast Path	总 Token	相对 M0 降幅
M0 Text-Full	关闭	关闭	关闭	关闭	982,471	—
M1 ASCP-Inline	开启	关闭	关闭	关闭	501,382	49.0%
M2 ASCP-StateRef	开启	开启	关闭	关闭	248,716	74.7%
M3 ASCP-StateRef-Memory	开启	开启	开启	关闭	243,294	75.2%
M4 Full-System	开启	开启	开启	开启	238,517	75.7%

结果表明，ASCP-G 和 StateRef 是降低 Token 的主要贡献项；共享记忆与 Fast Path 的直接降幅较小，但帮助系统复用历史结论并减少冗余验证。

图中两组前 5 轮实验的平均 Token 分别为：

• 纯文本模式：40,498.8；
• 结构化模式（无记忆）：11,495.2；
• 结构化模式（有记忆）：11,805.3。

结构化有记忆模式相对纯文本模式降低约 **70.9%**；记忆模块本身的价值主要体现在跨任务复用和质量恢复，而不是保证每一组短任务都继续降低 Token。

实验三：共享记忆与 Fast Path

在统一 Embedding 和相同 24 条冻结记忆语料下：

指标	StructAgentOS Memory	A-MEM-Retrieval
Precision	0.625	0.250
Recall	1.000	0.875
MRR	0.771	0.483
Top-5 成功率	1.000	0.875

下游任务成本结果：

配置	总 Token	相对 M2	总延迟
M2：无记忆	5,890	—	98,578 ms
M3：记忆检索、完整验证	4,122	-30.0%	71,364 ms
M4：记忆与安全 Fast Path	2,987	-49.3%	51,846 ms

StructAgentOS 的平均检索延迟为 489 ms，A-MEM-Retrieval 为 21,870 ms。该差异同时受到进程内 SQLite 与外部子进程调用路径的影响，不能全部归因于检索算法。

实验四：多模型 API 端到端验证

测试集共 24 道任务，覆盖数学、理化、计算机、语文与文学、历史与地理、生活计算与逻辑六个领域；四个模型共执行 96 次任务。

模型	正确数	准确率	完成率	API 成功率	平均 Token	平均耗时
DeepSeek-V4-Pro	22/24	91.7%	100.0%	99.1%	2,051.4	8.53 s
MiMo-V2.5-Pro	21/24	87.5%	95.8%	95.6%	2,160.2	9.89 s
Qwen3.7-Plus	22/24	91.7%	100.0%	99.1%	1,976.0	7.39 s
Gemini 3.6 Flash	23/24	95.8%	100.0%	98.2%	1,841.5	7.02 s
总体	88/96	91.7%	99.0%	98.0%	2,005.6	8.19 s

所有成功任务均实现 100% StateRef 有效传递。唯一未完成任务由 API 超时引起，未出现 ASCP-G 格式错误、Agent 路由失败或 StateRef 解引用失败导致的任务中断。

快速开始

以下命令假设源码包已经解压，并在 StructAgentOS 项目根目录执行。

环境要求

• Python 3.10 或更高版本；
• Linux、openEuler、WSL2、macOS，或支持 Python 的 Windows 环境；
• 真实模型实验需要可用的 OpenAI-compatible API；
• Mock 演示与离线回归不访问真实模型 API。

安装

python -m venv .venv

Windows PowerShell：

.\.venv\Scripts\Activate.ps1

Linux、openEuler、macOS 或 WSL：

source .venv/bin/activate

安装依赖：

python -m pip install -U pip
python -m pip install -e . -r requirements.txt

离线回归与测试

# 严格离线回归：Mock Provider、Hash 检索、进程内消息总线、禁止网络
python scripts/run_offline_regression.py --strict

# 完整测试集
python -m pytest -q

最小任务示例

python -m structagentos.run_task \
  --mode structured \
  --task tasks/demo_task.yaml \
  --output reports/demo_result.json \
  --provider mock

运行与复现

Mock 三模式对比

Mock Benchmark 用于低成本、可重复地验证机制链路：

python run_benchmark.py --rounds 10 --compare --provider mock

它可以验证：

• Text 与 Structured 通信路径；
• ASCP-G 消息、StateRef 与 EmbeddingRef；
• 共享记忆查询、命中和复用；
• Benchmark 报告与 Dashboard 字段；
• 无真实 API、无网络条件下的核心回归。

Mock Token 是根据序列化通信负载估算的，不能作为真实 API 计费 Token 的证据。

真实 API Benchmark

请通过configs/model_api.env配置文件提供模型信息，示例：

export STRUCTAGENTOS_LLM_PROVIDER="openai-compatible"
export STRUCTAGENTOS_LLM_MODEL="<MODEL_NAME>"
export STRUCTAGENTOS_LLM_BASE_URL="<API_BASE_URL>"
export STRUCTAGENTOS_LLM_API_KEY="<YOUR_API_KEY>"
export STRUCTAGENTOS_LLM_TIMEOUT_SECONDS="180"

不要把真实 API Key 提交到 Git 仓库、README、日志或实验报告中。

运行结构化模式：

python run_benchmark.py \
  --rounds 2 \
  --env-file configs/model_api.env \
  --memory-backend sqlite \
  --timeout-seconds 180

运行完整三模式对比：

python run_benchmark.py \
  --rounds 5 \
  --compare \
  --env-file configs/model_api.env \
  --memory-backend sqlite \
  --timeout-seconds 180

text 模式会携带更多历史上下文，真实 API 对比通常显著慢于结构化模式，请预留足够超时时间和调用预算。

交互式讨论与代码生成

python run_benchmark.py \
  --interactive-topic "设计一个支持版本协商的多 Agent 通信协议" \
  --rounds 3 \
  --provider mock

Dashboard

streamlit run dashboard/app.py

Dashboard 是试验3下的一个子试验，用于自定义任务

openEuler 验证

bash scripts/openEuler_smoke.sh

如果命令不是在真实 openEuler 环境中运行，输出只能作为当前宿主机检查结果，不能表述为 openEuler 真机验证。

输出产物

reports/
├── YYYYMMDD/
│   └── HHMM_<run_id>/
│       ├── result.json
│       ├── report.md
│       ├── discussion_trace.md
│       ├── generated_code.py
│       └── runs/
├── offline_regression_result.json
├── offline_regression_report.md
└── offline_regression_runs/

• result.json：机器可读的 Benchmark 汇总；
• report.md：面向评审与开发者的实验报告；
• discussion_trace.md：交互式讨论过程；
• generated_code.py：从讨论结果中提取的 Python 代码；
• runs/：逐轮 Trace、Audit、State 和 Metrics 数据。

项目结构

StructAgentOS/
├── structagentos/
│   ├── agents/          # Planner、Retriever、Executor、Verifier、Summarizer
│   ├── protocol/        # ASCP-G 消息、握手、能力发现、路由与校验
│   ├── runtime/         # Runtime、调度器、Agent Registry、Message Bus
│   ├── state/           # StateRecord、StateRef、生命周期与状态存储
│   ├── memory/          # MemoryRecord、检索、SQLite/JSON/VectorIndex
│   ├── sandbox/         # CodeAct 策略、Python Runner 与资源限制
│   ├── evaluation/      # Metrics、Benchmark 与报告生成
│   ├── observability/   # Trace 与审计日志
│   └── input/           # 文本、代码和多模态输入适配
├── dashboard/           # Streamlit 可视化面板
├── configs/             # Runtime 与模型配置
├── tasks/               # Demo 与 Benchmark 任务集
├── scripts/             # 回归、演示、API Smoke、openEuler 脚本
├── tests/               # 离线与系统测试
├── run_task.py
└── run_benchmark.py

技术栈

• Python 3.10+；
• PyYAML；
• SQLite / JSON Memory Store；
• 可选 ChromaDB 与外部 Embedding Provider；
• Streamlit Dashboard；
• POSIX rlimit 与可选 cgroup v2；
• OpenAI-compatible 模型接口。