LiteAgentBus

LiteAgentBus 是一个面向多智能体协作场景的系统原型，重点围绕以下三类机制展开：

低开销结构化通信
非文本状态传递
共享记忆存储、检索与复用

本项目对应中国研究生操作系统开源创新大赛社区赛题：一种面向多智能体协作的低开销通信、状态传递与共享记忆机制。

作品简介

系统包含 4 类 Agent：

Planner
Retriever
Executor
Summarizer

支持两种协作模式：

text 作为纯文本 baseline，使用自然语言展开完整上下文。
protocol 使用结构化协议字段传递 action / params / result_ref / state_refs / memory_refs 等高密度语义信息。

支持两种运行方式：

socket 多进程 + localhost Socket IPC，适合展示系统级多 Agent 运行时能力。
inline 单进程回退模式，适合端口受限或受限环境。

系统同时实现了：

SQLite 共享记忆模块
state_ref / memory_ref / result_ref / vector_id 非文本状态传递
重复记忆去重与节省量统计
OpenAI-compatible LLM Agent 接口
Python 沙箱执行原型

目录说明

当前提交目录中的主要内容如下：

agentbus/ 运行时、协议、状态存储、共享记忆、评测与报告生成代码
agents/ 多 Agent 角色实现
tools/ Python 沙箱
benchmarks/ 任务集与检索评测集
configs/ 协议与 Agent 配置
scripts/ 实验运行与结果生成脚本
docs/ 设计文档、部署文档、实验报告
deploy/ systemd 部署示例
outputs/ 实验结果与提交材料输出
run_demo.py 主运行入口

运行说明

1. 安装依赖

pip install -r requirements.txt

2. 基础复现实验

最小可运行版本：

python3 run_demo.py --mode both --transport inline

如果机器允许本地 Socket 监听，建议运行系统版：

python3 run_demo.py --mode both --transport socket

3. memory ablation 对照实验

关闭共享记忆：

python3 run_demo.py --mode both --transport inline --disable-memory

运行完整 memory ablation：

python3 scripts/run_memory_ablation_benchmark.py

4. 重复实验

基础 socket 重复实验：

python3 scripts/run_repeat_benchmark.py --repeat 5 --transport socket --label socket_repeat

真实 embedding 重复实验：

python3 scripts/run_real_embedding_repeat_benchmark.py --repeat 5 --transport socket

5. 真实 embedding 实验

下载并缓存真实模型：

python3 scripts/download_embedding_model.py --model BAAI/bge-small-zh-v1.5 --cache-dir outputs/model_cache

运行真实 embedding benchmark：

python3 scripts/run_real_embedding_benchmark.py --model BAAI/bge-small-zh-v1.5 --cache-dir outputs/model_cache

6. 真实 LLM Agent

如果需要启用真实 LLM：

export LITE_AGENT_LLM_MODE=openai-compatible
export LITE_AGENT_LLM_BASE_URL=https://your-api-host/v1
export LITE_AGENT_LLM_API_KEY=your_api_key
export LITE_AGENT_LLM_MODEL=your_model_name
python3 run_demo.py --mode both --transport auto

Embedding 说明

基础复现实验使用 hash embedding，不依赖模型缓存。

真实 embedding 实验使用 BAAI/bge-small-zh-v1.5，模型缓存未提交，可按脚本或说明另行下载。

当前主要结果文件

当前提交目录中最适合直接引用的结果文件包括：

基础重复实验

outputs/repeat/socket_repeat_summary.json
outputs/repeat/socket_repeat_summary.md

真实 embedding 重复实验

outputs/repeat_real_embedding/real_embedding_summary.json
outputs/repeat_real_embedding/real_embedding_summary.md

共享记忆开关对照实验

outputs/memory_ablation/summary.json
outputs/memory_ablation/summary.md

检索评测结果

outputs/retrieval_eval_report.json

重复记忆去重专项实验

outputs/duplicate_reuse/comparison.md

Worker 监控页示例

outputs/worker_status_panel.sample.html
outputs/worker_status_panel.sample.json

补充说明：

outputs/final_openeuler/ 中保存的是面向 openEuler 复现实验整理的一组原始运行归档；
outputs/repeat/ 和 outputs/repeat_real_embedding/ 中保存的是更适合直接引用的重复实验汇总结果；
outputs/model_cache/ 不在当前提交目录中，也不是提交必要内容。

提交材料说明

本仓库 master 分支根目录包含以下参赛材料：

README.md：作品简介与运行说明
LiteAgentBus_项目说明书.docx：项目说明书
参赛承诺书.pdf：参赛承诺书
LiteAgentBus_PPT.pptx：作品介绍PPT
演示视频.mp4：演示视频

核心源码位于：

agentbus/
agents/
scripts/
tools/
benchmarks/
configs/
deploy/

演示视频

演示视频已上传至网盘：

文件名：演示视频.mp4
链接：https://pan.baidu.com/s/1vopMkJNXje7oNMhD36UMFw
提取码：5cfc

视频内容包括：

openEuler 24.03-LTS-SP3 Docker 环境验证；
LiteAgentBus 多 Agent 系统运行演示；
text mode 与 protocol mode 通信开销对比；
非文本状态传递与共享记忆复用机制展示；
memory ablation 结果展示；
关键实验报告与提交文件说明。