AgentStateBus

AgentStateBus 是一个面向“多智能体协作低开销通信、状态传递与共享记忆机制”赛题的可运行原型系统。项目重点不是简单工作流编排，而是验证多 Agent 协作中的系统层基础设施：

用结构化协议替代冗长自然语言透传，降低通信字符数和估算 token 开销；
通过 state_id 引用传递二进制语义向量，减少“内部状态-文本-内部状态”的反复编解码；
将任务过程中的摘要、证据、工具结果和策略写入 SQLite 共享记忆，支持关键词、标签、语义相似度和混合检索；
在相同 10 轮连续任务上对比纯文本协作模式与结构化协议协作模式，生成可复现实验报告。

项目只依赖 Python 标准库，便于在 openEuler 24.03-LTS-SP3 上离线运行、测试和复现。

快速运行

python3 -m agentstatebus demo --out runs/demo

该命令会对同一组 10 个连续任务运行两遍：

text 模式：Agent 之间传递完整自然语言/JSON 上下文，作为传统纯文本协作基线。
structured 模式：Agent 之间传递紧凑动作载荷，并用 state_id、memory_id 引用非文本状态和共享记忆。

主要产物：

runs/demo/text/summary.json
runs/demo/structured/summary.json
runs/demo/structured/protocol_map.json
runs/demo/structured/states/*.bin
runs/demo/structured/memory.sqlite3
runs/demo/report/comparison.json
runs/demo/report/report.md
runs/demo/report/report.html

常用命令

python3 -m agentstatebus run --mode text --tasks bench/tasks.json --out runs/text
python3 -m agentstatebus run --mode structured --tasks bench/tasks.json --out runs/structured
python3 -m agentstatebus compare --text-run runs/text --structured-run runs/structured --out runs/report
python3 -m agentstatebus memory-search --db runs/structured/memory.sqlite3 --query "systemd 部署" --tags openeuler --strategy hybrid
python3 -m agentstatebus repeat --runs 3 --out runs/repeat
python3 -m agentstatebus codeact-demo
python3 -m agentstatebus ipc-state-demo --out runs/ipc-state-demo.json

测试

python3 -m unittest discover -s tests

赛题要求映射

赛题要求	原型实现
不少于 3 个 Agent	`planner`、`retriever`、`executor`、`summarizer` 共 4 个 Agent
覆盖规划、检索、执行、总结角色	在 `agentstatebus/agents.py` 中实现
结构化通信协议	`agentstatebus/protocol.py` 定义动作、载荷、结果、wire parser、能力握手和协议映射
纯文本与结构化两种模式	`python3 -m agentstatebus run --mode text/structured`
非文本中间状态传递	`agentstatebus/state.py` 保存二进制 `states/*.bin`，Agent 之间传递 `state_id`
共享记忆	`agentstatebus/memory.py` 使用 SQLite 保存记忆单元，并支持关键词/标签/语义/混合检索
两组关联连续任务	`bench/tasks.json` 中包含 openEuler 部署组和代码协作分析组，各 5 个任务
指标统计	`agentstatebus/metrics.py`、`summary.json`、`comparison.json`、Markdown/HTML 报告
不少于 10 轮稳定运行	`python3 -m agentstatebus demo --out runs/demo`
重复实验均值	`python3 -m agentstatebus repeat --runs 3 --out runs/repeat`
CodeAct 沙箱	`agentstatebus/codeact.py` 与 `codeact-demo`
Socket IPC 状态传递	`agentstatebus/ipc_state.py` 与 `ipc-state-demo`

架构概览

flowchart LR
  Runtime["多 Agent 运行时"] --> Protocol["协议解析与调度"]
  Protocol --> Planner["PlannerAgent"]
  Protocol --> Retriever["RetrieverAgent"]
  Protocol --> Executor["ExecutorAgent"]
  Protocol --> Summarizer["SummarizerAgent"]
  Retriever --> StateStore["二进制状态存储"]
  Executor --> StateStore
  Summarizer --> MemoryStore["SQLite 共享记忆"]
  Runtime --> Metrics["指标统计与报告"]
  MemoryStore --> Planner
  MemoryStore --> Retriever

完整文件结构与模块映射见 docs/structure.md；设计方案见 docs/design.md；部署说明见 docs/deploy.md；实验方案见 docs/experiment.md；完整技术报告见 docs/technical_report.md。

说明

当前 embedding 实现采用确定性的 signed-hash 向量。它并不追求超过神经向量模型，而是保证原型可以离线复现，用最小依赖验证结构化通信、非文本状态交换和共享记忆复用机制。