---

项目简介

传统 Agent 会在每轮推理中重复拼接系统提示、工具说明、完整对话历史和工具原始输出。随着任务轮次、工具数量和推理分支增加，输入词元持续增长，进一步造成 Prefill 开销上升、TTFT 增大、KV Cache 压力加剧以及并发处理能力下降。

AgentMem 将完整任务历史保留在事件与外部存储层，仅把当前有效的任务状态、工具摘要、证据引用、近期上下文和当前问题组织为稳定、紧凑的模型输入；推理侧通过统一多模型网关，结合任务类型、上下文长度、优先级、会话亲和、缓存会话、KV Cache 使用率和等待队列选择合适的模型服务，并在输出不满足约束时回退至大模型。

项目由两个代码仓库共同组成：

仓库	主要职责
Agent-Memory-Manager	轻量 Agent Runtime、事件溯源式记忆、工具调用与结果外置、分支上下文管理、Benchmark、评价与报告
AgentMem-vLLM	OpenAI-compatible 多模型网关、引擎状态采集、Agent-aware 路由、会话亲和、质量门控、大模型回退和流式性能观测

---

核心能力

• 轻量 Agent Runtime：支持单轮任务、交互式会话、工具调用、多阶段执行、下一步动作循环和基准测试。
• 事件溯源式记忆：将用户消息、工具调用、工具结果、模型响应、记忆增量和最终答案记录为追加式事件流。
• 结构化任务状态：从事件流投影生成目标、约束、事实、决策、待办、问题、告警和工具引用等当前状态。
• 工具结果外置：完整结果保存到外部结果空间，Prompt 默认只携带摘要、结果标识和证据引用。
• 证据按需回填：需要核验日志行、代码片段或表格内容时，根据结果标识和分块索引读取原始证据。
• 技能按需加载：稳定 Prompt 中只保留工具简介，命中工具后再加载对应完整技能说明。
• 稳定 Prompt 构建：固定系统规则、工具简介和任务状态的组织顺序，为 vLLM Prefix Cache 复用创造条件。
• 分支上下文共享：采用“共享上下文 + 分支增量”的 Copy-on-Write 表示，避免每个分支复制完整历史。
• 多模型状态感知路由：根据任务复杂度、上下文规模、服务负载、KV Cache 状态和会话缓存选择小模型或大模型。
• 质量门控与回退：校验非空输出、JSON 结构、必需字段和必需子串；小模型结果不合格时回退到健康的大模型。
• 可复现 Benchmark：覆盖工具密集、长会话、多阶段、分支推理、前缀缓存、消融、并发和多模型路由场景。
• 运行指标观测：记录输入/输出词元、TTFT、TPOT、端到端时延、吞吐量、路由准确率、KV Cache 使用率和 GPU 显存等指标。

---

系统架构

flowchart LR
    U[用户 / CLI / Benchmark] --> R[轻量 Agent Runtime]

    subgraph M[Agent-Memory-Manager]
        R --> E[事件日志]
        E --> P[记忆投影]
        P --> S[Task State View]
        S --> C[状态归约]
        C --> V[稳定 Prompt 构建]

        R --> T[工具注册与路由]
        T --> X[工具执行]
        X --> O[工具结果外置]
        O --> A[摘要 / Result ID / 证据引用]
        A --> E
    end

    V --> G[AgentMem-vLLM 多模型网关]
    G --> SM[vLLM 小模型引擎]
    G --> LM[vLLM 大模型引擎]

    SM --> Q[质量门控]
    LM --> Q
    Q -->|通过| R
    Q -->|不通过| LM

    G --> K[引擎状态与缓存统计]
    K --> G

一次请求的执行流程

1. Runtime 接收用户任务，初始化运行、智能体和会话标识。
2. 当前输入、工具调用和模型输出被追加记录为任务事件。
3. 记忆模块从事件流生成当前任务状态，并执行去重、摘要和容量控制。
4. 若任务需要外部信息，Runtime 路由并执行工具；完整工具结果外置保存。
5. Prompt 仅组织稳定系统前缀、结构化任务状态、工具摘要、证据引用、近期上下文和当前问题。
6. 多模型网关解析 agent_meta，评估任务所需模型层级。
7. 网关结合引擎健康状态、活动请求、等待队列、KV Cache 使用率、会话亲和和缓存会话选择引擎。
8. 模型生成结果后执行质量校验；必要时回退至大模型。
9. Runtime 解析结果、更新事件和记忆增量，继续下一阶段或输出最终答案。
10. Benchmark 与指标采集器保存 CSV、JSON、事件日志、状态快照和报告。

