<<<<<<< HEAD

Multi-agent 真实实验复现指南

• 实时真实实验：调用 DeepSeek、BGE、Chroma、共享内存、仓库内真实 codec 和 Wikipedia；任何组件降级都会因 --strict-real 而失败。

默认 config/config.yaml 是离线 mock 配置，供开发和测试使用。正式实验请使用独立的本机配置，且绝不提交密钥。

环境准备

需要 Python 3.11、可用的 /dev/shm、联网下载 BGE/tiktoken，以及有效的 DeepSeek API Key。首次真实运行会下载模型和 token 编码缓存。

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt
python3 -m pytest -q

创建本机真实配置和密钥环境：

cp config/config.real.example.yaml config/config.real.yaml
cp .env.example .env
# 编辑 .env，填入真实 DEEPSEEK_API_KEY
set -a; . ./.env; set +a
export MULTIAGENT_CONFIG=config/config.real.yaml

DEEPSEEK_BASE_URL 必须为 https://api.deepseek.com，密钥必须只存在于进程环境或 .env 中；

实时真实实验

以下命令在同一目录生成对比数据、图表、外部证据快照和完整依赖锁定文件。实际模型调用次数取决于复用命中，完整对比运行最多约 50 次模型调用。

run_dir=artifacts/real-run-$(date +%Y%m%d-%H%M%S)
mkdir -p "$run_dir"

python3 -m experiments.run_continuous \
  --strict-real --mode struct \
  --output "$run_dir/continuous.json"

python3 -m experiments.run_compare \
  --strict-real \
  --output "$run_dir/compare.json"

每个指标 JSON 会配套生成：

continuous.json
continuous.evidence.jsonl
continuous.environment.lock.txt
compare.json
compare.evidence.jsonl
compare.environment.lock.txt
token_comparison.png
memory_hit_rate.png
duration_comparison.png

*.evidence.jsonl 保存每条外部资料的正文、查询词、来源 URL、页面版本信息、抓取时间和 CID。CID 必须等于正文 UTF-8 的 SHA-256。*.environment.lock.txt 是该次实际运行环境的完整 pip freeze，用于重建依赖环境。

实时结果必须同时满足：

• provenance.strict_real 为 true；
• fallback_used 与 mock_used 都为 false；
• 每个组件清单的 LLM、嵌入器、记忆、共享内存、codec、retrieval 均为 real；
• production_ready 为 true；
• 研究任务的 document_refs 存在 source_url，且对应记录存在于证据 JSONL 中。

提交文档

• 系统设计文档：架构、数据面、协议、组件门禁和安全设计。
• 部署文档：隔离环境、密钥配置、离线验证和严格真实实验命令。
• 实验报告：已提交真实实验的配置、结果、证据与复核结论。

• 演示视频

  赛题题目：一种面向多智能体协作的低开销通信、状态传递与共享记忆机制（社区赛题）

赛题说明：

随着大模型应用从单 Agent 问答逐步扩展到多 Agent 协同执行，智能系统正在从“单点生成”向“分工协作”演进。在检索增强生成、复杂任务规划、代码协作、办公自动化、知识分析等场景中，往往需要多个 Agent 分别承担规划、检索、执行、总结、生成等不同角色，并通过相互协作完成复杂任务。当前主流多 Agent 系统大多以自然语言或 JSON 作为通信媒介，即一个 Agent 将其中间结果组织成文本，再传递给其他 Agent 进行解析和继续处理。这种方式虽然通用性较好，但在多轮、多 Agent、复杂任务场景下存在明显不足：一是通信内容冗长、重复上下文多，token 消耗高；二是中间结果需要在“内部状态—文本—内部状态”之间反复转换，导致时延增加并可能带来语义损耗；三是任务执行过程中形成的中间知识和经验难以沉淀，系统在处理相似任务时往往仍需从头开始，缺乏持续积累和复用能力。 本赛题面向多智能体协作系统中的基础设施问题，要求选手围绕低开销通信、非文本状态传递、共享记忆复用三个方面，设计并实现一套可运行的原型系统。系统一方面需要通过结构化通信协议替代冗长自然语言交互，将 Agent 间传递的内容收敛为动作、参数、结果、能力等高密度语义单元，以降低通信成本和解析开销；另一方面需要探索 embedding、语义向量、隐藏状态特征或其他中间表示在 Agent 之间的直接传递机制，减少不必要的文本编解码过程，提高协作效率。在此基础上，还需将任务执行过程中形成的摘要、证据、策略、经验等内容沉淀为可标识、可检索、可复用的共享记忆单元，使系统具备跨任务的知识积累和协同增强能力。 本课题区别于一般的工作流编排类题目，重点不在于简单调用大模型接口和外部工具，而在于研究多智能体协作中的“系统层机制”：包括 Agent 间统一通信协议设计、中间状态表示与交换方式、共享记忆组织模型、跨任务复用机制以及整体运行效率验证。选手需面向开源操作系统或通用 Linux 环境完成原型实现，通过可复现实验验证该机制相较传统纯文本协作方式在通信开销、任务时延和记忆复用方面的改进效果。
具体要求：

