AI工程师手册实战：从零构建 Deep Research Agent，自动生成研究报告的完整教程

AI工程师手册实战：从零构建 Deep Research Agent，自动生成研究报告的完整教程

【免费下载链接】ai-angineers-handbook项目地址: https://gitcode.com/gh_mirrors/ai/ai-angineers-handbook

如果你正在寻找一份AI工程师手册级别的实战教程，想搞懂 AI Agent 是如何工作的，那么本文非常适合你。我们将基于开源项目ai-angineers-handbook中的 Deep Research Agent 子项目，一步步拆解它是如何自动生成研究报告的——从用户输入一个主题开始，经过规划、搜索、反思、总结四个阶段，最终产出一份完整的 Markdown 报告，全程无需任何 LLM 编排框架，代码简洁到新手也能看懂。

上图展示了 Deep Research Agent 从"用户提问"到"交付报告"的端到端架构，来源：deep_research_agent/README.md

Deep Research Agent 是什么？它能自动做什么？

Deep Research Agent 是一个"深度研究型" AI Agent。与传统聊天机器人不同，它不只靠模型记忆回答问题，而是真正具备自主搜索网页、反复反思、迭代补全信息的能力，就像一位认真负责的研究助理：

• 🧠自主规划：先为你的问题设计报告大纲
• 🔍主动搜索：针对每个章节生成搜索词并调用网页搜索
• 🤔反思迭代：检查已有内容是否遗漏关键信息，补充搜索
• 📝自动成稿：把分散的资料整理成结构化研究报告

项目完整源码位于 deep_research_agent/src，全部核心逻辑只有 6 个文件，非常适合作为 AI Agent 入门教材。

Deep Research Agent 工作流程：5 步自动生成研究报告

整个系统采用经典的"规划—执行—总结"流水线，你只需要运行一条命令，剩下的交给 Agent：

1. 输入主题：用户提供想要研究的话题（Query）
2. 生成大纲：LLM 根据主题规划报告结构，输出若干段落的标题与内容要点
3. 逐段深研：每个段落独立进入研究流程，获取充足素材
4. 汇总成稿：所有段落的研究结果汇总，由 LLM 组装成最终报告
5. 输出报告：以 Markdown 文件形式交付给用户

这套顶层调度逻辑写在 topology.py 中，主流程清晰易懂，是理解 AI Agent 工作流的绝佳范例。

深入研究环节：Agent 反思机制如何提升报告质量

Deep Research Agent 最精彩的部分在于"单段落研究"环节，它体现了AI Agent 反思机制的核心思想：

针对每一个段落，Agent 会执行以下循环：

• ① LLM 基于段落要点设计最优搜索词，并说明推理过程
• ② 调用 Tavily 执行网页搜索，获取前几名相关结果
• ③ 把搜索结果交给 LLM 生成段落初稿
• ④ 进入反思步骤：LLM 审视初稿，判断是否遗漏关键角度，生成补充搜索词
• ⑤ 将补充结果合并进段落内容，重复反思若干轮（默认 2 轮），直到信息足够完整

这种"搜索 → 总结 → 反思 → 再搜索"的闭环，正是深度研究 Agent 与传统问答的关键区别，相关代码可参考 agents.py 中的ReflectionAgent与ReflectionSummaryAgent。

AI 工程师手册项目结构一览

本项目是 "Building Agents from Scratch"（从零构建 AI Agent）系列的一部分，整个手册循序渐进地覆盖了构建 Agent 的核心能力：

记忆（Memory）与评估（Evaluation）模块也在规划中。想从宏观上理解 AI Agent 的组成（核心、规划、记忆、工具），可以查看项目总览图 agent.png。

快速上手：一键安装与运行 Deep Research Agent

项目使用 uv 管理 Python 依赖，安装与运行都非常简单：

第 1 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/ai/ai-angineers-handbook

第 2 步：复制环境变量文件

进入building_agents_from_scratch/deep_research_agent目录，将env.example复制为.env：

cp env.example .env

第 3 步：运行深度研究

uv run --env-file .env src/topology.py --topic "人类有哪些有趣的特性"

大约 5 分钟后，一份完整的 Markdown 研究报告就会生成到reports目录下。

配置 API 密钥：SambaNova 与 Tavily 的完整配置方法

运行前需要准备两个免费的 API 密钥，并填入.env文件：

• SAMBANOVA_API_KEY：用于调用推理模型（DeepSeek-R1 系列）
• TAVILY_API_KEY：用于网页搜索

默认配置（见 env.example）已经非常贴心：

• LLM_REASONING：DeepSeek-R1-Distill-Llama-70B，负责大纲规划与最终成稿（推理能力强）
• LLM_REGULAR：Meta-Llama-3.3-70B-Instruct，负责搜索词生成与段落总结（速度快、成本低）

这种"强推理模型做规划、轻量模型做执行"的分工，是很多生产级 AI Agent 的通用设计，很值得学习借鉴。

查看生成结果：研究报告输出到哪里？

运行完成后，报告会以时间戳命名自动保存，例如：

reports/report_2026-08-19_08-00-00.md

报告内容包括：

• 📄 根据各段落标题自动生成的总标题
• 📑 结构化的章节内容
• 🧾 自动补充的结论（Conclusion）段落

如果只想跟着代码逐步理解实现细节，项目还提供了 Jupyter Notebook 交互式教程，位于 notebooks，逐行运行即可观察 Agent 的每一步行为。

写在最后：下一步怎么学？

通过本文的拆解，你已经看到了一个真实可运行的Deep Research Agent是如何把"规划、搜索、反思、总结"串成完整工作流的。这也是AI工程师手册系列的核心价值——不依赖黑盒框架，用最简单的方式讲清楚 AI Agent 的本质。

接下来你可以尝试：

• ✏️ 修改 topology.py 中的反思轮数NUM_REFLECTIONS，观察报告质量变化
• 🔧 调整搜索结果的截断长度，控制信息量
• 📖 继续学习同系列的工具使用（Tool Use）与反思（Reflection）模块，完善你的 Agent 知识体系

从零构建一个属于自己的 AI Agent，并没有想象中那么难，现在就去动手试试吧！

【免费下载链接】ai-angineers-handbook项目地址: https://gitcode.com/gh_mirrors/ai/ai-angineers-handbook