🔬 DeepResearchAgent

一个可运行、可恢复、可审计的深度研究智能体，也是一份面向 AI Agent 爱好者的工程学习参考。

从自然语言问题出发，自动规划研究、搜索并读取网页、整理证据，最终生成带来源的 Markdown 报告。既可以通过 CLI 使用，也可以在 Web 工作台中实时观察研究过程。

快速开始 · 工作流程 · 核心架构 · 学习路线 · 进阶能力 · 示例报告

DeepResearchAgent 是一个基于 LangGraph 构建的深度研究 Agent。

它希望同时回答两个问题：

1. 一个深度研究 Agent 怎样可靠地完成长任务？
2. 学习者怎样从最小 Agent 出发，逐步理解并复现一套完整的工程系统？

因此，这个项目既可以作为可运行的研究工具，也可以作为 AI Agent 爱好者的学习参考。你可以直接用它生成研究报告，也可以沿着 CLI、State、Tool、Middleware、Checkpoint、Memory 和 Skill 的顺序阅读代码，理解一次研究任务如何在系统中流动。

• 研究闭环：计划、搜索、正文读取、证据聚合、缺口检查、引用校验和报告生成。
• 可恢复：使用 SQLite Checkpoint 保存任务，进程中断后可以通过 thread_id 继续执行。
• 可审计：程序记录真实 Tool 调用、来源、证据和模型可见上下文，不依赖模型描述自己做过什么。
• 有边界：通过 Token 治理、搜索与阅读预算、有限 Reflection 和强制收尾避免无限循环。
• 可扩展：模型、Tool、Middleware、Memory、Skill 和评估层相互分离。
• 受控演化：Skill 可以基于跨任务评估生成候选，经规则与概率评审后由人工晋级，并保留旧版本回滚。
• 适合学习：模块职责明确，提供离线 Demo、自动化测试、名词解释和分阶段阅读路线。

项目要求 Python 3.12+，推荐使用 uv 管理环境。

git clone https://github.com/1612535983/deepresearchagent.git
cd deepresearchagent
uv sync --extra dev --extra web

先运行完全离线的 Demo，不需要 API Key：

uv run deepresearch demo

预期输出：

最小链路已跑通：命令行输入已经进入 LangChain Agent Graph，模型响应也已被封装为 ResearchResult。

运行测试：

uv run pytest -q

当前项目包含 332 个自动化测试，覆盖 Agent、Tool、Middleware、Checkpoint、上下文治理、Memory、Skill、报告评估、受控 Skill 演化和 Web API。

复制环境变量模板：

cp .env.example .env

项目通过 ChatOpenAI 接入兼容 OpenAI Chat Completions 协议的模型服务。.env.example 默认以 DeepSeek 为例：

DEEPRESEARCH_API_KEY=sk-your-api-key
DEEPRESEARCH_MODEL=deepseek-chat
DEEPRESEARCH_BASE_URL=https://api.deepseek.com

运行一次真实研究：

uv run deepresearch run "请解释 ReAct Agent 的基本工作方式"

实时查看计划、工具调用、证据和报告进度，并把结果保存为 Markdown：

uv run deepresearch run "研究 LangChain Agent" \
  --stream \
  --show-trace \
  --output reports/langchain-agent.md

可以先查看示例报告：LangGraph Agent 核心工作机制。该报告展示了完整研究正文、参考来源以及 Jev Shadow 模式生成的质量评估附录；真实内容会随研究问题、模型和搜索结果变化。

先安装并构建前端：

cd web
npm ci
npm run build
cd ..

然后从项目根目录启动本地服务：

uv run deepresearch serve

打开 http://127.0.0.1:8000 即可输入问题。API 文档位于 http://127.0.0.1:8000/docs。服务默认只监听本机；当前版本没有用户登录与权限隔离，不应直接暴露到公网。

前端开发时可以在另一个终端运行 cd web && npm run dev，浏览器访问 http://127.0.0.1:5173；Vite 会把 /api 请求代理到 8000 端口。

Web 工作流的输入与输出：

flowchart LR
    A[自然语言问题] --> B[创建研究计划]
    B --> C[网页搜索]
    C --> D[读取关键正文]
    D --> E[沉淀来源与证据]
    E --> F{检查研究缺口}
    F -->|仍需研究| C
    F -->|证据足够| G[生成并校验报告]
    G --> H[ResearchResult / Markdown]

    I[(SQLite Checkpoint)] -.保存与恢复.-> B
    J[(长期记忆)] -.跨任务召回.-> E
    K[Context Governance] -.外化 / 压缩 / 收尾.-> F
    L[(Skill Registry)] -.注入研究方法.-> B
    M[Report Evaluation] -.质量观测 / 有界回跳.-> G
    N[Skill Evolution] -.评估 / 候选 / 人工晋级.-> L

