AgentWeave — Connect, Collaborate, Compose

AgentWeave — 基于引用式语义传递的多智能体低开销通信机制

AMP 承载控制语义 · SSSP 连接状态与记忆
AgentWeave 是面向多智能体协作的系统层运行时，以 Agent Message Protocol（AMP）构建低开销结构化通信，以 Shared Semantic State Pool（SSSP）管理可寻址非文本状态和可复用共享记忆，使 Agent 通过轻量引用协同传递语义状态，并提供可运行、可观测、可复现的协作基础设施。

快速开始 · 系统架构 · 实验验证 · 赛题对照 · 参赛材料 · 项目文档

架构设计 · openEuler 部署 · 实验报告 · 正式对比报告 · 贡献指南

Agent 间交接 token 降低	总通信载荷降低	记忆命中率	非文本状态传递
97.46%	94.99%	79.05%	118 次
本方案相较纯文本基线	十任务正式实验	本方案全局经验复用	POSIX 共享内存

数据取自十任务正式实验归档。纯文本基线与本方案使用独立进程运行，完整口径见实验报告和正式对比报告。

🏆 参赛材料

项目文档	展示材料	参赛文件
项目说明书 PDF 项目说明书 DOCX	演示 PPTX 演示 PPT PDF 演示视频 MP4	作品原创承诺书 PDF

AgentWeave 为多 Agent 协作提供系统层通信与状态管理能力：随着协作轮次增加，系统通过引用式语义传递控制上下文规模，通过共享内存交换非文本状态，并将已验证的任务经验沉淀为可复用资产。

项目的协议内核由两部分组成：

AMP（Agent Message Protocol）：定义身份、握手、能力发现、结构化调用、结果返回、错误处理和消息关联。
SSSP（Shared Semantic State Pool）：定义原子状态、状态引用、检索、解析、可见性、生命周期和跨任务经验沉淀。

仓库同时提供可运行的参考实现和一个真实 Web CVE 复现应用，用来验证协议在多步骤、长状态、强工具依赖任务中的行为。

模式简称：M0 表示纯文本基线，M1 表示结构化通信，M2 表示 M1 加非文本状态交换，M3 表示 M2 加跨任务记忆的完整方案。详细配置见“实验设计与模式”。

✨ 核心能力

🔌 AMP 结构化通信	🧠 SSSP 共享语义状态池
身份握手、能力发现、结构化调用、结果关联、错误处理和 MessagePack 紧凑编码	ASU 原子状态、状态引用、检索解析、可见性、生命周期和跨任务经验沉淀
⚡ 非文本状态交换	📊 可复现实验体系
embedding 经 POSIX 共享内存跨进程传递，AMP 消息仅携带轻量引用	M0–M3 四模式、十任务压力实验、CSV、Trace、HTML 报告和可视化大屏

🎯 赛题要求对照

通信效率	状态传递创新	记忆复用效果	系统完整性	实验验证
25 分	20 分	20 分	20 分	15 分