---

四个核心模块

1. 轻量 Agent Runtime

负责统一组织“任务输入—阶段判断—工具调用—Prompt 构建—模型推理—结果解析—状态更新—最终输出”的执行闭环。它保留 Agent 实验所需的多轮、工具和分支能力，定位为轻量运行框架与 Benchmark Harness，而不是完整 AutoGPT 类平台。

2. 事件溯源式记忆

将任务执行过程记录为 user_message、tool_call、tool_result、assistant_response、memory_delta、final_answer 和 metric 等事件。记忆投影器将事件流转换为当前有效的 Task State View；归约器对重复事实、失效决策、已完成待办和字段容量进行控制；渲染器按稳定顺序构建模型输入。

3. 工具调用与输出管理

统一管理工具注册、能力描述、任务路由、工具执行、原始结果存储、摘要生成和证据回填。日志、代码、文件、表格和仓库扫描结果保存在外部结果空间，Prompt 默认只保留摘要、result_id、元数据和必要证据，需要时再按分块读取原文。

4. vLLM 后端优化

通过 Ray Serve/FastAPI 提供 OpenAI-compatible 统一入口，集中管理多个 vLLM 引擎。网关解析任务类型、优先级、会话标识、路由模式和质量约束，并维护引擎健康状态、活动请求、等待请求、KV Cache 使用率和缓存会话集合。路由策略在模型能力、服务负载和缓存复用之间进行权衡，模型输出不满足结构约束时触发大模型回退。

---

代码仓库结构

建议将两个仓库放在同一父目录下：

AgentMem/
├── Agent-Memory-Manager/
│   ├── agentmem/
│   │   ├── runtime/          # Agent 执行循环与模型客户端
│   │   ├── event_memory/     # 事件日志、Memory Delta、投影和归约
│   │   ├── memory/           # Prompt 构建、外置结果、分支上下文
│   │   ├── tools/            # 工具注册、路由与执行
│   │   └── metrics/          # 指标采集与校验
│   ├── benchmarks/
│   │   ├── tasks/            # 固定 JSONL 任务
│   │   ├── workloads/        # 场景工作负载
│   │   └── fixtures/         # 测试数据
│   ├── configs/              # 运行与发布配置
│   ├── scripts/              # 一键测试、复现和 openEuler smoke
│   ├── skills/               # 工具技能说明
│   ├── tests/                # 单元与集成测试
│   ├── docs/                 # 设计、部署和 Benchmark 文档
│   └── results/              # CSV、JSON、事件、快照和报告
│
└── AgentMem-vLLM/
    ├── agentmem_rayserve/
    │   ├── app.py            # 统一网关、状态刷新与请求转发
    │   ├── policy.py         # 固定、轮询和 AgentMem 路由策略
    │   └── quality.py        # 质量门控与回退
    ├── deploy/systemd/       # 双引擎和网关服务模板
    ├── agentmem_engines*.json
    ├── benchmark_multimodel_agentmem.py
    ├── benchmark_multimodel_performance.py
    ├── summarize_multimodel_repeats.py
    ├── EXPERIMENTS.md
    └── results/

---

快速开始

1. 获取代码

mkdir AgentMem && cd AgentMem

git clone https://github.com/z17691248297-source/Agent-Memory-Manager.git
git clone https://github.com/SyaOtiLan/AgentMem-vLLM.git

2. 安装 Agent Runtime 与记忆管理组件

cd Agent-Memory-Manager

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -r requirements.txt
python -m pytest

3. 无 GPU 快速验证

Mock 模式不依赖 GPU 或真实模型服务，适合先验证事件、工具、记忆和报告链路：

python -m agentmem benchmark --scenario tool-heavy --backend mock
python -m agentmem benchmark --scenario long-session --backend mock
python -m agentmem benchmark --scenario multi-stage --backend mock
python -m agentmem benchmark --scenario branching --backend mock
python -m agentmem benchmark --scenario prefix-cache --backend mock
python -m agentmem benchmark --scenario ablation --backend mock
python -m agentmem report

一键运行：

bash scripts/run_all.sh

可复现 smoke：

bash scripts/reproduce_all.sh --smoke

4. 启动双 vLLM 模型服务

以下为通用示例，模型路径、GPU 编号、端口、显存比例和最大上下文长度需按实际环境调整：

CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen2.5-1.5B-Instruct \
  --host 0.0.0.0 \
  --port 8101 \
  --enable-prefix-caching \
  --max-model-len 8192

CUDA_VISIBLE_DEVICES=1 vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8102 \
  --enable-prefix-caching \
  --max-model-len 16384