整个流程可以理解为：

1. CLI 接收问题和运行参数。
2. Agent 创建结构化研究计划。
3. 模型选择搜索、正文读取、计划更新或报告工具。
4. Middleware 把真实工具结果整理为来源和证据，并同步到 State。
5. 程序检查计划、证据、上下文和工具预算，决定继续研究还是开始收尾。
6. 报告工具校验引用，把 Markdown 写入 State.final_report。
7. Runner 返回 ResearchResult，也可以把报告保存到本地文件。

本项目刻意把模型能力与确定性程序逻辑分开：

• 模型负责：理解问题、制定计划、选择工具、判断下一步和撰写报告。
• 程序负责：记录真实执行结果、更新状态、校验引用、保存 Checkpoint、控制预算和处理失败。

这样既保留了 Agent 的灵活性，也让关键行为可以测试、恢复和审计。

flowchart TB
    ENTRY[CLI / Web / Python API] --> RUNNER[Runner / Stream]
    RUNNER --> GRAPH[LangGraph Agent]
    GRAPH <--> MODEL[Chat Model]
    GRAPH <--> TOOLS[Research Tools]
    GRAPH <--> MW[Middleware Chain]

    MW <--> STATE[ResearchState]
    STATE <--> CHECKPOINT[(SQLite Checkpoint)]
    MW <--> MEMORY[(Long-term Memory)]
    MW <--> SKILL[(Versioned Skills)]
    MW --> CONTEXT[Context Governance]
    MW --> EVAL[Report Evaluation]

.
├── src/deepresearch/
│   ├── cli.py               # 命令行入口
│   ├── agent.py             # 组装并运行 Agent Graph
│   ├── state.py             # 研究状态与 reducer
│   ├── checkpointing.py     # SQLite Checkpoint 与任务恢复
│   ├── events.py            # 流式事件
│   ├── api/                 # FastAPI、公开 DTO、异步任务与 SSE
│   ├── tools/               # 搜索、正文读取、计划和报告工具
│   ├── middlewares/         # 证据、反思、治理、记忆等横切逻辑
│   ├── context/             # Token、外化、快照、摘要和收尾策略
│   ├── memory/              # 长期记忆存储、检索与 Worker
│   ├── skill/               # Skill 解析、版本、选择、注入、指标和受控演化
│   └── evaluation/          # 报告/Skill 概率评估与 Provider 适配
├── web/                     # React + TypeScript 研究工作台
├── tests/                   # 自动化测试
├── examples/                # 输出样例
├── reports/                 # 运行报告与 Jev Shadow 示例
├── docs/assets/             # README 素材
├── .github/workflows/       # GitHub Actions
└── pyproject.toml           # 依赖、脚本入口与打包配置

如果你刚开始学习 Agent，不建议直接从最复杂的 Middleware 入手。可以按照下面的顺序阅读和动手：

推荐的完整代码阅读顺序：

cli.py
  ↓
agent.py
  ↓
state.py
  ↓
tools/
  ↓
middlewares/
  ↓
context/
  ↓
memory/ → skill/ → evaluation/

这个顺序先回答“输入如何变成输出”，再逐步展开状态、工具、可靠性和高级能力，适合边运行、边阅读、边修改。

这些问题也是阅读项目时最值得追问的部分：不仅要知道“使用了什么技术”，还要理解它解决了什么问题，以及付出了什么代价。

uv run deepresearch run "研究 LangChain Agent" --stream --show-trace

--stream 展示由真实 Graph 更新转换出的 ResearchEvent；--show-trace 读取 State 中的搜索、正文、来源、证据、上下文和评估统计，不会额外调用模型。

uv run deepresearch run "研究 LangChain Agent" \
  --output reports/langchain-agent.md

程序不会覆盖已经存在的文件。报告正文来自 State.final_report；如果已完成质量评估，还会追加程序确定性渲染的评估附录。

uv run deepresearch run "研究 LangGraph" \
  --thread-id research-001 \
  --stream

uv run deepresearch resume research-001 --stream
uv run deepresearch inspect research-001

• 新任务应该使用新的 thread_id。
• resume 从最近的 Graph 快照继续，不会重新创建初始 State。
• inspect 只读取最新持久化摘要，不会调用模型。
• 不要让两个进程同时执行同一个 thread_id。