#	赛题主要要求	AgentWeave 实现与核验入口
1	≥3 个 Agent、覆盖 ≥3 类角色，完成多步骤复杂任务	✅ 6 类领域 Agent + StatePool 服务，共 7 个独立进程；覆盖规划、检索、环境、执行、校验、经验管理。Agent 实现 · 会话主链
2	结构化通信包含动作、参数、结果、能力，并支持握手、能力发现或协议映射	✅ AMP 提供 `HELLO / CALL / RESULT / ERROR`、消息关联与能力注册；MessagePack 失败时降级为紧凑 JSON。AMP · 协议帧 · 能力目录
3	同时支持纯文本与结构化模式，在相同任务条件下可复现对比	✅ M0–M3 共用同一任务入口、Agent 和指标采集链路；正式实验独立运行 M0/M3。实验入口 · 正式并行实验
4	非文本中间状态直接交换，并说明生成、传递、接收、使用方式	✅ embedding 本地生成，经 POSIX 共享内存跨进程交付 StatePool，用于语义检索、路由和去重；正式批次完成 118 次、181,248 字节传递。状态交换 · 共享内存通道
5	统一记忆单元包含 ID、来源 Agent、时间、任务主题、摘要等元数据	✅ ASU 统一封装 19 个字段，并按 ephemeral / task / global 生命周期管理。ASU · StatePool
6	支持关键词、标签或语义检索，允许跨 Agent、跨任务复用	✅ StatePool 支持关键词、标签、语义和混合检索；M3 正式实验命中 117/148 次，命中率 79.05%。检索实现 · 状态路由
7	≥2 组关联连续任务，验证减少重复计算、降低开销和提升效率	✅ A 组验证同一目标两阶段状态复用，B 组验证跨目标同族经验复用；正式批次连续执行 10 个场景。场景库 · 正式清单
8	展示消息数、文本 token、非文本次数与规模、耗时、命中率和整体提升	✅ MetricsCollector 统一采集全部指标，并生成 JSON、CSV、账本、Trace 和 HTML 报告。指标采集 · 正式汇总
9	包含运行时、协议调度、状态交换、记忆存储检索和评测模块，稳定执行 ≥10 轮	✅ 五类核心模块完整协同；正式 M3 连续执行 10 轮无中断，45 项单元与集成测试通过。系统设计 · 测试目录
10	提交源码、设计、部署、实验报告和视频，支持现场复现并结合系统技术	✅ 根目录提供完整材料；实现 UDS、Socket、共享内存、mmap、SQLite/FTS5、向量索引、Docker 与进程沙箱。部署文档 · 实验报告
+	CodeAct：生成 Python，在轻量沙箱中安全执行并回传结果	✅ Executor 在隔离子进程中运行代码，配置 timeout、CPU/内存和文件描述符限制，并返回结构化结果。CodeAct 沙箱

💡 为什么需要它

传统多 Agent 系统通常把上一步的对话、工具输出和中间结论拼成长文本，再交给下一个 Agent。任务越长，重复上下文越多，通信载荷、解析成本和错误传播也越明显。

AgentWeave 将这条链路拆开：

AMP 负责轻量协作交接，SSSP 负责非文本状态的存储、检索与复用；Agent 通过 state_ref 按需解析目标状态。

控制消息、结构化状态、数值向量和大体积证据分别走适合自己的通道：

数据	传递方式	用途
调用与返回	AMP Frame，经 Socket/UDS 传输	能力调用、结果关联、错误处理
可复用状态	`state_ref`	跨 Agent、跨阶段按需解析
数值向量	`embedding_ref` + Shared Memory	语义检索、路由和去重
日志与响应正文	`artifact_ref`	大对象保留在状态存储层，消息和模型上下文仅携带引用

🏗️ 系统架构

AgentWeave 采用任务调度、协议运行时、状态存储与领域适配协同工作的分层架构。Session Orchestrator 根据任务图调度能力，Broker 与 Capability Registry 通过 AMP 完成多 Agent 消息路由；StatePoolAgent 经共享内存接收 embedding，并依托 SSSP、SQLite、FTS5 和向量索引管理 ASU 状态与跨任务记忆。CVE 复现适配层将通用运行时映射为规划、检索、环境构建、受控利用、验证和经验沉淀流程，Trace、指标账本与报告链路贯穿通信面和状态面，为双模式实验与结果审计提供观测数据。

蓝色表示 AMP 控制流，青色表示 SSSP 状态流，紫色虚线表示 Trace、指标与报告链路；下层 CVE 流程是通用 Agent 运行时的一套参考适配。

这里有两个中心，职责不同：

Broker 是通信中心：根据 action 和能力目录决定消息交给谁，并用 msg_id / in_reply_to 维持请求关联。
StatePool / SSSP 是状态中心：StatePoolAgent 是通过 AMP 对外提供状态读写、检索与解析能力的独立服务进程；SSSP 是共享语义状态池机制，StatePool 是核心实现，SQLite、FTS5 与向量索引承担持久化和检索。

AMP：结构化控制协议

Agent 启动后通过 HELLO 注册身份和能力，Broker 将 action → agent_id 写入 Capability Registry。Orchestrator 依据能力标识发起调用，Capability Registry 与 Broker 共同完成进程映射和消息路由。

AMP 当前覆盖：

HELLO / WELCOME：握手与能力目录；
CALL / RESULT / ERROR：通用调用、返回与失败；
CAPABILITY_ADVERTISE：能力声明与发现；
TOOL_RESULT：将工具结果写成共享状态；
STATE_REF_TRANSFER：传递状态引用；
MEMORY_RETRIEVE / MEMORY_RETRIEVE_RESULT：查询共享记忆；
msg_id / in_reply_to / task_id：消息关联和任务隔离。

