# 论文 vs 代码一致性核查：DeepAgent

## 核查对象与方法（含命令）

- 论文：DeepAgent: A General Reasoning Agent with Scalable Toolsets，WWW'26，DOI 10.1145/3774904.3792460，arXiv:2510.21618v3（2026-02-05，ACM 排版版，12 页）
- 代码仓库：https://github.com/RUC-NLPIR/DeepAgent（MIT，1144 stars，2026-04-13 最后推送）

方法：
```bash
git clone --depth 1 https://github.com/RUC-NLPIR/DeepAgent.git "<工作目录>/workdir/p8-deepagent"
curl -sL -m 90 https://arxiv.org/pdf/2510.21618 -o /tmp/p8.pdf   # 1.3MB, 12 页
# pymupdf 抽取全文至 /tmp/p8.txt
python3 -m py_compile src/**/*.py                               # 全部通过
python3 -m venv /tmp/p8venv && pip install <轻量子集依赖>        # 220+ 包安装成功
python3 src/run_deep_agent.py --help                            # 正常
# mock OpenAI 兼容服务（/v1/completions + /v1/chat/completions）+ 本地最小 tokenizer，
# 端到端跑通 GAIA 单例主循环（含工具执行与评测）与 memory folding 路径
# 不下载任何模型权重（whisper base 权重下载触发即中止）
```

## 论文关键声明清单

1. 架构：端到端统一推理流（thinking、tool search、tool call 一体化，非 ReAct 式固定循环），四种动作类型：内部思考、工具搜索 `<tool_search>…</tool_search>`、工具调用 `<tool_call>{"name":..., "arguments":...}</tool_call>`、记忆折叠 `<fold_thought>`（§3.1–3.3）
2. 工具检索：对工具文档建索引，bge-large-en-v1.5 稠密检索，按余弦相似度取 top-k（式 3）
3. 辅助 LLM 三项职责：(a) 过滤/总结过长的检索工具文档；(b) 压缩冗长的工具返回；(c) 把长交互历史压缩为结构化记忆（§3.2）
4. 记忆折叠：episodic/working/tool 三段记忆由辅助 LLM **并行**生成，固定 JSON schema（§3.4、Appendix C）
5. ToolPO 端到端 RL 训练：LLM 工具模拟器 + 工具调用优势归因（tool-call advantage attribution），基于 VeRL，100 步、batch 64、K=8、λ1=λ2=1、max seq 32768、64×H20（§3.5、Appendix B）；训练数据：ToolBench 1k+1k、ALFWorld 500、WebShop 500、WebDancer 200、WebShaperQA 500、DeepMath 0.9k（Appendix A.1）
6. 主模型 QwQ-32B，辅助模型 Qwen2.5-32B-Instruct，VQA 用 Qwen2.5-VL-32B-Instruct；生成参数：max 81920 tokens、温度 0.7、top_p 0.8、top_k 20、重复惩罚 1.05；最大动作数 50（§4.3、Appendix B）
7. Web 搜索用 Google Serper API、网页浏览用 Jina Reader API（§4.3）
8. 九个基准：ToolBench（16k+ API，G3 100 题）、API-Bank（73 API）、TMDB（54 工具）、Spotify（40 工具）、ToolHop（995 题、3,912 可执行工具）、ALFWorld（9 个动作）、WebShop、GAIA、HLE（抽样 500 题）
9. 指标：Pass@1；ToolBench/API-Bank/TMDB/Spotify 报 Success 与 Path，ALFWorld 报 Success/Path，WebShop 报 Success/Score，GAIA/HLE 按 Text/MM/File 分域
10. 报告数字（DeepAgent-32B-RL）：ToolBench 开集 64.0、API-Bank 24.0、TMDB 55.0、Spotify 50.9、ToolHop 40.6；ALFWorld 91.8、WebShop 34.4、GAIA 53.3、HLE 20.2（Table 1–2）

## 证据对照表（声明 | 代码证据（文件:行号） | 判定）

（路径均相对仓库根目录，仓库位于 `workdir/p8-deepagent/`）

