AgentLink：多智能体通信与记忆原型系统

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

AgentLink 是一个面向多智能体协作的系统原型，提供 多Agent编排、结构化通信、KV 状态传递、长期记忆检索和 CodeAct 工具执行，并由 CLI、Web 和评测脚本。

当前支持三种 Agent 间传输方式：

• text：传递自然语言结果。
• json_schema：使用统一结构化字段传递摘要、事实、简短推理步骤、结论、来源和限制。
• kv：使用 vLLM 执行 latent step，并在 Agent 之间传递真实 KV 状态。

长期记忆由 SQLite 保存文本记忆、实体和关系，向量索引负责语义检索，SQLite 图视图或 Neo4j 负责图关系访问。

1. 环境要求

推荐运行环境：

• Python 3.11。
• NVIDIA GPU 与可用 CUDA 驱动：本地大模型和 KV 状态传递需要。
• Node.js 18及以上版本：仅CLI和WASM执行环境需要。
• Docker：仅选择Docker CodeAct沙箱时需要。

推荐使用 uv 安装：

uv sync --locked
source .venv/bin/activate

也可以使用普通虚拟环境：

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

2. 模型与推理后端

系统默认使用以下模型：

• 主模型：Qwen/Qwen3-8B。
• 记忆文本与关系向量检索：BAAI/bge-small-en-v1.5。
• 实体与关系抽取：knowledgator/gliner-relex-base-v1.0。
• 记忆候选轻量重排：cross-encoder/ms-marco-MiniLM-L6-v2。

模型可以填写 Hugging Face 仓库名，也可以填写本地目录。首次联网运行时依赖库会自动下载；离线环境应提前将模型放到本地，并在 configs.yaml 中填写路径。

本地 vLLM

推荐配置：

llm:
  backend: vllm
  model: qwen3-8b
  model_path: /path/to/Qwen3-8B
  served_model_name: qwen3-8b
  vllm_host: 127.0.0.1
  vllm_port: 8000
  gpu_memory_utilization: 0.95
  tensor_parallel_size: 1
  max_model_len: 40768
  dtype: bfloat16
  enable_thinking: false
  auto_start_vllm: false

手动启动配置中的 vLLM 模型服务：

python scripts/start_vllm_from_config.py --config configs.yaml

如果使用CLI， 用户也可以设置 llm.auto_start_vllm: true，由 CLI 启动和停止 API 服务。直接运行 Web 后端时，应先执行上面的启动命令，或者连接已经运行的 vLLM 服务。

API调用

兼容 OpenAI Chat Completions 的服务使用：

llm:
  backend: openai
  base_url: https://api.example.com/v1
  model: model-name
  api_key: ""

密钥可以通过环境变量传入：

export LLM_API_KEY="your-api-key"

openai 后端支持 text、json_schema 和 CodeAct，不支持本项目的 KV 状态传递。

3. 数据集与记忆状态

创建本地数据目录：

mkdir -p datasets

LoCoMo

包含10组长程对话、272个会话和1,986条问答，用于评测系统对跨会话事实、时间关系和多跳证据的长期记忆能力。

git clone https://github.com/snap-research/locomo.git datasets/locomo

Web/CLI 启动时可以从 LoCoMo JSON 构建记忆：

runtime:
  output_dir: outputs/agentlink
  memory_source: datasets/locomo/data/locomo10.json
  existing_memory_dir: null
  memory_text_limit: -1

memory_source是待构建的源 JSON 文件，不是数据集名称。当前主服务的自动导入入口按照 LoCoMo 会话格式解析。构建完成后，memory.sqlite和向量库会写入runtime.output_dir。

已有记忆状态应直接配置状态目录：

runtime:
  memory_source: null
  existing_memory_dir: /path/to/existing-memory-state

该目录至少需要包含memory.sqlite和vector_db/；vector_db/保存系统构建并读取的持久化向量索引。

MedQA

医学问答数据集。项目使用的是LatentMAS提供的300条英文四选一实验子集。

下载到推荐位置：

mkdir -p datasets/medqa
curl -L https://raw.githubusercontent.com/Gen-Verse/LatentMAS/main/data/medqa.json \
  -o datasets/medqa/medqa.json

数据来源：

• MedQA：https://github.com/jind11/MedQA
• 本项目实验使用的300条整理版本：https://github.com/Gen-Verse/LatentMAS/blob/main/data/medqa.json

评测配置可以填写：

eval:
  dataset: medqa
  dataset_path: datasets/medqa/medqa.json
  output_dir: outputs/eval
  limit: null

运行示例：

LLM_BASE_URL=http://127.0.0.1:8000/v1 \
python scripts/run_agent_message_qwen3_8b.py \
  --dataset medqa \
  --dataset-path datasets/medqa/medqa.json \
  --mode json_text \
  --output outputs/medqa-json-text \
  --limit 10