结构化模式优先使用 MessagePack，并提供紧凑 JSON 降级通道。Socket 帧采用四字节大端长度前缀，为流式传输提供明确的消息边界。

SSSP：共享语义状态池

SSSP 的最小单位是 ASU（Atomic State Unit）。它把大段过程文本拆成有类型、有来源、有生命周期、可单独引用的状态。

状态按生命周期分为三层：

层级	保存内容	典型状态
`ephemeral`	有 TTL 的临时或敏感状态	token、cookie、短期会话
`task`	当前任务共享工作集	endpoint、部署状态、攻击证据、验证结论
`global`	已验证的跨任务经验	deployment recipe、成功路线、失败模式、验证策略

敏感状态使用更严格的可见性或 secret_ref。credential、token 和 cookie 保持在限定作用域内，经验提升流程会将其过滤。

非文本状态交换

M2/M3 模式下，Agent 将 ASU 的索引视图编码为 embedding，并通过命名共享内存交给 StatePool：

AMP 传递轻量句柄，向量以原始数值形式经过共享内存交付，LLM 仅接收按需解析后的信息。当前主链路使用 384 维向量；语义模型不可用时可退化为确定性哈希向量，以保证协议流程仍可运行。

共享记忆与经验复用

ExperienceAgent 在任务开始前从 global 池预取相似经验，在任务结束后只沉淀经过 Verifier 确认的路线、配方和失败模式。后续任务通过关键词、标签或语义相似度召回，再按需解析完整状态。

StatePool 当前支持：

关键词、标签、语义和混合检索；
pool / state_type / visibility / TTL / confidence 过滤；
FTS5、标签索引和向量索引；
state_ref 的 summary/ref/full 多级解析；
基于 provenance 和 dedupe_key 的状态去重；
命中次数、复用次数和经验提升统计。

🛡️ CVE 复现任务落地

漏洞复现任务用于验证协议的领域适配器。正式任务由六个领域 Agent 和一个 StatePoolAgent 协作完成。

Agent	职责	主要产出
PlannerAgent	拆分任务、选择能力、判断是否存在可复用路线	plan、reuse route
InfoRetrieverAgent	获取 CVE、PoC、补丁和部署信息	cve_info、setup_hint
EnvBuilderAgent	分析前置条件、部署环境、初始化业务状态	deployment contract、endpoint、session
ExploitAgent	执行负对照、攻击候选和证据采集	negative_control、http_trace、evidence
VerifierAgent	独立比较正负观察并排除误报	verification、verdict
ExperienceAgent	预取历史经验并沉淀已验证结论	recipe、route、insight
StatePoolAgent	提供状态写入、检索、解析和提升服务	state refs、memory hits

一次完整任务的主链路为：

CVE 复现任务主链路：信息检索与经验预取并行，随后依次完成环境分析、部署初始化、受控利用、验证和经验沉淀

信息检索与经验预取可以并行；部署、攻击、验证和经验沉淀则按照状态依赖串行执行。每个 Agent 通过 ReAct 循环调用真实工具，工具 Observation 被提炼为 ASU 后写入 SSSP。

🧪 实验验证

仓库保留两组目标不同、口径独立的实验数据。系统支持 M0–M3 四档运行；正式归档选取两端配置 M0 与 M3，验证完整机制相对纯文本基线的总体收益。

实验设计与模式

四种模式运行同一套 Agent 和任务链，只切换通信、状态和记忆机制：

模式	通信	StatePool	Embedding / SHM	跨任务记忆
M0	冗长自然语言 envelope	—	—	—
M1	AMP / MessagePack + `state_ref`	✓	—	—
M2	M1 + 语义状态交换	✓	✓	—
M3	M2 + 全局经验复用	✓	✓	✓

指标口径与实验产物

Broker 将通信拆成两个口径：

handoff：Orchestrator 与领域 Agent 之间的协作交接，是低开销通信的主要比较对象；
pool：Agent 与 StatePool 之间的基础设施 I/O，单独计量并完整呈现状态池自身成本。