| 论文声明 | 代码证据 | 判定 |
|---|---|---|
| 四种动作类型与特殊 token | `src/prompts/prompts_deepagent.py:5-17`（`<tool_search>`/`<tool_call>`/`<fold_thought>` 定义）；拦截循环 `src/run_deep_agent.py:432-561` | 一致 |
| 工具调用 JSON 格式 `{"name":..., "arguments":...}` | `src/prompts/prompts_deepagent.py:26,46`；解析执行 `src/run_deep_agent.py:496-513` | 一致 |
| bge-large-en-v1.5 稠密检索、余弦 top-k | `src/tools/tool_search.py:64-89`（`util.cos_sim`）；`src/run_tool_search_server.py:146`（默认路径 `./LLMs/Retrievers/bge-large-en-v1.5`）；`config/base_config.yaml:48` | 一致 |
| 辅助 LLM 过滤过长工具文档 | `src/run_deep_agent.py:469-478`（>15000 字符调 `run_tool_selection`） | 一致 |
| 辅助 LLM 压缩冗长工具输出 | `src/run_deep_agent.py:519-528`（>5000 字符调 `run_tool_response_analysis`） | 一致 |
| 三段记忆并行生成 | `src/run_deep_agent.py:294-386`（`asyncio.gather` 于 380-384） | 一致 |
| 记忆 JSON schema（Appendix C） | `src/prompts/prompts_deepagent.py:432-525`（task_description/key_events/immediate_goal/tools_used/derived_rules 等字段与论文逐字对应） | 一致 |
| 折叠后以压缩记忆重开新一轮 | `src/run_deep_agent.py:561-592`（`seq['prompt']` 重建） | 一致 |
| 生成参数 0.7/0.8/20/1.05/81920 | `src/run_deep_agent.py:91-95`（默认值） | 一致 |
| 最大动作数 50 | `src/run_deep_agent.py:99`（`--max_action_limit` 默认 50） | 一致 |
| 主/辅助/VQA/检索器四类模型配置 | `config/base_config.yaml:30-49`（model/aux/vqa/tool_retriever 分节） | 一致 |
| Serper 搜索 + Jina 浏览 | `config/base_config.yaml:8-11`；`src/tools/tool_manager.py:221-243,278-325`；`src/tools/google_search.py` | 一致 |
| 工具文档用 OpenAI function 格式 | `src/tools/rapid_api.py`（`api_json_to_openai_json`）；`src/tools/tool_manager.py:73-84` | 一致 |
| ToolBench G3=100 题 | `data/ToolBench/test_instruction/G3_instruction.json`（实测 100 条） | 一致 |
| ToolBench 16k 工具语料未随仓库分发 | `config/base_config.yaml:56` 指向 `./data/ToolBench/retrieval/G1/corpus.tsv`，该文件不存在；README:137 说明需从 ToolBench 官方仓库下载 | 一致（与 README 声明相符） |
| ToolHop 995 题、3,912 工具 | `data/ToolHop/ToolHop.json`（实测 995 题、跨题工具定义总数恰为 3912） | 一致 |
| ALFWorld 9 个动作 | `src/envs/alfworld.py:168+`（goto/take/move/open/clean/heat/cool/use/look，实测 9 个）；`data/ALFWorld/test.json` 134 任务 | 一致 |
| WebShop search/click | `src/envs/webshop.py:205+`（search、click，另含 reset） | 一致 |
| HLE 抽样 500 题 | `data/HLE/all_500.json`（实测 500 条） | 一致 |
| Success/Path 双指标评测 | `src/evaluate/evaluate_toolbench.py:80`（`compute_path_rate`）、135-434（LLM 判定 Success）；`src/evaluate/evaluate_restbench.py`、`evaluate_alfworld.py`、`evaluate_webshop.py`、`evaluate_api_bank.py` | 一致 |
| Pass@1 口径 | `src/evaluate/evaluate_base.py:255`（metrics 含 pass@1 字段） | 基本一致（单次采样评测） |
| GAIA/HLE/ALFWorld/WebShop/API-Bank 评测脚本齐全 | `src/evaluate/evaluate_*.py` 逐一对应 `src/run_deep_agent.py:999-1075` 的分发逻辑 | 一致 |
| ReAct/CodeAct 等基线可复现 | `src/prompts/prompts_react.py`、`prompts_tooleval.py`、`prompts_webthinker.py` 存在；但 `src/run_react.py` 源码缺失（仅残留 `src/__pycache__/run_react.cpython-313.pyc`），浅克隆无法查删除历史 | 部分一致 |
| **ToolPO RL 训练（工具模拟器、工具调用优势归因、VeRL、100 步、K=8 等）** | **仓库内无任何训练脚本**；grep `toolpo|verl|advantage|rollout` 仅命中 README 描述行。唯一相关是推理期 demo 用的 LLM 模拟 API：`src/tools/rapid_api.py:224`（`call_api_simulation`），且在 `src/tools/tool_manager.py:407-409` 中被注释禁用 | 无法验证（训练代码未开源） |
| 报告数字（64.0/91.8/53.3 等） | 需要 vLLM 服务 + QwQ-32B 等权重 + 各 API key + 64×H20 GPU，本核查环境无法重跑 | 无法验证（未见与论文矛盾） |
| 论文 Figure 1 总体结果图 | `figures/overall_results.png` 与论文 Figure 1 同图（图中数字与 PDF 提取文本一致） | 一致 |