--dataset-path是必填项，系统不会生成备用样本，也不会将测试替身当成MedQA结果。加载器支持JSON或JSONL，每条记录需要包含question或query、options以及answer字段。

MultiAgentBench

MultiAgentBench是面向多智能体协作能力的评测基准。本项目使用其中的Research和Coding子集，测试复杂研究与代码开发任务中的智能体编排和协同执行能力。

git clone https://github.com/ulab-uiuc/MARBLE.git ref/MARBLE

分别运行 Research 或 Coding 子集：

python scripts/run_multiagentbench.py --scenario research --backend vllm --model qwen3-8b --output-dir outputs/multiagentbench/research
python scripts/run_multiagentbench.py --scenario coding --backend vllm --model qwen3-8b --output-dir outputs/multiagentbench/coding

脚本默认读取ref/MARBLE/multiagentbench/<scenario>/<scenario>_main.jsonl，并将完整模型回答写入输出目录。使用外部评估模型时，另外传入--evaluator-model、--evaluator-backend openai和--evaluator-base-url。

MemGym

面向智能体长程记忆能力的评测基准。本项目使用其中包含1,194条3至6跳任务的DeepResearch子集，测试多轮检索信息的记忆与整合能力

git clone https://github.com/WujiangXu/MemGym.git datasets/MemGym
python scripts/evaluate_memgym_dr.py --help

其他实验通过scripts/中的独立适配器指定数据路径、样本数和输出目录：

python scripts/run_qwen3_8b_text.py --help
python scripts/run_qwen3_8b_json_text.py --help
python scripts/run_qwen3_8b_kv.py --help

4. 项目目录

cli/                        TypeScript 交互式 CLI、配置校验和服务生命周期管理
docker/codeact/             CodeAct Docker 沙箱定义
scripts/                    vLLM 启动、评测脚本
src/
  agents/                   Agent 基础定义与角色实现
  codeact/                  CodeAct 循环、执行器、代理和运行时工具注入
  config/                   Python 统一配置、YAML 加载和环境变量覆盖
  evaluation/               数据集加载、系统评测运行器和指标
  latent/                   状态传输记录与通信指标
  llm/                      vLLM、OpenAI 客户端
  memory/                   记忆写入、实体关系抽取、建图、检索
  protocol/                 结构化消息、A2A 会话和输出适配
  runtime/                  消息总线、会话状态和持久化
  server/                   FastAPI 后端与 AgentGroup 运行链路
  storage/                  ChromaDB、内存向量库等存储适配
  tools/                    记忆、检索、HTTP、PDF、Excel、DOCX 等工具
  web/                      Web 静态资源和兼容启动入口
tests/                      单元、集成、沙箱和系统边界测试
requirements.txt            可安装依赖范围
pyproject.toml / uv.lock    uv项目定义与固定环境锁

5. 统一配置

CLI、Web、模型启动脚本和系统运行时使用同一份YAML配置。默认按以下顺序查找：

1. 命令行显式传入的--config路径。
2. AGENTLINK_CONFIG环境变量。
3. 项目根目录configs.yaml。
4. 项目目录.agentlink/config.yaml。
5. 用户目录~/.agentlink/config.yaml。