comm_tokens 衡量线上通信载荷的等价 token，llm_tokens 记录 LLM API 输入输出。每次运行同时生成 metrics.json、metrics.csv、token_ledger.csv、消息 Trace、Agent 执行报告和 HTML 汇总页。

正式十任务 M0/M3 对照

formal_20260707_203555 同时运行独立的 M0 与 M3 进程，包含十个连续真实 Web CVE 场景。

对照条件与归档证据

对照条件	M0 纯文本基线	M3 本方案	归档证据
任务输入	相同的 10 个场景及执行顺序	相同的 10 个场景及执行顺序	`manifest.json` 的 `scenarios` 与子进程命令
部署配置	`real + strict-real`	`real + strict-real`	两个子进程的 `command`
LLM 模型	`claude-sonnet-4-6`	`claude-sonnet-4-6`	两组 `llm_usage.jsonl`
温度与缓存	`temperature=0.0`，缓存关闭	`temperature=0.0`，缓存关闭	LLM 客户端默认配置与 `cache_hit=false`
运行隔离	独立进程、结果、记忆和 Trace 目录	独立进程、结果、记忆和 Trace 目录	`manifest.json` 的 `children`

当次运行没有保存随机种子和代码提交号。补充后的 manifest 将这两项标记为 not_recorded，公平性结论覆盖相同任务输入、模型、部署参数、温度和缓存配置；后续正式批次应在启动时同步固化随机种子与代码提交号。

指标	M0	M3
Agent 间交接 token（handoff）	7,841,941	199,148
总通信等价 token（comm）	7,841,941	392,842
工具调用次数	331	302
非文本状态传递次数	0	118
记忆检索命中率	0	79.05%
完整执行轮次	10/10	10/10
Verifier 确认场景	5/10	8/10

该轮中，M3 的 handoff 载荷降低 97.46%，总通信载荷降低 94.99%。实验同时独立记录 LLM token；状态检索和更完整的 Agent 内部上下文仍可能增加模型输入。“Agent 间通信优化”与“模型调用成本优化”分别采用独立指标衡量。

逐轮协作通信 Token	逐轮记忆命中

红色表示纯文本协作模式 M0，深蓝色表示完整机制模式 M3；图表和正文采用同一批正式实验数据。

完整归档：formal comparison · combined metrics · manifest

正式十任务实验量化 M0/M3 在通信、状态与记忆机制上的收益；openEuler 24.03 LTS-SP3 部署章节提供目标平台的安装与核心路径复现方法，两类材料共同覆盖性能验证与平台交付要求。

连续两任务可控对比

任务组使用 real + strict-real，先完成 CVE-2025-22619 环境建立与验证，再在第二个任务中复用前序状态。

指标	M0	M3	变化
Agent 间交接 token（handoff）	52,383	20,973	-59.96%
总通信等价 token（comm）	52,383	41,173	-21.40%
工具调用次数	45	43	-4.44%
非文本状态传递次数	0	18	M3 生效
记忆检索命中率	0	70.59%	M3 生效
Verifier 确认场景	2/2	2/2	结果持平

数据源：metrics.json · token_ledger.csv · presentation.html

⚡ 快速开始

环境要求

Python 3.10 或更高版本；
Linux / openEuler 用于完整 IPC 路径；
Docker
LLM API、sentence-transformers、FAISS/ChromaDB

安装

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

如果只验证 AMP、SSSP、共享内存和规则降级链路，可以先安装最小依赖：

python -m pip install numpy msgpack tiktoken

验证协议与状态池

python tests/test_sssp.py
python tests/test_pool_messaging.py

这两条命令分别覆盖 AMP/ASU/检索/生命周期等核心单元，以及 Agent 通过消息总线访问 StatePool 的集成链路。

运行一个离线实验

python eval/sssp_runner.py \
  --limit 2 \
  --modes m0,m3 \
  --deploy-mode simulated

无 API Key 时，Agent 使用确定性规则路径；语义模型不可用时使用哈希向量。运行结果写入 var/sssp_results/，会更新该目录中的报告和 trace。

LLM

当前完整实验系统使用 Anthropic SDK，并支持兼容代理：

export ANTHROPIC_API_KEY="<your-key>"
export ANTHROPIC_BASE_URL="<optional-compatible-endpoint>"
export OOA_LLM_MODEL="claude-sonnet-4-6"
export OOA_LLM_CACHE=0