5. 启动 AgentMem 多模型网关

cd ../AgentMem-vLLM

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
pip install "ray[serve]" fastapi httpx openai

cp agentmem_engines.dual_gpu.json agentmem_engines.json
export AGENTMEM_CONFIG="$PWD/agentmem_engines.json"

serve run agentmem_rayserve.app:application

默认网关地址：

http://127.0.0.1:8000/v1

6. 配置 Agent-Memory-Manager 连接网关

编辑 Agent-Memory-Manager/configs/config.yaml：

llm:
  backend: vllm
  model: auto
  base_url: http://127.0.0.1:8000/v1
  api_key: EMPTY
  api_key_env: AGENTMEM_API_KEY
  temperature: 0
  max_tokens: 512
  timeout: 120

memory:
  recent_rounds: 6
  enable_tool_externalization: true
  enable_skill_lazy_loading: true
  enable_history_summary: true
  enable_branch_sharing: true
  enable_stable_prefix: true

tools:
  enabled:
    - log_analyzer
    - file_reader
    - calculator
    - code_analyzer
    - csv_analyzer
    - repo_scanner
  max_selected_tools: 2
  max_output_chars: 20000

benchmark:
  output_dir: results
  repeat: 1

通过单引擎直接测试时，可额外配置对应模型服务的 /metrics 地址；通过多模型网关运行时，引擎状态由网关独立维护。

7. 发送 Agent-aware 请求

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="EMPTY",
)

response = client.chat.completions.create(
    model="auto",
    messages=[
        {
            "role": "user",
            "content": "分析日志并规划后续工具调用流程。",
        }
    ],
    extra_body={
        "agent_meta": {
            "agent_id": "agent-001",
            "session_id": "session-001",
            "task_type": "planning",
            "priority": "normal",
            "routing_mode": "agentmem",
            "quality_gate": True,
        }
    },
)

print(response.choices[0].message.content)

质量敏感的非流式请求还可以设置：

{
  "require_json": true,
  "required_json_keys": ["status", "next_action"],
  "required_substrings": ["evidence"]
}

---

常用命令

Agent Runtime

python -m agentmem run "用一句话解释 KV Cache。"
python -m agentmem chat
python -m agentmem tools

上下文管理 Benchmark

python -m agentmem benchmark --scenario tool-heavy
python -m agentmem benchmark --scenario long-session
python -m agentmem benchmark --scenario multi-stage
python -m agentmem benchmark --scenario branching
python -m agentmem benchmark --scenario prefix-cache
python -m agentmem benchmark --scenario ablation
python -m agentmem benchmark --all
python -m agentmem report

通用参数：

--mode baseline|optimized|both
--backend mock|vllm|openai_compatible
--repeat N
--output results/
--config configs/config.yaml

多模型路由与流式性能 Benchmark

cd AgentMem-vLLM

python benchmark_multimodel_performance.py \
  --base-url http://127.0.0.1:8000/v1 \
  --modes baseline_fixed_large,baseline_round_robin,agentmem \
  --requests 200 \
  --concurrency 4 \
  --gpu-indices 0,1 \
  --output result.json

---

Benchmark 场景

场景	主要验证内容
tool-heavy	工具原始结果外置、工具摘要注入和技能按需加载
long-session	多轮任务中完整历史、摘要记忆和事件溯源式记忆的增长趋势
multi-stage	planning → tool calling → reflection → final answer 多阶段状态管理
branching	公共上下文共享、分支增量和上下文复制成本
prefix-cache	稳定 Prompt 前缀、Prefix Cache、Prefill 和 TTFT
ablation	稳定前缀、技能延迟加载、工具外置、历史压缩等单项贡献
并发 Agent	不同并发数下的任务时延、TTFT 和吞吐量
多模型路由	Fixed 7B、Round Robin 与 AgentMem 的路由准确率、吞吐和流式时延
KV Cache 压力	临时工具结果施压后关键前缀的命中与重访时延
缩减 KV 预算	更低 KV Block 容量下的缓存保留、GPU 显存和响应效率

