AgentMemBus 项目运行说明

AgentMemBus 是一个面向多智能体协作的低开销通信、状态传递与共享记忆机制原型系统。项目支持 Planner、Retriever、Executor、Summarizer 四类 Agent，并提供 text-only 与 optimized 两种协作模式，用于对比自然语言长文本通信和结构化协议通信的开销差异。

当前系统默认使用 Mock LLM，不依赖 NPU、CUDA、torch、torch_npu、faiss 或 sentence-transformers。只有显式设置 LLM_BACKEND=deepseek 时才会尝试调用 DeepSeek API。

1. 运行环境

推荐环境：

Python 3.10 或 3.11
openEuler 22.03 LTS-SP4 / openEuler 24.03-LTS-SP3
CPU + Mock LLM 默认模式
Conda 或 Miniforge 虚拟环境

项目第一阶段到当前 Dashboard 演示阶段都可以在 CPU 环境运行，不需要 Ascend NPU，也不会调用 torch 或 torch_npu。

2. 创建 Conda 环境

Linux / openEuler：

conda create -n agentmembus python=3.10 -y
conda activate agentmembus
cd AgentMemBus
python -m pip install -r requirements.txt

Windows PowerShell：

conda create -n agentmembus python=3.10 -y
conda activate agentmembus
cd C:\OSopen\AgentMemBus
python -m pip install -r requirements.txt

如果服务器已经创建好虚拟环境，只需要进入项目目录后安装依赖：

python -m pip install -r requirements.txt

3. 依赖说明

requirements.txt 当前包含轻量依赖：

pydantic
python-dotenv
requests
numpy
streamlit
pandas
plotly

项目不会安装或使用以下重型依赖：

torch
torch_npu
faiss
sentence-transformers
CUDA 相关依赖

4. 快速运行 Demo

进入项目目录：

cd AgentMemBus

运行 optimized 模式，默认使用 Mock LLM：

LLM_BACKEND=mock python run_demo.py --mode optimized

运行 text-only 模式：

LLM_BACKEND=mock python run_demo.py --mode text

如果不传 --mode，默认使用 optimized：

python run_demo.py

运行完成后会生成 demo 指标文件：

metrics/demo_text_metrics.json
metrics/demo_optimized_metrics.json

5. Demo 对比实验

执行：

python compare_demo.py

该脚本会依次运行：

python run_demo.py --mode text
python run_demo.py --mode optimized

然后生成：

metrics/demo_comparison.json

对比内容包括：

token 开销
字符开销
latency
state transfer count
state transfer bytes
memory hit count
memory hit rate

6. Benchmark 多轮实验

运行 text-only 与 optimized 的完整 benchmark：

python benchmark/run_benchmark.py --mode both --rounds 10

也可以分别运行：

python benchmark/run_benchmark.py --mode text --rounds 10
python benchmark/run_benchmark.py --mode optimized --rounds 10

Benchmark 会读取：

benchmark/tasks.json

当前任务集包含 2 组关联连续任务，每组 3 个任务：

openEuler 多 Agent 系统部署
多 Agent 共享记忆机制技术报告

Benchmark 输出文件：

metrics/benchmark_text_metrics.json
metrics/benchmark_optimized_metrics.json
metrics/benchmark_comparison.json
docs/experiment_report.md

说明：Benchmark 为了保证可复现，默认使用 Mock LLM，不会强制调用 DeepSeek API。

7. 启动 Streamlit Dashboard

建议先生成 benchmark 指标：

python benchmark/run_benchmark.py --mode both --rounds 10

启动可视化页面：

streamlit run dashboard/app.py

Dashboard 包含两个主要页面：

Live Particle Simulation：动态粒子通信演示，用于展示 Agent 通信、state_refs 状态传递和 memory_refs 记忆复用。
Benchmark Results：读取真实 benchmark 指标，展示 text-only 与 optimized 的实验对比结果。

如果 metrics/benchmark_comparison.json 不存在，Dashboard 会提示先运行 benchmark，不会直接崩溃。

8. DeepSeek API 可选接入

默认 mock 模式不需要 API key：

LLM_BACKEND=mock python run_demo.py --mode optimized

如果需要使用 DeepSeek API，可以复制环境变量模板：

cp .env.example .env

编辑 .env：

LLM_BACKEND=deepseek
DEEPSEEK_API_KEY=your_api_key_here
DEEPSEEK_API_KEY_FILE=
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

然后运行：

LLM_BACKEND=deepseek python run_demo.py --mode optimized

