LightMAS

LightMAS 是面向“多智能体协作的低开销通信、状态传递与共享记忆机制”赛题的 Python 原型项目。项目可在 Linux/openEuler CPU 环境运行，不依赖 GPU，不需要外部模型下载，重点展示多 Agent 协作中如何降低重复上下文通信，并用严格实验拆分“结构化通信”和“共享记忆”两类收益。

1. 项目背景

多 Agent 系统通常需要规划、检索、执行和总结等角色协作。如果每一步都传递完整自然语言上下文，消息字符数和 token 近似开销会随着任务轮次增长。

LightMAS 当前提供三组实验模式：

• text_mode：纯文本协作基线，不使用非文本状态传递，不使用共享记忆。
• structured_no_memory：结构化 AgentMessage + StatePacket 非文本状态传递，不使用共享记忆。
• structured_with_memory：结构化 AgentMessage + StatePacket 非文本状态传递 + SQLite/numpy 共享记忆。

这样可以分别观察：

• 结构化通信和状态引用带来的通信开销下降。
• 共享记忆对连续任务复用的额外贡献。

2. 系统架构

用户任务
  |
  v
LightMASRuntime
  |
  +-- AgentRegistry：注册 Agent
  +-- MessageDispatcher：发送、接收、记录 AgentMessage
  +-- RuntimeContext：保存初始输入和 text_mode 上下文
  +-- StateStore：保存 structured 模式的非文本向量状态
  +-- SharedMemory：SQLite 元数据 + numpy 向量文件
  +-- CommunicationMetrics：统计通信、状态、记忆和耗时指标
  |
  +-- PlannerAgent -> RetrieverAgent -> ExecutorAgent -> SummarizerAgent

Agent 之间不能直接调用彼此函数，必须通过 Dispatcher 发送和接收 AgentMessage。

3. 目录结构

LightMAS/
├── agents/             # BaseAgent 与 4 个协作 Agent
├── data/               # tasks.json 与 experiment_config.json
├── docs/               # 系统设计、部署、实验报告和演示脚本
├── evaluation/         # 通信、状态、记忆和耗时指标
├── memory/             # SQLite + numpy 共享记忆
├── outputs/            # 实验输出 CSV 和 Markdown 报告
├── protocol/           # AgentMessage、AgentCapability、握手协议
├── runtime/            # 注册表、Dispatcher、运行时
├── state/              # StateEncoder、StatePacket、StateStore
├── tests/              # 单元测试
├── app.py              # Streamlit 展示页面
├── run_demo.py         # Demo 入口
├── run_experiment.py   # 三模式可复现实验入口
└── requirements.txt

4. 安装方法

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

依赖说明：

• numpy：保存和读取共享记忆向量。
• scikit-learn：默认使用 HashingVectorizer 编码非文本状态。
• streamlit：展示实验结果；没有 Streamlit 时仍可运行 run_experiment.py。
• pytest：运行测试。

5. 运行方法

运行 Demo：

python run_demo.py

运行三模式可复现实验：

python run_experiment.py

启动展示页面：

streamlit run app.py

如果环境没有 Streamlit，直接查看命令行报告：

outputs/comparison_report.md

6. 实验方法

任务集：

data/tasks.json

共 10 个连续任务：

• A 组：openEuler/Linux 故障诊断类任务，共 5 个。
• B 组：多 Agent 项目开发文档类任务，共 5 个。

配置文件：

data/experiment_config.json

关键配置：

• similarity_threshold：共享记忆真实命中阈值，默认 0.35。
• memory_top_k：每轮任务最多纳入的历史记忆数量，默认 1。
• estimated_seconds_per_token：估算端到端耗时使用的 token 时间系数。

实验顺序：

1. 使用独立 Runtime 运行 text_mode 的 10 个任务。
2. 使用独立 Runtime 运行 structured_no_memory 的 10 个任务。
3. 使用独立 Runtime 运行 structured_with_memory 的 10 个任务。

每种模式都有独立 memory 数据库和 state_store，避免跨模式污染。

structured_with_memory 中每轮任务顺序为：

1. RetrieverAgent 先检索历史记忆，并过滤当前 task_id。
2. ExecutorAgent 执行当前任务。
3. SummarizerAgent 最后写入当前任务记忆。

7. 输出文件

outputs/metrics_text.csv
outputs/metrics_structured_no_memory.csv
outputs/metrics_structured_with_memory.csv
outputs/comparison_report.md

8. 指标说明

CSV 字段包括：

• agent_message_count：Agent 消息次数。
• text_characters：通信字符开销。
• approximate_tokens：token 近似开销。
• elapsed_seconds：框架运行耗时。
• estimated_end_to_end_seconds：估算端到端耗时。
• non_text_state_transfer_count：非文本状态传递次数。
• vector_dimensions：传递向量维度累计值。
• vector_bytes：传递向量字节数累计值。
• memory_query_count：记忆查询次数。
• true_memory_hit_count：真实记忆命中次数。
• memory_hit_rate：真实记忆命中率。
• shared_memory_items_after_task：任务结束后的共享记忆条数。

真实记忆命中必须同时满足：

1. 最高相似度大于 similarity_threshold。
2. 该 memory_id 被实际加入本轮任务上下文或最终结果。
3. 检索时排除了当前任务的 task_id。

报告展示：

• 字符开销降低率。
• token 开销降低率。
• 框架运行耗时。
• 估算端到端耗时。
• 状态传递次数。
• 记忆查询次数。
• 真实记忆命中次数。
• 记忆命中率。

9. openEuler 部署说明

推荐步骤：

cd LightMAS
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
python run_demo.py
python run_experiment.py
pytest

注意事项：

• 不需要 GPU。
• 不需要联网下载模型。
• SQLite 和 numpy 向量文件默认写入本地文件系统。
• 如果不部署 Streamlit，仍可通过 outputs/comparison_report.md 完成交付评审。
• 如果服务器运行 Streamlit，请按实际安全要求配置端口、防火墙和访问控制。

10. 交付材料

• README.md：项目说明和运行入口。
• docs/系统设计文档.md：系统架构和核心机制。
• docs/部署文档.md：Linux/openEuler 部署步骤。
• docs/实验报告.md：实验任务、指标和结果说明。
• docs/演示视频脚本.md：比赛演示视频讲解脚本。
• outputs/metrics_text.csv：text_mode 实验结果。
• outputs/metrics_structured_no_memory.csv：structured_no_memory 实验结果。
• outputs/metrics_structured_with_memory.csv：structured_with_memory 实验结果。
• outputs/comparison_report.md：三模式实验对比报告。