.env 会从项目根目录自动加载。密钥、缓存和本地状态库保持为本地文件，并由忽略规则排除在版本控制之外。

运行连续任务

以下命令要求本机已经具备 Docker 环境和对应复现资产：

python eval/sssp_runner.py \
  --scenario-ids A1-CVE-2025-22619-setup,A2-CVE-2025-22619-reproduce \
  --modes m0,m3 \
  --deploy-mode real \
  --strict-real

--strict-real 会禁止真实部署失败后静默退回模拟结果，适合正式实验和结果审计。

🐧 openEuler 适配

项目目标环境为 openEuler 24.03 LTS-SP3。该版本提供 x86_64 与 AArch64 安装介质；核心路径面向服务器环境，直接使用 Linux 提供的进程、Socket、共享内存、文件锁和资源限制能力。

项目机制	openEuler / Linux 落点
Agent 进程隔离	`multiprocessing.Process`
控制面通信	Unix Domain Socket
消息边界	长度前缀 Socket Frame
非文本数据面	POSIX Shared Memory、`/dev/shm`、mmap
状态持久化	SQLite、FTS5、向量索引
并发同步	文件锁、线程锁、原子 generation
CodeAct 隔离	独立进程、临时目录、timeout、rlimit；可扩展 nsjail

openEuler 上的基础环境：

sudo dnf install -y python3 python3-pip python3-devel gcc gcc-c++ git

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install numpy msgpack tiktoken

上述依赖可以验证 AMP、SSSP 和规则降级链路。安装 requirements.txt 中的可选依赖后，可进一步启用真实语义模型、隐藏状态实验和向量库；AArch64 环境可结合对应 PyTorch/Transformers wheel 或本地软件源部署。

openEuler 核心路径：

顶层 core/ 运行时提供 UDS 通信路径；
src/os_agent/state_exchange/l1_embedding.py 使用 fcntl、flock 和 /dev/shm，落实 Linux/openEuler 共享内存与文件锁机制；
真实 CVE 模式通过目标项目构建工具、容器镜像和网络环境完成端到端复现；
十任务实验归档与 openEuler 部署流程构成完整验证链：前者提供机制性能证据，后者提供目标平台复现入口。

🔭 可观测性与产物

一次运行会留下外层协议 trace、Agent 内层 ReAct trace、LLM 使用量、状态池事件和指标账本。

metrics.json                 聚合指标与逐任务结果
metrics.csv                  便于二次分析的表格
token_ledger.csv             逐轮通信与模型 token 账本
trace_<mode>.jsonl           AMP/Broker 外层消息轨迹
agent_react_<mode>.jsonl     Agent action/observation 轨迹
agent_execution_<mode>.html  可阅读的 Agent 执行报告
presentation.html            汇总展示页

前端展示读取：

var/sssp_results/
var/formal_parallel_runs/formal_20260707_203555/

前端位于 frontend/，数据构建入口为：

python scripts/build_frontend_data.py

📁 仓库结构

agents/             当前领域 Agent、ReAct 循环和 StatePoolAgent
core/               AMP、Broker、调度、传输、状态交换和 trace
sssp/               ASU、StatePool 和状态路由
memory/             共享记忆、检索和经验反思
llm/                可选 LLM 客户端和使用量记录
tasks/              CVE 场景、连续任务组和研究任务
tools/              CVE 检索、真实环境部署和领域工具
sandbox/            CodeAct 隔离执行
eval/               M0-M3 实验、指标计算和报告生成
scripts/            演示、正式并行实验和数据导出
frontend/           静态可视化页面
var/                已归档的实验数据和报告
src/os_agent/       L1 工程化核心包
examples/           L1、P0-P3 和真实 API 示例
tests/              单元、集成和场景切片测试
docs/               设计、部署和实验文档
config/             协议映射与状态交换配置

📚 文档

文档	内容
SSSP-Agent 系统设计	当前协议、状态池、Agent 和实验模式
openEuler 部署	openEuler 24.03 LTS-SP3 安装与运行
实验报告	指标定义、结果和图表
L1 实现说明	L1 向量状态交换实现
贡献指南	分支、提交和本地验证约定