固定任务位于 benchmarks/tasks/*.jsonl。Evaluator 可基于 expected_tools、answer_keywords、expected_stages、min_metrics 和 max_metrics 输出 success、score 与 failure_reason，避免把“API 调用成功”直接等同于“任务完成正确”。

---

关键指标

上下文与工具结果

• prompt_tokens
• history_tokens
• summary_tokens
• raw_tool_tokens
• injected_tool_tokens
• tool_compression_ratio
• stable_prefix_tokens
• cached_prompt_tokens
• prefix_cache_hit_rate

推理性能

• latency
• ttft
• tpot
• tokens_per_second
• requests_per_s
• peak_gpu_memory_mb
• kv_cache_usage
• waiting_requests

任务与路由

• success
• score
• failure_reason
• routing_accuracy
• format_success_rate
• selected_engine
• fallback_reason

---

代表性实验结果

以下结果来自当前项目测试环境，用于说明系统行为，不应直接外推到不同模型、GPU、并发或工作负载。正式发布性能结论时应使用独占 GPU、固定任务集和任务级评价器，并同步原始结果文件。

上下文管理

测试场景	对照结果	AgentMem 结果	结论
工具密集平均输入词元	13,697	1,569	降低 88.54%
多阶段平均输入词元	10,922	1,192	降低 89.09%
第 50 轮长会话输入词元	3,824	1,530	长会话上下文保持受控
8 分支上下文词元	16,432	3,692	节省 77.53%
前缀缓存平均 TTFT	0.427 s	0.275 s	降低 35.59%

并发执行

并发 Agent 数由 1 增加到 2 时，任务吞吐量由 0.1646 task/s 提升至 0.2139 task/s，提高约 29.95%，同时平均时延和 TTFT 下降。本实验环境下 2～4 个并发 Agent 取得较好的吞吐与响应平衡；并发数达到 8 后，等待和资源竞争明显增加。

KV / Prefix Cache

指标	Stock vLLM	AgentMem-vLLM
压力后关键前缀命中词元	0	3,008
压力后命中率	0%	99.47%
平均重访时延	299.4 ms	98.8 ms

在缩减 KV 预算实验中，KV Block 数由 851 降至 576，AgentMem-vLLM 仍保留 3,008 个关键前缀命中词元，平均时延由 302.7 ms 降至 82.0 ms。

多模型路由

策略	成功率	路由准确率	吞吐量	P95 TTFT
Fixed 7B	100%	50%	2.873 req/s	65.5 ms
Round Robin	100%	50%	5.009 req/s	64.2 ms
AgentMem	100%	100%	3.311 req/s	63.2 ms

相较 Fixed 7B，AgentMem 的吞吐量提高 15.3%，P95 TTFT 降低约 3.5%，并将任务全部路由至预期模型层级。Round Robin 的吞吐量更高，但无法保证任务复杂度与模型能力匹配。

---

输出文件

运行后会生成或更新：

results/
├── tool_heavy_baseline.csv
├── tool_heavy_optimized.csv
├── long_session_*.csv
├── multi_stage_*.csv
├── branching_*.csv
├── prefix_cache_*.csv
├── ablation.csv
├── vllm_benchmark.csv
├── summary.csv
├── report.md
├── event_log/
├── event_memory_snapshots/
└── tool_store/
    ├── raw/
    ├── index/
    └── chunks/

多模型网关 Benchmark 默认输出 JSON，包含逐请求记录和策略汇总：

mode
success_rate
format_success_rate
routing_accuracy
requests_per_s
avg_latency_s
p95_latency_s
avg_ttft_s
p95_ttft_s
avg_tpot_s
p95_tpot_s
peak_gpu_memory_mib

---

openEuler / openKylin

Agent Runtime 可运行于 openEuler 用户态容器，并通过 OpenAI-compatible API 连接远程 GPU 模型节点。

最小兼容性验证：

cd Agent-Memory-Manager

DOCKER_CMD='sudo docker' \
  bash scripts/run_openeuler_smoke.sh

输出位于：

results/openeuler-smoke/

该流程验证容器用户态、Python 环境、CLI、远程模型服务连接和 tool-heavy smoke。它不等同于 openEuler 原生 GPU 推理部署证明。

---

测试与复现

# Agent Runtime、记忆、工具、评价与报告
cd Agent-Memory-Manager
python -m pytest

# 网关路由与质量门控
cd ../AgentMem-vLLM
python -m unittest -v \
  test_agentmem_policy.py \
  test_agentmem_quality.py

发布级复现：

cd Agent-Memory-Manager

export AGENTMEM_LLM_BACKEND=vllm
export AGENTMEM_LLM_BASE_URL=http://127.0.0.1:8000/v1
export AGENTMEM_MODEL=auto

bash scripts/reproduce_all.sh \
  --release \
  --config configs/config.release.yaml \
  --output-dir results/release

---

致谢

本项目基于 vLLM、Ray Serve、FastAPI、OpenAI-compatible API 和 Qwen 系列模型构建。感谢相关开源社区提供高吞吐推理、服务编排和模型能力支持。