EAGLE 2.0 多智能体低开销协作系统

EAGLE 2.0 是面向社区赛题“一种面向多智能体协作的低开销通信、状态传递与共享记忆机制”的原型系统。项目围绕低开销结构化通信、非文本状态传递、共享记忆复用和 CodeAct 沙箱执行设计，实现了可在 openEuler 24.03-LTS-SP3 上运行、测试和复现实验的多 Agent 协作运行时。

系统包含 Planner、Retriever、Executor、Verifier、Summarizer 五类 Agent。一次任务会经历能力发现、任务规划、共享记忆检索、embedding 状态生成与传递、LLM 代码生成、沙箱执行、执行验证、失败修复请求和记忆写入等阶段。连续任务中，后续 Agent 可通过语义检索复用前序任务沉淀的摘要、策略和执行经验。

核心特性

结构化通信协议：Agent 间传递动作类型、输入参数、返回结果、能力描述和状态引用，避免长文本上下文透传。
双模式对比：支持纯文本协作模式和结构化协议协作模式，并可在相同任务序列下输出评测报告。
非文本状态传递：将任务语义编码为 embedding 状态向量，支持 JSON fallback 和 shared memory 引用传递。
共享记忆复用：使用 SQLite 记录记忆 ID、来源 Agent、创建时间、任务主题、摘要、标签和长上下文，支持关键词、标签和语义相似度检索。
CodeAct 执行：Executor 调用真实 OpenAI-compatible LLM API 或 mock 模式生成 Python 代码，并在 Bubblewrap/本地 fallback 沙箱中运行。
执行验证与修复：Verifier 校验沙箱执行结果，失败时可向 Executor 发起结构化修复请求。
openEuler 适配：在 openEuler 24.03-LTS-SP3 上验证单元测试、10 轮评测和真实 API 场景。

目录结构

eagle/
  agents.py              Agent 定义与协作能力
  runtime.py             多 Agent 运行时和双模式调度
  protocol.py            结构化消息协议
  db_bridge.py           SQLite + FAISS/hash embedding 共享记忆
  state_exchange.py      状态向量生成与交换
  shared_vector_pool.py  共享内存向量池
  llm_client.py          OpenAI-compatible LLM API 客户端
  sandbox.py             Bubblewrap/本地沙箱执行
  evaluation.py          10 轮可复现实验评测
  real_api_scenario.py   真实 LLM API 连续任务示例
protocols/               Protobuf 协议定义
generated/               fallback 协议类
tests/                   单元测试与修复闭环测试
scripts/sync_to_vm.sh    Mac 到 openEuler 虚拟机同步脚本
DESIGN.md                系统设计文档
TECHNICAL_REPORT.md      技术报告与实验结果

环境要求

基础路径无需第三方依赖即可运行 mock 测试。完整 openEuler 演示建议：

sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y python3 python3-pip python3-devel bubblewrap sqlite-devel clang llvm elfutils-libelf-devel
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

可选生成真实 gRPC stubs：

python3 -m grpc_tools.protoc \
  -Iprotocols \
  --python_out=generated \
  --grpc_python_out=generated \
  protocols/message.proto \
  protocols/agent_runtime.proto

配置真实 LLM API

项目默认读取根目录 .env，支持 OpenAI-compatible /v1/chat/completions 接口。

cp .env.example .env
vim .env

示例：

EAGLE_LLM_MODE=api
EAGLE_LLM_BASE_URL=https://api.deepseek.com
EAGLE_LLM_MODEL=deepseek-chat
EAGLE_LLM_API_KEY=your_api_key_here

若没有 API Key，离线测试和评测会使用 mock 路径，保证可复现。

运行测试

python3 -m unittest discover -s tests -v

当前验证覆盖内存中心、消息限制、LLM mock、沙箱执行、IPC pipeline、评测指标和 Verifier 修复闭环。

运行 10 轮赛题评测

python3 -m eagle.evaluation --rounds 10

报告输出：

data/reports/evaluation_report.json
data/reports/evaluation_report.md

评测指标包括消息次数、文本通信字符数、结构化通信字节数、状态传递次数与字节数、shared memory 使用次数、JSON 向量传输节省量、执行尝试次数、修复次数、共享记忆命中率和耗时对比。

运行真实 API 场景

该场景会调用 .env 中配置的真实大模型 API。它包含两轮 openEuler 诊断任务：第一轮生成并执行安全 /proc 诊断脚本，第二轮复用第一轮共享记忆生成轻量版策略。

python3 -m eagle.real_api_scenario --isolated --output data/reports/real_api_scenario.json

典型结果：

task_count: 2
shared_memory_state_transfer_count: 2
json_vector_bytes_avoided: 3678
state_strategy_uses: 2
memory_hits: 1
real_api_01 exit=0
real_api_02 exit=0, reused_memory_id=mem_bec44eb2e018

openEuler 虚拟机同步

在 Mac 上开发时，可同步到 openEuler 虚拟机：

./scripts/sync_to_vm.sh

默认目标：

root@192.168.65.2:/root/os-project

持续监听同步：

./scripts/sync_to_vm.sh --watch

交付文件

README.md：作品简介、环境要求和运行说明
DESIGN.md：系统架构、模块设计和协议机制
TECHNICAL_REPORT.md：实现细节、实验设计、评测结果和结论