• 系统需支持不少于 3 个 Agent 协同运行，至少覆盖任务规划、信息检索、总结生成、工具执行等角色中的 3 类，并能够完成一个包含多步骤处理过程的复杂任务；
• 系统需设计并实现一套面向 Agent 间协作的结构化通信机制，通信内容至少包括动作类型、输入参数、返回结果和能力描述，并支持基本的握手、能力发现或协议映射机制，不得仅通过自然语言长文本直接透传全部协作信息；
• 系统需同时支持“纯文本协作模式”和“结构化协议协作模式”，并在相同任务条件下完成可复现实验对比；
• 系统需实现一种非文本中间状态传递机制，支持 embedding、语义向量、隐藏状态特征或其他中间表示在 Agent 间直接交换，并说明其生成方式、传递方式、接收方式及后续使用方式；
• 系统需实现共享记忆模块，能够将任务执行过程中的中间结果、摘要、经验片段、证据链、结论或策略保存为统一的记忆单元，并为每条记忆记录至少包含记忆 ID、来源 Agent、创建时间、任务主题和摘要描述等基本元数据；
• 系统需支持按关键词、标签或语义相似度检索历史记忆，并允许不同 Agent 在后续任务中直接复用已有记忆；
• 系统需至少设计 2 组具有关联性的连续任务，验证结构化通信、非文本状态传递和共享记忆复用在减少重复计算、降低协作开销和提升任务效率方面的实际效果；
• 系统需统计并展示 Agent 间消息次数、文本通信 token 或字符开销、非文本状态传递次数及数据规模、单任务总耗时、共享记忆命中率及整体性能提升情况；
• 系统架构中至少应包含多 Agent 运行时、协议解析与调度模块、状态交换模块、共享记忆存储与检索模块和评测模块，并能够稳定执行不少于 10 轮连续任务；
• 需提交完整源码、系统设计文档、部署文档、实验报告和演示视频，能够支持评审现，鼓励结合 IPC、共享内存、Socket、向量数据库、WASM/容器沙箱、eBPF 等系统技术提升实现质量。
• 鼓励系统能够支持基于 CodeAct 模式的 Agent 执行机制，允许 LLM 生成 Python 可执行代码，并在轻量沙箱中安全运行，实现低延迟、可隔离的代码执行与结果回传能力。

  赛题要求：

• 系统支持不少于3个Agent协同运行，覆盖规划、检索、执行、总结等角色；
• 设计结构化通信协议替代自然语言交互；
• 实现非文本中间状态传递机制（embedding/语义向量/隐藏状态）；
• 实现共享记忆模块，支持记忆的存储、检索和复用；
• 至少设计2组关联性连续任务进行验证；
• 提供通信开销、任务时延、记忆复用等方面的性能对比数据。

  评分细则（明确评审角度、标准和分值范围）：

• 通信效率（25分）：相比纯文本协作的token节省效果
• 状态传递创新（20分）：非文本状态传递机制的设计新颖性
• 记忆复用效果（20分）：跨任务记忆复用的准确性与效率
• 系统完整性（20分）：多Agent协作的稳定性与功能覆盖
• 实验验证（15分）：性能对比数据的说服力

  交付要求：

  最终交付的代码需在 openEuler 24.03-LTS-SP3 操作系统版本上能够正常编译、运行和测试。

  赛题联系人：

• 陈老师 chengong15@huawei.com
• 李老师 liping136@huawei.com

  97dd4cf3488059a0f666aada079f014e4e604eda