项目深度调研

smolagents Open Deep Research

smolagents Open Deep Research:24 小时复现 OpenAI Deep Research

Aymeric Roucher, Albert Villanova del Moral, Merve Noyan, Thomas Wolf, Clémentine Fourrier (Hugging Face) · Hugging Face · GitHub · 2025-02

代码主页 HF

一句话OpenAI 发布 Deep Research 次日,Hugging Face 用自家 smolagents 框架花 24 小时拼出一个开源版:CodeAgent 管理者 + 文本浏览器搜索子 agent,在 GAIA validation 上拿到 55.15% pass@1(OpenAI 为 67.36%,此前开源框架 SoTA 是 Magentic-One 的约 46%),全部代码只有几百行,是最适合拿来改造的 deep research 起点。

这是什么

2025 年 2 月 2 日 OpenAI 发布 Deep Research,在 GAIA benchmark 上做到 67.36%(validation, pass@1),但没有公开任何 agentic framework 细节。Hugging Face 团队(Aymeric Roucher 等)第二天就启动 24 小时复现冲刺,把结果开源在 smolagents 仓库的 examples/open_deep_research 目录,并配了博客《Open-source DeepResearch – Freeing our search agents》。

这不是一篇论文,而是一个'证明开源可以快速逼近'的工程 demo:整个 agent 由 run.py 一个文件定义(约 200 行),挂在 smolagents 库上(agents.py 核心不到 1000 行)。它在 GAIA validation 上打出 55.15%,当时是开源框架的最好成绩;切换成 JSON 动作格式的同配置 agent 立刻掉到 33%,这是博客最想传达的论点——让 agent 用 Python 代码而不是 JSON blob 表达动作。

smolagents 库本体至今活跃(29051 stars,2026-08-25 仍有 push),但 open_deep_research 这个 example 基本处于'完成即冻结'状态,后续改进(vision browser 等)散落在库的其他位置。

smolagents 官方 benchmark:同一模型套上 CodeAgent(实心柱)对比裸 LLM(斜纹柱)在 GAIA/MATH/SimpleQA 上的成绩。agent 化普遍带来数十分提升,GAIA 上裸模型几乎全军覆没(<10%)而 CodeAgent 版 o1 约 47%、DeepSeek-R1-Distill-32B 约 40%——这是博客'framework 决定下限'论点的主要证据。

机制与做法

两层 agent 架构:CodeAgent 管理者 + JSON 搜索子 agent

顶层是一个 CodeAgent(默认模型 o1,reasoning_effort=high,max_steps=12,planning_interval=4),动作以 Python 代码形式写出并执行,且 additional_authorized_imports=["*"]——允许任意 import,没开沙箱。它自己只拿两个工具:visualizer(视觉问答,处理图片题)和 TextInspectorTool(把 PDF/xls 等文件转成文本读,text_limit=100k 字符)。

网页浏览外包给一个 managed agent:名为 search_agent 的 ToolCallingAgent(注意,是 JSON 工具调用式,不是 CodeAgent),max_steps=20,挂 7 个浏览工具:GoogleSearchTool(serper/SerpApi)、VisitTool、PageUp/PageDown、Finder/FindNext、ArchiveSearchTool(查 Wayback Machine),外加一个 TextInspectorTool。浏览器是 SimpleTextBrowser——纯文本、viewport 5120 字符、靠翻页和 Ctrl-F 式查找操作,完全没有 JS 渲染。

CodeAct 论文(Wang et al. 2024)的对比图,博客引用它说明为什么用代码写动作:左边 JSON/文本式 agent 要一次一个 tool call 地串行查四个国家的手机价格,右边代码式 agent 一个 for 循环 + 复用 Python 内置 min() 一步完成。这正是 open_deep_research 顶层 manager 采用 CodeAgent 的理由。

工具直接搬自 Microsoft Magentic-One

博客明说:text browser 和 text inspector 这两件核心工具取自 Microsoft Research 的 Magentic-One,'几乎没改'。HF 的增量贡献主要是把执行框架从 AutoGen 换成 smolagents 的 code-action 范式,以及 manager/searcher 的两层编排。从 46%(Magentic-One)到 55.15% 的提升,博客归因于 code actions:引用 Wang et al. (CodeAct, arXiv:2402.01030) 的结论——代码动作比 JSON 平均少 30% 步数,且一段代码里能写循环和变量复用,JSON 得拆成 20 个 blob 的事一步就能干完。

GAIA 评测的一个细节:附件被人工预处理过

example 的 README 里有一段'Full reproducibility of results'值得注意:提交 GAIA 时,他们把每个单页 PDF/xls 附件在 macOS 的 Preview/Numbers 里手动打开、截图存成 PNG,评测时文件加载系统若发现同名 PNG 就优先加载 PNG 而非原文件(等于把文件解析问题转成了视觉问题,交给 visualizer)。README 承认这一步是手工做的('could be automatized'),处理后的数据传到了 gated 数据集 smolagents/GAIA-annotated。复现 55.15% 需要这份人工增强过的数据。

关键结果

