DeepResearchAgent 教程:Skywork 开源的自进化深度研究智能体框架
「Deep Research(深度研究)」是这两年大模型应用里最出圈的能力形态之一:给它一个开放式问题,它能自己拆解子问题、联网搜索、阅读资料、交叉验证,最后产出一篇带论据的长报告。OpenAI、Google 等厂商都推出了各自的 Deep Research 产品,但它们都是闭源服务。想在自己的环境里搭一套可控、可改、可扩展的深度研究系统,就需要开源框架——Skywork(昆仑万维天工)开源的 DeepResearchAgent 正是为此而生。
DeepResearchAgent 在 GitHub 上的官方定位是一个分层多智能体系统(hierarchical multi-agent system):由顶层规划 Agent 协调多个专职的下层 Agent,完成任务的自动分解与高效执行。它不仅面向深度研究任务,也面向通用任务求解,仓库还附带了 GAIA 基准相关的数据与话题标签。但它真正的差异化卖点,是把自己定义为一套「自进化协议 + 工程化运行时」:不只让 Agent 干活,还让 Agent 在干活的过程中沉淀经验、优化自身,并且全过程可追踪、可回滚。项目采用 MIT 许可证,2025 年 5 月开源,目前约 3.5k Star。
本文按「架构与工作原理 → 环境与安装 → 配置 → 运行一个研究任务 → 注意事项 → 适用人群」的顺序,把这个项目讲清楚。需要提前说明的是:它是一个面向研究者和开发者的框架,不是开箱即用的成品应用,阅读本文前最好具备 Python 与大模型 API 的基本经验。
一、架构与工作原理
DeepResearchAgent 的设计出发点,是作者认为现有不少 Agent 协议(如 A2A、MCP)对跨实体的生命周期/上下文管理、版本追踪、以及演化过程中的安全更新接口规定不足,容易让系统变成「大一统单体 + 脆弱胶水代码」。它的解法是把「演化什么」与「如何演化」解耦成两层协议:
- RSPL(Resource Substrate Protocol Layer,资源基底协议层):把 prompt、agent、tool、environment、memory 这五类要素统一建模为「协议注册资源」,每类资源都有显式的状态、生命周期与版本化接口。换句话说,提示词、工具、记忆都不再是散落在代码里的字符串和全局变量,而是可注册、可替换、可追踪版本的组件。
- SEPL(Self Evolution Protocol Layer,自进化协议层):定义闭环的 operator 接口,负责提出(propose)、评估(assess)、提交(commit)改进,整个演化过程带有可审计的 lineage(血统记录),并且支持回滚(rollback)。改坏了能退回去,这是它区别于「让模型自己瞎改提示词」类玩法的关键。
在这两层协议之上,系统运行时形成一个反复迭代的自进化闭环:
- 行动(Act):Agent 基于 LLM 与可用工具/环境产生行动与输出;
- 观测(Observe):记录结果、执行轨迹、关键中间信息,以及来自环境的反馈信号;
- 优化(Optimize):优化器把反馈转化为可复用的改进——提示词、解法、变量的更新,官方列举的方法包括 Reflection(反思)、GRPO、Reinforce++ 等;
- 记忆(Remember):把会话事件、总结与洞察写入记忆系统,供后续步骤乃至后续会话复用。
落到代码结构上,核心模块都在 src/ 目录下,按职责拆分得很清楚:
- Agents(src/agent/):决定「下一步做什么」的运行逻辑,包括规划、工具调用、领域专用 Agent 等;
- Tools(src/tool/):暴露给 Agent 调用的能力,分为工作流工具与默认工具;
- Environments(src/environment/):可交互的有状态接口,如文件系统、交易回测环境、浏览器/移动端环境等;
- Memory(src/memory/):会话/事件记忆系统,负责总结、洞察与长期状态;
- Optimizers(src/optimizer/):自进化算法实现,把反馈转成可落地的更新;
- Tracing & Versioning(src/tracer/、src/version/):记录执行轨迹、管理迭代产物,便于分析失败与复现实验;
- Model(src/model/):模型管理器与各厂商后端,配合 LiteLLM 风格的多模型接入;
- 配置系统(configs/、src/config/):采用 MMEngine 风格的组合式配置,用 Python 配置文件一致地装配 agent/tool/env/memory/model。
官方总结的设计目标是三个词:可组合(不推翻架构即可替换/扩展任一类组件)、可观测(结构化 trace 与 memory event 让失败分析更透明)、可演化(优化器 + 持久化记忆实现迭代改进,而非一次性推理)。对于深度研究场景,这套架构的实际含义是:顶层 Agent 负责规划研究路径,下层的研究、分析类工具型 Agent 负责具体执行,执行轨迹被完整记录,研究过程中形成的中间结论会进入记忆,提示词与策略还能在多轮运行间持续改进。
二、环境与安装
DeepResearchAgent 是一个 Python 项目。仓库同时提供了 environment.yml(Conda 环境,环境名为 agentworld,锁定 Python 3.11 与 PyTorch 2.5.1 等一整套依赖)和 requirements.txt(pip 依赖清单)。由于依赖较重(包含浏览器自动化、文档解析、数据分析、金融数据等多个方向的库),官方推荐用 Conda 一次性建好隔离环境:
# 克隆仓库(仓库包含 git submodule,建议带上 --recurse-submodules)
git clone --recurse-submodules https://github.com/SkyworkAI/DeepResearchAgent.git
cd DeepResearchAgent
# 方式一:Conda 创建完整环境(推荐,环境名 agentworld,Python 3.11)
conda env create -f environment.yml
conda activate agentworld
# 方式二:已有 Python 3.11 环境时,用 pip 安装依赖
pip install -r requirements.txt
装好后先确认目录结构:configs/ 是组件组合配置,examples/ 是可直接运行的示例入口,workdir/ 是运行产物目录(日志、轨迹、结果都会写到这里)。下一步是配 API Key。
三、配置:API Key 与组合式配置文件
1. 配置模型 API Key
把仓库根目录的 .env.template 复制为 .env,填入至少一个模型提供方的 Key。模板中官方推荐的是 OpenRouter(一个 Key 即可调多家模型),同时预留了 OpenAI、Anthropic、Google Gemini 的配置位:
cp .env.template .env
# .env 文件内容(按需填写,至少配一个)
# OpenRouter(官方推荐)
OPENROUTER_API_KEY=sk-or-你的key
# 可选:OpenRouter 建议填写的来源标识,以及自定义 API Base
OPENROUTER_HTTP_REFERER=
OPENROUTER_X_TITLE=
OPENROUTER_API_BASE=
# OpenAI(可选)
OPENAI_API_KEY=
OPENAI_API_BASE=
# Anthropic(可选)
ANTHROPIC_API_KEY=
ANTHROPIC_API_BASE=
# Google Gemini(可选)
GOOGLE_API_KEY=
2. 理解配置文件:以 tool_calling_agent.py 为例
框架的所有装配都在 configs/ 下的 Python 配置文件里完成,采用 MMEngine 的 read_base 组合方式:一个总配置从子配置里引入 agent、tool、environment、memory 再组装。以官方示例 configs/tool_calling_agent.py 为例,几个关键点值得先看懂:
- 主模型:配置项
model_name = "openrouter/gemini-3-flash-preview",注释里还给出了openrouter/claude-sonnet-4.5备选。模型名采用「提供方/模型」的写法,与 .env 里配的 Key 对应。 - 启用的工具:
tool_names列表默认启用了bash、python_interpreter、todo、skill_generator、ai_capability_debate等;而与深度研究最相关的deep_researcher(深度研究)、deep_analyzer(深度分析)、browser(浏览器)、plotter(绘图)、mdify(文档转 Markdown)在默认配置里是注释掉的,需要用时把对应行取消注释、并把工具名加入列表。 - 工具可以单独配模型:配置里
deep_researcher_tool与deep_analyzer_tool默认使用openrouter/o3这类强推理模型,skill_generator则用主模型。也就是说,「干活的 Agent 用便宜快的模型、深度研究子任务用最强的模型」这种分工是框架原生支持的。 - 记忆系统:默认装配了两套记忆——
general_memory_system(通用记忆,带总结与洞察上限)和optimizer_memory_system(优化器记忆),这正是自进化闭环里「记忆」与「优化」两环的落点。 - 环境:默认启用
file_system文件系统环境,Agent 的读写操作都发生在这个受控环境里,产物落在 workdir 下。
临时改参数不必改文件:运行命令支持 --cfg-options 覆盖任意配置项(下一节会用到)。
四、运行一个研究任务
官方 README 给出的可运行示例是一个 Tool-Calling Agent(思考-行动式工具调用智能体),它能在执行过程中动态实例化、检索、精炼资源并持续改进。先原样跑通它,确认环境与 Key 无误:
# 运行官方示例(使用 configs/tool_calling_agent.py 的默认配置)
python examples/run_tool_calling_agent.py --config configs/tool_calling_agent.py
想换模型、换输出目录、给本次运行打标签,用 --cfg-options 覆盖即可,不用动配置文件:
# 覆盖模型、工作目录与运行标签
python examples/run_tool_calling_agent.py \
--config configs/tool_calling_agent.py \
--cfg-options model_name=openrouter/gpt-4o workdir=workdir/demo tag=demo
要真正让它做深度研究类任务,关键一步是回到 configs/tool_calling_agent.py,把 deep_researcher、deep_analyzer 等工具的引入与 tool_names 中的注释打开(它们默认调用 openrouter/o3,请确保你的 OpenRouter 账户有相应额度,或把工具的 model_name 改成你手头可用的强推理模型)。启用之后,顶层 Agent 在接到一个开放式研究问题时,就可以把「搜集资料、梳理证据、深度分析」这类子任务分发给这些专职工具型 Agent,并结合 bash、Python 解释器、绘图等工具完成数据处理与成果整理;全程的轨迹、日志与结果都会写入 workdir/ 下对应 tag 的目录,配合 tracer 与 memory 的记录,事后可以完整复盘它每一步做了什么、得出了什么中间结论。
第一次运行建议这样安排顺序:先用默认配置跑通示例 → 看懂 workdir 里的日志与轨迹文件 → 再启用 deep_researcher 并换上强模型,拿一个你熟悉领域的问题做对照测试,人工评估它拆题、取证、成文的质量。深度研究任务的 token 消耗通常不低,先小规模验证再放量,能省下不少冤枉钱。
五、注意事项
- 它是框架,不是成品:没有开箱即用的 Web 界面与「输入问题就出报告」的完整产品链路,深度研究工具在默认配置里甚至是关闭的。期望「下载就能当 Deep Research 产品用」的读者会失望;它的价值在于给开发者一套可组合、可演化的底座。
- 依赖重、环境挑:environment.yml 锁定了上百个包(含 PyTorch、浏览器自动化、文档解析、金融数据等),首次安装耗时与磁盘占用都不小,版本冲突时优先用 Conda 方式整体创建,不要逐个手装。
- API 成本:自进化闭环意味着多轮调用、反思与优化都会烧 token,深度研究子工具默认还指定了 o3 级别的强模型。正式跑批量任务前,先用小问题测算单次成本,并给 API 账户设好额度上限。
- 安全边界:默认启用的工具里包含 bash 与 Python 解释器,Agent 能在你的机器上真正执行命令。务必在隔离环境(虚拟机/容器/专用账号)里运行,文件系统环境的工作目录也要圈定范围,不要直接在存有重要数据的机器上裸跑。
- 项目仍在快速演进:仓库 2025 年 5 月才开源,配置写法、默认模型名(示例里甚至出现了预览版模型)都可能随版本变化。遇到问题时以你克隆到的那份代码与配置为准,README 与本文都只能当索引。
- 协议定位偏研究:RSPL/SEPL 这套自进化协议是它的学术与工程主张,相关优化器(GRPO、Reinforce++ 等)更偏实验性质。生产落地前,建议先在自己的任务集上做对照评测,别被「自进化」三个字带着走。
六、适用人群与小结
DeepResearchAgent 更适合这几类人:想自建深度研究系统、不愿被闭源服务锁定的团队与个人开发者;研究多智能体协作与 Agent 自进化方向的算法/工程人员——RSPL/SEPL 的资源版本化与可回滚演化设计,在同类开源项目里确实少见,值得拆开读源码;以及需要在 GAIA 类通用任务基准上做实验、要一套带完整轨迹记录的运行时的研究者。
反过来,如果你只是想「有个工具帮我写调研报告」,市面上的成品 Deep Research 服务会更省事;如果你要的是轻量级 Agent 编排,LangGraph、CrewAI 等框架上手更快。DeepResearchAgent 的位置在更底层、更研究向的一端:它给你的不是答案,而是一台能让 Agent 边干活边进化、且全过程可审计的机器。把预期放对,它会是一个很有启发性的开源项目;下一步建议直接克隆仓库,先跑通 tool_calling_agent 示例,再去读 src/optimizer/ 与两套 memory 的实现,那里是这个项目真正的核心。