也可以把 API key 写入项目根目录的 api-key.txt：

printf '%s' '你的真实 API key' > api-key.txt
chmod 600 api-key.txt
LLM_BACKEND=deepseek python run_demo.py --mode optimized

api-key.txt 只写一行 API key，不要添加 DEEPSEEK_API_KEY= 前缀。该文件已加入 .gitignore，不要提交到代码仓库。

也可以把密钥保存在项目外部：

mkdir -p ~/.config/agentmembus
printf '%s' '你的真实 API key' > ~/.config/agentmembus/deepseek.key
chmod 600 ~/.config/agentmembus/deepseek.key

export LLM_BACKEND=deepseek
export DEEPSEEK_API_KEY_FILE="$HOME/.config/agentmembus/deepseek.key"
python run_demo.py --mode optimized

DeepSeek 当前只用于：

PlannerAgent
SummarizerAgent

RetrieverAgent 和 ExecutorAgent 仍保持确定性模拟逻辑，便于 benchmark 复现和答辩演示。

9. 两种协作模式说明

text-only 模式

Agent 之间传递较长自然语言文本：

Planner 输出自然语言计划。
Retriever 返回较长证据文本。
Executor 返回较长执行说明。
Summarizer 基于长文本生成总结。
不使用 state_refs。
不使用 memory_refs。

该模式用于作为通信开销 baseline。

optimized 模式

Agent 之间传递结构化协议字段：

使用 action、params、result 等紧凑字段。
Retriever 将证据 payload 写入 StateStore，只传递 state_id。
Summarizer 通过 state_refs 读取 StateStore。
Summarizer 将任务摘要写入 MemoryStore。
后续任务通过 memory_refs 命中并复用历史记忆。

该模式用于验证低开销通信、非文本状态传递和共享记忆复用。

10. StateStore 与 MemoryStore

StateStore 默认目录：

data/states/

典型文件：

data/states/state_index.json
data/states/state_000001.json
data/states/state_000001_embedding.npy

MemoryStore 默认数据库：

data/memory/memory.db

MemoryStore 使用 SQLite 保存：

memory_id
task_topic
summary
tags
state_refs
embedding_ref
reuse_count

11. 实验报告

Benchmark 会自动生成：

docs/experiment_report.md

报告包含：

实验目标
实验环境
任务设置
text-only 与 optimized 对比
token saving rate
char saving rate
state transfer count
state transfer bytes
memory hit count
memory hit rate
task success rate
延迟分析与优化方向

optimized latency 可能高于 text-only，这是因为原型系统中包含 SQLite 读写、StateStore 文件持久化、轻量 embedding 和 memory search。当前实验重点是验证 token 降低、状态传递可行性和共享记忆复用效果。

12. 常用验收命令

python run_demo.py --mode text
python run_demo.py --mode optimized
python compare_demo.py
python benchmark/run_benchmark.py --mode text --rounds 10
python benchmark/run_benchmark.py --mode optimized --rounds 10
python benchmark/run_benchmark.py --mode both --rounds 10
streamlit run dashboard/app.py

13. 常见问题

1. Dashboard 提示缺少 benchmark 指标

先运行：

python benchmark/run_benchmark.py --mode both --rounds 10

然后重新启动：

streamlit run dashboard/app.py

2. DeepSeek 没有 API key

使用 mock 模式即可：

LLM_BACKEND=mock python run_demo.py --mode optimized

如果确实要调用 DeepSeek，请配置 .env、DEEPSEEK_API_KEY 或 DEEPSEEK_API_KEY_FILE。

3. 想保留历史记忆复用

默认 demo 会清理 store，以保证实验可复现。如果想保留历史记忆：

python run_demo.py --mode optimized --no-reset-store

4. Linux 服务器上找不到 streamlit

确认当前 Conda 环境已激活，并重新安装依赖：

conda activate agentmembus
python -m pip install -r requirements.txt
python -m streamlit run dashboard/app.py

14. 项目目录

AgentMemBus/
├── agents/
├── benchmark/
├── bus/
├── dashboard/
├── docs/
├── llm/
├── memory/
├── metrics/
├── state/
├── compare_demo.py
├── run_demo.py
├── requirements.txt
├── .env.example
└── README.md

15. 安全说明

不要把真实 API key 写入代码。
不要提交 .env 或 api-key.txt。
benchmark 默认使用 mock，便于复现实验结果。
项目默认不使用 NPU、torch、torch_npu、faiss 或 sentence-transformers。