Proto Agents

Proto Agents 是一个基于 AutoGen Core 和 Protobuf 的多智能体协作项目，用于比较纯文本与结构化消息的通信开销，并验证向量状态传递和历史执行结果复用。

系统包含 Planner、Retriever、Executor 和 Summarizer 四个 Agent。仓库同时提供纯文本通信基线，便于在相同任务、工具和记忆策略下与 Protobuf 模式做对比。

实现内容

• text 和 proto 两种通信模式
• 本地 FIFO runtime 和 AutoGen Core SingleThreadedAgentRuntime
• 握手、能力发现、动作请求、状态传递、执行结果和错误消息等 Protobuf 消息
• 基于 SQLite 的共享记忆，以及关键词、标签和向量相似度融合检索
• ref、float16、float32 三种向量状态编码
• 只读环境探测、项目扫描工具和受限 CodeAct 执行
• 可重复运行的 text/proto 对比实验、JSONL trace 和汇总报告

系统结构

flowchart LR
    T[Task] --> B[Runtime Broker]
    B --> P[Planner]
    P --> R[Retriever]
    R --> E[Executor]
    E --> S[Summarizer]
    S --> B
    R <--> M[(SQLite Memory)]
    S --> M
    P <--> A[(Artifact Store)]
    R <--> A
    E <--> A
    S <--> A

在 proto 模式下，Agent 之间传递的是序列化后的 AgentEnvelope。运行 trace 只用于记录和评测，不参与业务数据传递。

环境要求

• Python 3.11 或更高版本
• Linux；严格验收环境为 openEuler 24.03 LTS-SP3
• Bubblewrap 0.8 或更高版本，仅在强制 CodeAct 隔离时需要

创建虚拟环境并安装依赖：

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

requirements.txt 包含运行、Protobuf 代码生成和质量检查所需依赖。只安装项目及质量工具时，也可以执行：

python -m pip install '.[quality]'

快速开始

从项目根目录运行一轮本地 Protobuf 流程：

PYTHONPATH=src python -m proto_agents.main \
  --mode proto \
  --runtime local \
  --rounds 1

其他运行方式：

# 纯文本基线
PYTHONPATH=src python -m proto_agents.main --mode text --runtime local --rounds 1

# AutoGen Core runtime
PYTHONPATH=src python -m proto_agents.main --mode proto --runtime autogen --rounds 1

未配置模型服务时，程序使用确定性的本地模板和 32 维 hashing embedding，不需要联网。运行指标和 trace 写入 experiments/results/，共享记忆写入 data/。

配置模型服务

项目支持 OpenAI-compatible 的 chat completions 和 embeddings 接口。可以在项目根目录创建 .env，也可以直接设置同名环境变量；环境变量的优先级更高。

LLM_API_URL=https://example.com/v1
LLM_API_KEY=your-key
LLM_MODEL=your-chat-model
LLM_TEMPERATURE=0.2

EMBEDDING_API_URL=https://example.com/v1
EMBEDDING_API_KEY=your-key
EMBEDDING_MODEL=your-embedding-model

.env 已加入 .gitignore，不要提交真实密钥。只有 URL 和 key 同时存在时才会请求远端接口；调用失败会回退到本地实现。

向量状态的线路编码由 PROTO_STATE_ENCODING 控制：

取值	线路内容	适用场景
ref	向量引用和校验元数据	同一进程内传递较大的状态，默认值
float16	little-endian 半精度字节	降低自包含向量的传输体积
float32	Protobuf repeated float	保留完整单精度数值

例如：

PROTO_STATE_ENCODING=float16 PYTHONPATH=src \
  python -m proto_agents.main --mode proto --runtime local --rounds 1

运行对比实验

下面的命令会让 text 和 proto 模式分别运行 10 轮。run-id 必须唯一，已有结果不会被覆盖。

CODEACT_REQUIRE_BWRAP=1 \
  bash scripts/run_10_rounds.sh --run-id my_benchmark_run

每种模式使用独立的 SQLite 数据库。运行成功后，结果位于：

experiments/results/runs/my_benchmark_run/
data/runs/my_benchmark_run/

结果目录包括运行清单、指标汇总、对比报告、逐轮指标和 Agent trace。默认实验使用本地模板模型；只有直接调用 experiments/run_benchmark.py 并传入 --online 时，才会启用已配置的远端接口。

基准结果

仓库内附的离线基准在 openEuler 24.03 LTS-SP3、Local runtime、ref 编码下完成，text 和 proto 各运行 10 轮。以下为每轮平均值：

指标	text	proto
数据面消息数	3.00	4.00
总线路消息数	3.00	16.00
数据面字节数	8883.00	1657.60
控制面字节数	0.00	3938.60
总线路字节数	8883.00	5596.20
状态传递次数	0.00	2.00
共享记忆查询命中率	80.00%	80.00%

在这组任务上，proto 模式的数据面字节数减少 81.34%；计入握手、能力发现和动作请求后，总线路字节数减少 37.00%。两种模式各有 2 轮执行实际工具和 CodeAct，其余 8 轮复用共享记忆。

这些数据用于比较通信与复用机制，不代表公网模型的响应速度。原始指标和计算口径见 基准报告 和运行清单。

测试与检查

运行单元测试和静态检查：

PYTHONPATH=src python -m unittest discover -s tests -v
python -m ruff check src tests experiments

修改 protos/agent_protocol.proto 后重新生成 Python 代码：

bash scripts/gen_proto.sh

在 openEuler 24.03 LTS-SP3 上执行完整质量门禁：

bash scripts/quality_gate.sh

该脚本会检查系统和依赖版本、编译 Protobuf schema、运行测试与静态检查，并验证 Local/AutoGen runtime 和 Bubblewrap 隔离。

外层容器不允许 user namespace 时，可使用 --no-require-bubblewrap 做非严格检查。该结果不能替代正式隔离验收。

目录说明

protos/                 Protobuf schema
src/proto_agents/       Agent、runtime、协议、记忆、状态和工具实现
experiments/            任务集、基准 runner 和结果汇总
tests/                  单元测试
scripts/                代码生成、质量检查和实验脚本
data/                   SQLite 共享记忆及实验数据