by 1612535983
Recoverable and auditable deep-research agent built with LangGraph. It plans research, searches the web, manages evidence and context, resumes interrupted runs, and generates cited reports—also designed as a learning reference for AI Agent enthusiasts.
# Add to your Claude Code skills
git clone https://github.com/1612535983/deepresearchagentGuides for using ai agents skills like deepresearchagent.
See how deepresearchagent compares with popular alternatives.
deepresearchagent is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by 1612535983. Recoverable and auditable deep-research agent built with LangGraph. It plans research, searches the web, manages evidence and context, resumes interrupted runs, and generates cited reports—also designed as a learning reference for AI Agent enthusiasts. It has 59 GitHub stars.
deepresearchagent's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/1612535983/deepresearchagent" and add it to your Claude Code skills directory (see the Installation section above).
deepresearchagent is primarily written in Python. It is open-source under 1612535983 on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh deepresearchagent against similar tools.
No comments yet. Be the first to share your thoughts!
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
一个可运行、可恢复、可审计的深度研究智能体,也是一份面向 AI Agent 爱好者的工程学习参考。
从自然语言问题出发,自动规划研究、搜索并读取网页、整理证据,最终生成带来源的 Markdown 报告。既可以通过 CLI 使用,也可以在 Web 工作台中实时观察研究过程。
快速开始 · 工作流程 · 核心架构 · 学习路线 · 进阶能力 · 示例报告
DeepResearchAgent 是一个基于 LangGraph 构建的深度研究 Agent。
它希望同时回答两个问题:
因此,这个项目既可以作为可运行的研究工具,也可以作为 AI Agent 爱好者的学习参考。你可以直接用它生成研究报告,也可以沿着 CLI、State、Tool、Middleware、Checkpoint、Memory 和 Skill 的顺序阅读代码,理解一次研究任务如何在系统中流动。
| 角色 | 可以从项目中获得什么 |
|---|---|
| 使用者 | 输入一个开放问题,获得带来源的研究回答、执行记录和可选 Markdown 报告 |
| 学习者 | 观察一个 Agent 如何规划、调用工具、管理状态、处理中断、控制上下文并完成收尾 |
| 开发者 | 在模块化结构上替换模型、扩展工具、增加 Middleware,或接入自己的存储与评估服务 |
[!NOTE] 这是一个面向学习与工程实践的项目。代码和测试覆盖了 README 中描述的主要能力,但“有引用”不等于“事实一定正确”,概率评估也不能代替人工核验。
| 内容 | |
|---|---|
| 输入 | 一个非空自然语言问题,例如“LangChain Agent 如何工作?” |
| 输出 | 最终回答、完整 ResearchState、任务 thread_id,以及可选 Markdown 报告 |
| 适合 | 技术调研、概念梳理、方案比较、需要网页证据和引用的开放问题 |
| 暂不保证 | 来源内容一定真实、语义结论一定正确,或任何一次运行都能获得相同结果 |
thread_id 继续执行。项目要求 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 工作流的输入与输出:
| 内容 | |
|---|---|
| 输入 | 研究问题,以及可选的强制 Skill |
| 实时输出 | 计划、搜索、阅读、Reflection、Skill 和 JEV 事件 |
| 最终输出 | Markdown 报告、来源、JEV 质量结果和上下文诊断 |
| 恢复输入 | SQLite 中已有的 thread_id |
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
整个流程可以理解为:
State.final_report。ResearchResult,也可以把报告保存到本地文件。本项目刻意把模型能力与确定性程序逻辑分开:
这样既保留了 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]
| 组件 | 输入 | 输出 | 解决的问题 |
|---|---|---|---|
| CLI / Runner | 问题、参数、thread_id |
ResearchResult、流式事件、报告文件 |
统一启动、恢复和展示任务 |
| Web API / UI | HTTP 请求、SSE 事件 | 任务时间线、报告、来源和诊断页面 | 让非命令行用户操作并观察研究任务 |
| Agent Graph | Messages、State、模型响应 | 下一次模型调用或 Tool 调用 | 组织模型与工具的循环 |
| Research Tool | 查询词、URL、计划步骤、报告 | 搜索记录、正文、计划更新、最终报告 | 让模型能够对外执行动作 |
| Middleware | 模型请求、Tool 结果、State | 状态更新、约束、路由决策 | 集中处理证据、反思、预算和上下文 |
| ResearchState | 每一步产生的结构化更新 | 当前任务的完整状态 | 避免只依赖对话历史记录事实 |
| Checkpointer | Graph State、thread_id |
SQLite 快照 | 让长任务可以跨进程恢复 |
| Memory | 已完成任务和当前问题 | 可跨任务召回的记忆 | 复用过去任务中的有效信息 |
| Skill | SKILL.md、问题、可用 Tool |
受预算限制的过程知识 | 复用“应该怎样研究”的方法 |
| Evaluation | 问题、报告、来源和证据 | 概率、质量分和建议动作 | 观测报告质量并有限控制回跳 |
| Skill Evolution | 运行评估、当前版本、人工修复原因 | 未激活候选、评审记录、可晋级版本 | 让过程知识可实验、可审计、可回滚地改进 |
.
├── 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 入手。可以按照下面的顺序阅读和动手:
| 阶段 | 建议阅读 | 重点问题 | 可以尝试的练习 |
|---|---|---|---|
| 1. 跑通最小链路 | cli.py → agent.py |
用户问题怎样进入模型,又怎样变成结果? | 修改离线 Demo 的输入和输出 |
| 2. 理解状态 | state.py |
为什么 Agent 需要 State,而不只需要聊天记录? | 增加一个研究统计字段 |
| 3. 理解工具 | tools/ |
模型怎样发起搜索?Tool 结果怎样返回模型? | 新增一个简单 Tool |
| 4. 理解横切逻辑 | middlewares/evidence.py、reflection.py |
如何在不污染 Tool 的情况下收集证据和检查缺口? | 为一条规则增加测试 |
| 5. 理解长任务 | checkpointing.py、events.py |
如何保存进度、恢复任务并实时显示过程? | 中断任务后使用 resume |
| 6. 理解上下文工程 | context/、相关 Middleware |
上下文过长时,怎样外化、压缩并安全收尾? | 调低阈值观察治理事件 |
| 7. 理解能力复用 | memory/、skill/ |
“记住什么”和“应该怎样做”有什么区别? | 编写一个自己的 SKILL.md |
| 8. 理解质量评估 | evaluation/ |
概率评估怎样进入系统,又怎样避免失控回跳? | 使用 Shadow 模式收集结果 |
| 9. 理解受控演化 | evaluation/skill.py、skill/evolution.py |
怎样把评估信号变成候选,而不让模型直接改线上 Skill? | 生成、评审并人工晋级一个候选版本 |
| 10. 理解产品边界 | api/、web/ |
内部 State 如何变成稳定 API,流式事件如何进入页面? | 启动工作台并观察一次研究 |
推荐的完整代码阅读顺序:
cli.py
↓
agent.py
↓
state.py
↓
tools/
↓
middlewares/
↓
context/
↓
memory/ → skill/ → evaluation/
这个顺序先回答“输入如何变成输出”,再逐步展开状态、工具、可靠性和高级能力,适合边运行、边阅读、边修改。
| 工程问题 | 本项目的处理方式 | 主要取舍 |
|---|---|---|
| 模型可能描述并未发生的操作 | 程序记录真实 Tool 调用、来源和 Observation | State 更复杂,但执行事实可以审计 |
| 长任务中断后需要重新开始 | SQLite Checkpoint + thread_id 恢复 |
需要管理任务 ID 和持久化文件 |
| 搜索结果不断挤占上下文 | P1 外化、P4 Snapshot 与摘要、P5 强制收尾 | 压缩可能损失细节,因此先保存可校验快照 |
| 搜索失败或重复调用形成死循环 | 总次数、连续失败、重复查询和收尾预算 | 达到边界后可能基于不完整证据生成报告 |
| 模型生成不存在的引用 | 报告 Tool 校验 URL 是否来自已收集来源 | 能校验引用存在,不能自动保证来源内容为真 |
| 质量判断影响正常任务 | 默认 Shadow、有限 Gate、签名幂等和 fail-open | 概率只作为决策信号,不作为事实正确率 |
| 恢复状态和长期知识容易混淆 | Checkpoint 与 Memory 使用两条独立持久化路径 | 组件更多,但职责和生命周期更清楚 |
这些问题也是阅读项目时最值得追问的部分:不仅要知道“使用了什么技术”,还要理解它解决了什么问题,以及付出了什么代价。
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。以下能力默认关闭,便于学习者先理解最小研究链路,再按需启用。
Checkpoint 保存“同一个任务怎样继续”,Memory 保存“后续任务可能再次用到什么”。两者不是同一个概念。
DEEPRESEARCH_MEMORY_USE=default
DEEPRESEARCH_MEMORY_NAMESPACE=default
DEEPRESEARCH_MEMORY_ENABLE_RECALL=true
DEEPRESEARCH_MEMORY_ENABLE_EXTRACT=false
Retriever 使用基础中英文分词、BM25 和记忆强度排序。召回内容只进入当前模型请求的 <memory_context>,不会写入正式对话历史。
Tool 解决“Agent 能执行什么动作”,Skill 解决“Agent 应该怎样完成某类任务”。
DEEPRESEARCH_SKILL_USE=default
DEEPRESEARCH_SKILL_DIRS=skills
DEEPRESEARCH_SKILL_INCLUDE_BUILTIN=true
uv run deepresearch skills validate
uv run de