## 运行尝试记录

1. **编译检查**：`python3 -m py_compile` 全部 27 个源文件通过（仅 1 条 `\%` 转义 SyntaxWarning，见 `src/utils/math_equivalence.py:104`）。
2. **依赖安装**：仓库无 `setup.py`/`pyproject.toml`，`pip install -e .` 不适用；按 README 的 `pip install -r requirements.txt` 方式在 venv 安装轻量子集（pyyaml/numpy/openai/aiohttp/transformers/sentence-transformers/fastapi 等，共 220+ 包）成功；未装 vllm（体积过大且仅推理服务需要）。
3. **入口自检**：`python src/run_deep_agent.py --help` 正常打印全部参数（与 README 参数表一致）。
4. **提示词模块**：独立 import 成功；`<tool_search>`/`<tool_call>`/`<fold_thought>` token 与 Appendix C 记忆 schema 字段校验通过。
5. **ToolHop 真实工具执行**：`ToolHopCaller` 加载数据集内 Python 函数并调用成功（`geo_relationship_finder` 返回参数校验错误信息，证明执行链路真实生效）。
6. **API-Bank 真实工具执行**：`APIBankExecutor` 初始化成功，`Calculator` 工具执行 `(1+2)*3` 返回正确结果。
7. **端到端主循环（mock LLM，GAIA 单例）**：搭本地 mock OpenAI 服务（/v1/completions + /v1/chat/completions）+ 最小本地 tokenizer，跑通：模型输出 `<tool_call>` → 系统拦截并真实执行 `execute_python_code`（返回 `Execution result: 1024`）→ `<tool_call_result>` 回填 → 生成 `\boxed{1024}` → LLM-judge 评测 `llm_equal=1.0`，`interactions` 与 `action_count` 记录完整。
8. **记忆折叠路径（mock LLM）**：模型输出 `<fold_thought>` → 触发 `run_thought_folding` → 三段记忆并行调用辅助模型 → 折叠记忆回填并重建 prompt → 新一轮推理生成最终答案，`interactions` 中记录 `thought_folding`（episodic/working/tool 三字段）。
9. **未做/受阻项**：未下载任何模型权重（任务约束）；GAIA FileProcessor 初始化会触发 whisper 下载 139MB `base.pt`（`src/tools/file_process.py:14,68`），已通过移除 `gaia_file_dir` 配置规避；工具检索服务需 bge-large-en-v1.5 权重、ToolBench 语料需另行下载，故未运行 `run_tool_search_server.py`；真实模型推理、真实评测数字复现未做（需 GPU/API key）。

## 官方性确认