以下能力默认关闭，便于学习者先理解最小研究链路，再按需启用。

DEEPRESEARCH_MEMORY_USE=default
DEEPRESEARCH_MEMORY_NAMESPACE=default
DEEPRESEARCH_MEMORY_ENABLE_RECALL=true
DEEPRESEARCH_MEMORY_ENABLE_EXTRACT=false

DEEPRESEARCH_SKILL_USE=default
DEEPRESEARCH_SKILL_DIRS=skills
DEEPRESEARCH_SKILL_INCLUDE_BUILTIN=true

uv run deepresearch skills validate
uv run deepresearch skills list
uv run deepresearch skills show source-verification
uv run deepresearch run "核验这项声明并给出来源" --skill source-verification

DEEPRESEARCH_SKILL_ENABLE_EVALUATION=true
DEEPRESEARCH_EVALUATION_USE=jev
DEEPRESEARCH_JEV_API_KEY=your-typesafe-api-key

# 1. 研究模型根据人工原因和历史运行评估生成未激活候选
uv run deepresearch skills evolve source-verification \
  --reason "历史评估显示关键结论缺少逐项引用"

# 2. 确定性规则 + Jev 对 baseline/candidate 做有界评审
uv run deepresearch skills review source-verification__candidate_id

# 3. 只有评审通过后，人工命令才能激活候选
uv run deepresearch skills promote source-verification__candidate_id

uv run deepresearch skills evaluations source-verification
uv run deepresearch skills experiments source-verification
uv run deepresearch skills history source-verification

DEEPRESEARCH_EVALUATION_USE=jev
DEEPRESEARCH_EVALUATION_MODE=shadow
DEEPRESEARCH_JEV_API_KEY=your-typesafe-api-key

• Agent：让模型能够根据当前状态选择下一步动作的执行系统。
• Tool：模型可以调用的程序能力，例如搜索、读取网页和提交报告。
• State：Graph 节点共享的结构化任务状态，例如计划、来源、证据和最终报告。
• Middleware：插入模型或 Tool 生命周期的横切逻辑，例如收集证据、检查缺口和控制预算。
• Checkpoint：某一执行时刻的 State 和 Graph 位置，用于恢复同一个任务。
• Memory：跨任务保存和召回的信息，不负责恢复 Graph 的执行位置。
• Skill：告诉 Agent“应该怎样完成某类任务”的过程知识，不等同于可执行 Tool。
• Reflection：Agent 准备结束时进行的缺口检查；本项目对回跳次数设置了上限。
• Token / 上下文窗口：模型处理文本的计量单位，以及一次请求能够容纳的 Token 上限。
• Shadow / Gate：Shadow 只观测评估结果；Gate 可以根据阈值有限地改变后续路由。
• SSE：服务器向浏览器单向持续推送事件的 HTTP 机制，本项目用它实时展示研究进度。
• DTO：专门用于 API 输入输出的数据结构；它过滤内部消息和大段证据，避免直接暴露完整 State。

当前项目是一个 单 Agent、本地单用户的深度研究系统。CLI、Python API 和 Web 工作台共用同一个 Runner、事件与 Checkpoint 边界。

目前尚未实现：

• MCP 与独立 Sandbox；
• 多 Agent 并行研究；
• 使用人工标注数据完成概率校准；
• 固定任务集上的 Skill baseline/candidate A/B 重放与 Canary 发布；
• 对事实正确率、报告质量和成本进行系统 Benchmark。

后续计划优先补充评估数据集，计算 Brier Score、ECE 和质量/成本指标，再考虑 MCP、Sandbox、多用户鉴权和多 Agent。

uv run pytest -q

每次 push 或 pull request 都会通过 GitHub Actions 在 Python 3.12 上运行测试。

欢迎通过 Issue 提交 Bug、文档建议或可复现的改进想法。提交代码前请保证：

1. 不包含 API Key、.env、本地数据库、报告或运行时记忆；
2. 一个提交只处理一个可以解释的问题；
3. 新行为包含对应测试，现有测试保持通过；
4. README、类型注解和错误信息与代码行为一致。

项目建立在 LangChain 与 LangGraph 的公开能力之上；设计过程中也参考了 DeerFlow、Open Deep Research、Poirot 等开源项目的架构思路。

本项目没有逐模块移植上述项目，也不与它们存在官方关系。具体参考内容和设计取舍见 ACKNOWLEDGMENTS.md。

本项目采用 MIT License。你可以学习、使用和修改代码；分发副本或重要代码片段时，请保留许可证和版权声明。