GAIA validation pass@1:55.15%,对比 OpenAI Deep Research 67.36%、此前开源框架 SoTA Magentic-One 约 46%、无 agent 的裸 GPT-4 不到 7%。
同一套配置把动作格式从代码换成 JSON,成绩从 55.15% 掉到 33%——code actions 是最大单一增益来源(但注意顶层是 CodeAgent、搜索子 agent 本身就是 JSON 式)。
代码动作比 JSON 平均少 30% 步数(引自 CodeAct 论文 arXiv:2402.01030,非本项目实测),LLM 调用数和 token 成本随之下降约 30%。
默认模型是 OpenAI o1(当时要 tier-3 API 权限),max_completion_tokens=8192;'开源'指框架和编排代码,不是模型。
工程量极小:agent 定义约 200 行(run.py),浏览工具约千行(scripts/),smolagents 核心 agents.py 不到 1000 行,均为 Apache-2.0。
这个成绩很快被超越:到 2025-2026 年,GAIA validation 上开源 deep research agent 已普遍报 60-75%(如 Princeton HAL 榜单上 2025-08 用 GPT-5 跑同一套 HF Open Deep Research 也被单独收录);55.15% 的历史意义大于当前竞争力。

实证核查

扎实分数、代码、榜单三者对得上,博客对'工具来自 Magentic-One'、'与 OpenAI 还有 12 分差距'也不遮掩;但'复现'含两处折扣——默认跑在闭源 o1 上,且 GAIA 附件经过人工截图增强,严格复现需要 gated 的 GAIA-annotated 数据集。

博客与 README 声称 GAIA validation 55.15%(README 写 55% pass@1),为当时开源框架最佳,OpenAI Deep Research 为 67%。

GAIA 官方 leaderboard(huggingface.co/spaces/gaia-benchmark/leaderboard)有对应提交,代码与提交配置公开在 examples/open_deep_research(run.py、run_gaia.py);Princeton HAL 后来还独立用该 harness 跑过 GPT-5 版本并列入其 GAIA 榜单(hal.cs.princeton.edu/gaia),说明第三方能跑通这套代码。数字本身可信。

'开源复现 OpenAI Deep Research'。

两处折扣:(1) run.py 默认 model-id 是 'o1' 并对 o1 特判 reasoning_effort=high,55.15% 是用 OpenAI 闭源模型打的,开源的只是编排框架;(2) 核心工具 SimpleTextBrowser/TextInspector 是从 Microsoft Magentic-One 搬来的,博客自己承认'didn't change them much'。作为'开源 agent 框架 + 闭源模型'的组合,声称成立但要读清楚定语。

README 声称结果'fully reproducible'。

同一节 README 写明:GAIA 单页 PDF/xls 附件被人工在 macOS Preview/Numbers 打开截图成 PNG,评测时优先加载 PNG(examples/open_deep_research/README.md 'Full reproducibility of results' 一节);增强后数据在 gated 数据集 smolagents/GAIA-annotated。即 55.15% 依赖一步论文外的人工数据预处理,直接拿原始 GAIA 文件跑大概率到不了这个数。

code actions 是性能提升主因(JSON 版掉到 33%)。

33% 这个消融数字只在博客出现,没有公开的逐题日志;且实际架构里负责上网的 search_agent 恰恰是 ToolCallingAgent(JSON 式,见 run.py),code actions 只用在顶层 manager。方向上与 CodeAct 论文(arXiv:2402.01030)和 smolagents 自己的 benchmark(仓库 examples/smolagents_benchmark)一致,细节无法独立核验。

作为活跃维护的参考实现。

smolagents 库本体活跃(2026-08-25 仍有 push,29051 stars),但 open_deep_research example 自 2025 年初后基本没有实质演进:issue #1687(2025 年提问 Open Deep Research 有无 roadmap)至今 0 回复仍 open,相关 issue #656/#1867/#1875 等长期挂起。拿它当模板没问题,别指望上游继续打磨这个 example。

与我们方向的关系

对做 autoresearch/deep research agent 的同学,这是性价比最高的起点代码:两层 agent(CodeAgent manager + 浏览子 agent)+ 文本浏览器 + 文件转文本工具,总共千余行,依赖清楚,Apache-2.0,可以直接换模型(LiteLLM 接口)、换搜索源、加自己的领域工具。它也是理解'code as action'这一派设计(CodeAct → smolagents → 后来各家 CodeAgent)的最短路径。

两个可借鉴的实证教训:(1) 动作表达格式对 agent 成绩影响巨大(同配置 code 55% vs JSON 33%),做自己的 agent 评测时应把这作为消融维度;(2) 榜单分数常藏着数据预处理细节——它的 GAIA 提交靠人工把附件截图成 PNG 绕过文件解析短板,复核任何 GAIA 分数时都值得问一句'附件是怎么喂进去的'。

阅读笔记

跑 example 需要 SERPAPI_API_KEY 或 SERPER_API_KEY + 模型 API key;manager 的 additional_authorized_imports=['*'] 意味着 agent 代码在本机裸跑,README 明确说 LocalPythonExecutor 不是安全边界,改造时应换 Docker/E2B 沙箱。GAIA-annotated 数据集是 gated(申请即通过)。想看后续演进可关注 smolagents 的 vision_web_browser.py 和 examples/smolagents_benchmark。