- GitHub 仓库描述即官方徽标：**`[WWW'26 Oral🔥] DeepAgent: A General Reasoning Agent with Scalable Toolsets`**（经 GitHub API 核实，属 RUC-NLPIR 组织）。
- README 最新动态（README.md:24）："**[Jan 14, 2026]**: 🎉 DeepAgent has been accepted by **[WWW 2026](https://www2026.thewebconf.org/index.html)**!"；README.md:281 处标注 "(WWW 2026)"。
- arXiv v3 为 ACM 官方排版版，页脚含 DOI `10.1145/3774904.3792460`、ISBN `979-8-4007-2307-0/2026/04`（/tmp/p8.txt:66-69），与 ACM Reference Format（:139-145）一致；ACM DL 页面因 Cloudflare 无法直接抓取，但 DOI 由论文官方页脚确证。
- 论文所列数据集与训练后模型均已开源上线：`huggingface.co/datasets/lixiaoxi45/DeepAgent-Datasets` 与 `lixiaoxi45/DeepAgent-QwQ-32B`（经 HF API 核实存在，最后更新 2026-02-05，与 arXiv v3 同日）。
- 作者单位：论文列 RUC（Xiaoxi Li、Guanting Dong、Jiajie Jin、Yutao Zhu、Ji-Rong Wen、Zhicheng Dou 等）+ **Xiaohongshu Inc.**（Wenxiang Jiao、Jiarui Jin、Hao Wang、Yuan Lu）+ Tsinghua（Yinuo Wang）；README.md:18 亦标注 "Powered by RUC x Xiaohongshu Inc."。⚠️ 注意：任务描述中"字节跳动 Seed 与 RUC 合作"与论文/仓库不符，实际合作方为**小红书（Xiaohongshu Inc.）**，未见任何 ByteDance Seed 署名。
- 作者邮箱 xiaoxi_li@ruc.edu.cn（README.md:335）与论文首页一致。

## 结论：一致（推理框架与评测代码部分高度一致；训练代码未开源，属部分一致中的已知缺口）

**核心推理/评测系统与论文高度一致**：四种动作 token、工具检索、辅助 LLM 三项职责、三段并行记忆折叠、JSON 记忆 schema、生成超参（0.7/0.8/20/1.05/81920/50 动作）、九个基准数据与评测脚本（Success/Path、Pass@1 口径）均能在代码中找到逐条对应证据（详见证据表），且主循环与记忆折叠两条关键路径经 mock LLM 端到端跑通，ToolHop/API-Bank 工具真实执行成功。论文 Figure 1 与仓库 `figures/overall_results.png` 同图。

**唯一重大缺口**：论文核心贡献之一的 **ToolPO 训练（工具模拟器 + 工具调用优势归因 + VeRL）完全未开源**，仓库仅有推理/部署代码，训练部分（含 Appendix A.1 训练数据配方、100 步、K=8 等配置）无法验证；另 `run_react.py` 基线运行脚本源码缺失（仅残留 pyc）。因此若以"复现全部论文结果（含训练）"为标准，判定为**部分一致（训练不可复现）**；以"复现推理评测结果"为标准，判定为一致。

## 局限

1. 浅克隆（--depth 1）无法查阅完整 git 历史，`run_react.py` 是否曾被删除无法确认；pyc 残留表明其曾存在。
2. 未运行真实模型推理：需 vLLM 服务、QwQ-32B 等权重（任务禁止下载权重）、RapidAPI/Serper/Jina/TMDB/Spotify 等 API key 与 GPU；论文报告数字（64.0/53.3 等）无法本机复验，仅能确认"代码未发现与之矛盾之处"。
3. ToolBench 16k 工具语料与 bge 检索模型权重未随仓库分发（README 已声明），检索服务与开集场景未实测。
4. ACM DL 页面被 Cloudflare 拦截，"Oral"状态以仓库官方徽标 + arXiv 官版页脚为准；DOI 未能在 ACM 站内二次确认。
5. mock 测试中 aux 模型输出由脚本固定，未验证真实模型对提示词的响应质量。