建议在根目录新建configs.yaml`。下面是可直接调整的基础配置：

server:
  host: 127.0.0.1
  port: 7860
  auto_start: true
  startup_timeout: 30

llm:
  backend: vllm
  model: qwen3-8b
  model_path: /path/to/Qwen3-8B
  served_model_name: qwen3-8b
  temperature: 0.6
  top_p: 0.95
  max_new_tokens: 4096
  gpu_memory_utilization: 0.95
  tensor_parallel_size: 1
  max_model_len: 40768
  vllm_host: 127.0.0.1
  vllm_port: 8000
  auto_start_vllm: false
  auto_stop_vllm: true
  vllm_startup_timeout: 600
  vllm_extra_args: []
  enable_thinking: false
  dtype: bfloat16
  kv_latent_steps: 40

memory:
  embedding_model: BAAI/bge-small-en-v1.5
  embedding_device: auto
  reranker_model: cross-encoder/ms-marco-MiniLM-L6-v2
  reranker_device: cpu
  vector_backend: chroma
  default_top_k: 5
  context_max_tokens: 1024
  graph_store: sqlite
  graph_expand: true
  knowledge_extractor: gliner-relex
  gliner_model: knowledgator/gliner-relex-base-v1.0
  gliner_device: auto
  gliner_threshold: 0.75
  gliner_relation_threshold: 0.70
  gliner_related_to_threshold: 0.85
  gliner_max_relations: 12
  neo4j_uri: bolt://localhost:7687
  neo4j_user: neo4j
  neo4j_password: ""
  neo4j_database: null

runtime:
  output_dir: outputs/agentlink
  agent_groups_dir: .agentlink/agentgroups
  memory_source: null
  existing_memory_dir: null
  memory_text_limit: -1
  gliner_relex_cache_dir: null
  llm_max_tokens: 1024
  llm_context_window: 8192

pipeline:
  default_group: plan-retrieve-execute
  default_profile: default

profiles: {}

compact:
  enabled: true
  model_profile: default
  trigger_tokens: 6000
  keep_recent_turns: 4
  max_summary_tokens: 512

常用说明：

• profiles用于给不同 Agent 选择不同模型服务；未指定时使用llm作为default profile。
• pipeline.default_group选择默认 AgentGroup。内置组包括plan-retrieve-execute、plan-execute、retrieve-execute、single、codeact-planner-executor和codeact-research。
• 用户 AgentGroup 保存在runtime.agent_groups_dir。
• memory.default_top_k为默认值，CLI/Web请求时可以在设置里修改；最终记忆上下文长度还受memory.context_max_tokens限制。
• graph_store: neo4j需要填写 Neo4j 连接信息；密码为空或连接失败时，主服务会回退到 SQLite 图视图。
• 密钥和密码优先使用LLM_API_KEY、NEO4J_PASSWORD等环境变量。

6. 启动 CLI 与 Web

CLI

首次使用时安装并构建CLI：

npm --prefix cli install
npm --prefix cli run build

npm --prefix cli start -- --config configs.yaml

当server.auto_start: true时会自动启动src.server.app。当llm.auto_start_vllm: true且当前传输不是原生KV时，CLI也会启动配置中的vLLM API服务。

进入CLI后可使用/help查看AgentGroup、模型profile、传输方式、记忆检索和会话命令。

Web

AGENTLINK_CONFIG=configs.yaml python -m src.server.app

浏览器访问：

http://127.0.0.1:7860/

CLI 与 Web 都调用src.server中的同一套AgentGroup、模型、CodeAct和记忆运行链路；src.web.app只保留兼容启动入口。

7. CodeAct 沙箱配置

CodeAct支持local、ipython、wasm和docker四种执行环境。统一配置如下，切换时通常只需要修改sandbox一项：

codeact:
  sandbox: docker          # local | ipython | wasm | docker
  max_turns: 6
  code_timeout: 8.0
  llm_timeout: 90.0
  proxy_host: 127.0.0.1
  docker_memory: 1g
  docker_cpus: 1.0
  docker_pids_limit: 128
  docker_read_only: true

执行环境	额外准备	隔离边界	适用场景
local	无	与后端处于同一Python进程，非安全隔离	可信代码、开发调试、最快启动
ipython	Python依赖中已包含IPython	与后端处于同一进程，非安全隔离	需要IPython执行语义的可信任务
wasm	Node.js和Pyodide依赖	Python运行在Pyodide/WASM中；宿主工具只通过白名单代理调用	轻量隔离
docker	Docker和daemon	独立容器、只读根文件系统、能力与资源限制	不可信代码或需要更强隔离的任务

最少准备命令

local和ipython在Python依赖安装完成后不需要额外命令。

WASM只需安装根目录依赖：

npm install

Docker只需确认daemon可用：

docker info

第一次执行Docker沙箱时，系统会自动根据docker/codeact/Containerfile.openeuler检查或构建沙箱镜像。沙箱会自动：

• 使用Docker bridge网络和host.docker.internal访问宿主工具代理。
• 根据Docker daemon检测SELinux，并仅在需要时添加挂载标签。
• 启用--cap-drop=ALL、no-new-privileges、PID/CPU/内存限制和临时/tmp。
• 默认使用只读根文件系统，只挂载当前执行的临时工作目录。

8. 测试

快速运行核心单元与集成测试：

python tests/run_suite.py --suite core --no-coverage

运行Python全量测试、覆盖率门槛和CLI测试：

python tests/run_suite.py --suite full

只检查CLI：

npm --prefix cli test

GPU模型、原生KV和外部数据集测试不会被普通无卡测试伪造为成功；需要模型、GPU或Docker/WASM运行时的测试应在对应环境显式启用。

9. 输出与运行状态

默认运行状态位于runtime.output_dir，评测脚本使用各自的--output-dir。逐样本评测通常增量写入，任务中断时已完成记录仍会保留。

常见文件：

• memory.sqlite：文本记忆、实体、关系和证据映射。
• vector_db/：持久化向量索引。
• runtime_events.jsonl：消息、检索和状态传输事件。
• sessions.jsonl、messages.jsonl：会话与Agent消息记录。
• memory_search_log.jsonl：记忆检索诊断信息。
• state_transfers.jsonl：真实状态传输元数据与耗时。
• records.jsonl：逐样本模型输出。
• summary.json或metrics.json：聚合正确率、token、耗时和通信指标。
• vllm.log：由CLI托管vLLM时的服务日志。

outputs/、output/、本地配置、模型、数据集、缓存和密钥均已排除在Git发布内容之外，不应作为源码提交。