深度搜索代理

一个无框架的深度搜索AI代理实现，能够通过多轮搜索和反思生成高质量的研究报告。

特性

• 无框架设计: 从零实现，不依赖LangChain等重型框架
• 多LLM支持: 支持DeepSeek、OpenAI等主流大语言模型
• 智能搜索: 集成Tavily搜索引擎，提供高质量网络搜索
• 反思机制: 多轮反思优化，确保研究深度和完整性
• 状态管理: 完整的研究过程状态跟踪和恢复
• Web界面: Streamlit友好界面，易于使用
• Markdown输出: 美观的Markdown格式研究报告

工作原理

Deep Search Agent采用分阶段的研究方法：

graph TD
    A[用户查询] --> B[生成报告结构]
    B --> C[遍历每个段落]
    C --> D[初始搜索]
    D --> E[生成初始总结]
    E --> F[反思循环]
    F --> G[反思搜索]
    G --> H[更新总结]
    H --> I{达到反思次数?}
    I -->|否| F
    I -->|是| J{所有段落完成?}
    J -->|否| C
    J -->|是| K[格式化最终报告]
    K --> L[输出报告]

核心流程

1. 结构生成: 根据查询生成报告大纲和段落结构
2. 初始研究: 为每个段落生成搜索查询并获取相关信息
3. 初始总结: 基于搜索结果生成段落初稿
4. 反思优化: 多轮反思，发现遗漏并补充搜索
5. 最终整合: 将所有段落整合为完整的Markdown报告

快速开始

1. 环境准备

确保您的系统安装了Python 3.9或更高版本：

python --version

2. 克隆项目

git clone <your-repo-url>
cd Demo\ DeepSearch\ Agent

3. 安装依赖

# 激活虚拟环境（推荐）
conda activate pytorch_python11  # 或者使用其他虚拟环境

# 安装依赖
pip install -r requirements.txt

4. 配置API密钥

项目根目录下已有config.py配置文件，请直接编辑此文件设置您的API密钥：

# Deep Search Agent 配置文件
# 请在这里填入您的API密钥

# DeepSeek API Key
DEEPSEEK_API_KEY = "your_deepseek_api_key_here"

# OpenAI API Key (可选)
OPENAI_API_KEY = "your_openai_api_key_here"

# Tavily搜索API Key
TAVILY_API_KEY = "your_tavily_api_key_here"

# 配置参数
DEFAULT_LLM_PROVIDER = "deepseek"
DEEPSEEK_MODEL = "deepseek-chat"
OPENAI_MODEL = "gpt-4o-mini"

MAX_REFLECTIONS = 2
SEARCH_RESULTS_PER_QUERY = 3
SEARCH_CONTENT_MAX_LENGTH = 20000
OUTPUT_DIR = "reports"
SAVE_INTERMEDIATE_STATES = True

5. 开始使用

现在您可以开始使用Deep Search Agent了！

使用方法

方式一：运行示例脚本

基本使用示例：

python examples/basic_usage.py

这个示例展示了最简单的使用方式，执行一个预设的研究查询并显示结果。

高级使用示例：

python examples/advanced_usage.py

这个示例展示了更复杂的使用场景，包括：

• 自定义配置参数
• 执行多个研究任务
• 状态管理和恢复
• 不同模型的使用

方式二：Web界面

启动Streamlit Web界面：

streamlit run examples/streamlit_app.py

Web界面无需配置文件，直接在界面中输入API密钥即可使用。

方式三：编程方式

from src import DeepSearchAgent, load_config

# 加载配置
config = load_config()

# 创建Agent
agent = DeepSearchAgent(config)

# 执行研究
query = "2025年人工智能发展趋势"
final_report = agent.research(query, save_report=True)

print(final_report)

方式四：自定义配置（编程方式）

如果需要在代码中动态设置配置，可以使用以下方式：

from src import DeepSearchAgent, Config

# 自定义配置
config = Config(
    default_llm_provider="deepseek",
    deepseek_model="deepseek-chat",
    max_reflections=3,           # 增加反思次数
    max_search_results=5,        # 增加搜索结果数
    output_dir="my_reports"      # 自定义输出目录
)

# 设置API密钥
config.deepseek_api_key = "your_api_key"
config.tavily_api_key = "your_tavily_key"

agent = DeepSearchAgent(config)

项目结构

Demo DeepSearch Agent/
├── src/                          # 核心代码
│   ├── llms/                     # LLM调用模块
│   │   ├── base.py              # LLM基类
│   │   ├── deepseek.py          # DeepSeek实现
│   │   └── openai_llm.py        # OpenAI实现
│   ├── nodes/                    # 处理节点
│   │   ├── base_node.py         # 节点基类
│   │   ├── report_structure_node.py  # 结构生成
│   │   ├── search_node.py       # 搜索节点
│   │   ├── summary_node.py      # 总结节点
│   │   └── formatting_node.py   # 格式化节点
│   ├── prompts/                  # 提示词模块
│   │   └── prompts.py           # 所有提示词定义
│   ├── state/                    # 状态管理
│   │   └── state.py             # 状态数据结构
│   ├── tools/                    # 工具调用
│   │   └── search.py            # 搜索工具
│   ├── utils/                    # 工具函数
│   │   ├── config.py            # 配置管理
│   │   └── text_processing.py   # 文本处理
│   └── agent.py                 # 主Agent类
├── examples/                     # 使用示例
│   ├── basic_usage.py           # 基本使用示例
│   ├── advanced_usage.py        # 高级使用示例
│   └── streamlit_app.py         # Web界面
├── reports/                      # 输出报告目录
├── requirements.txt              # 依赖列表
├── config.py                    # 配置文件
└── README.md                    # 项目文档

代码结构

graph TB
    subgraph "用户层"
        A[用户查询]
        B[Web界面]
        C[命令行接口]
    end
    
    subgraph "主控制层"
        D[DeepSearchAgent]
    end
    
    subgraph "处理节点层"
        E[ReportStructureNode<br/>报告结构生成]
        F[FirstSearchNode<br/>初始搜索]
        G[FirstSummaryNode<br/>初始总结]
        H[ReflectionNode<br/>反思搜索]
        I[ReflectionSummaryNode<br/>反思总结]
        J[ReportFormattingNode<br/>报告格式化]
    end
    
    subgraph "LLM层"
        K[DeepSeekLLM]
        L[OpenAILLM]
        M[BaseLLM抽象类]
    end
    
    subgraph "工具层"
        N[Tavily搜索]
        O[文本处理工具]
        P[配置管理]
    end
    
    subgraph "状态管理层"
        Q[State状态对象]
        R[Paragraph段落对象]
        S[Research研究对象]
        T[Search搜索记录]
    end
    
    subgraph "数据持久化"
        U[JSON状态文件]
        V[Markdown报告]
        W[日志文件]
    end
    
    A --> D
    B --> D
    C --> D
    
    D --> E
    D --> F
    D --> G
    D --> H
    D --> I
    D --> J
    
    E --> K
    E --> L
    F --> K
    F --> L
    G --> K
    G --> L
    H --> K
    H --> L
    I --> K
    I --> L
    J --> K
    J --> L
    
    K --> M
    L --> M
    
    F --> N
    H --> N
    
    D --> O
    D --> P
    
    D --> Q
    Q --> R
    R --> S
    S --> T
    
    Q --> U
    D --> V
    D --> W
    
    style A fill:#e1f5fe
    style D fill:#f3e5f5
    style E fill:#fff3e0
    style F fill:#fff3e0
    style G fill:#fff3e0
    style H fill:#fff3e0
    style I fill:#fff3e0
    style J fill:#fff3e0
    style K fill:#e8f5e8
    style L fill:#e8f5e8
    style N fill:#fce4ec
    style Q fill:#f1f8e9

API 参考

DeepSearchAgent

主要的Agent类，提供完整的深度搜索功能。

class DeepSearchAgent:
    def __init__(self, config: Optional[Config] = None)
    def research(self, query: str, save_report: bool = True) -> str
    def get_progress_summary(self) -> Dict[str, Any]
    def load_state(self, filepath: str)
    def save_state(self, filepath: str)

配置

配置管理类，控制Agent的行为参数。

class Config:
    # API密钥
    deepseek_api_key: Optional[str]
    openai_api_key: Optional[str] 
    tavily_api_key: Optional[str]
    
    # 模型配置
    default_llm_provider: str = "deepseek"
    deepseek_model: str = "deepseek-chat"
    openai_model: str = "gpt-4o-mini"
    
    # 搜索配置
    max_search_results: int = 3
    search_timeout: int = 240
    max_content_length: int = 20000
    
    # Agent配置
    max_reflections: int = 2
    max_paragraphs: int = 5

示例

示例1：基本研究

from src import create_agent

# 快速创建Agent
agent = create_agent()

# 执行研究
report = agent.research("量子计算的发展现状")
print(report)

示例2：自定义研究参数

from src import DeepSearchAgent, Config

config = Config(
    max_reflections=4,        // 更深度的反思
    max_search_results=8,     // 更多搜索结果
    max_paragraphs=6          // 更长的报告
)

agent = DeepSearchAgent(config)
report = agent.research("人工智能的伦理问题")

示例3：状态管理

# 开始研究
agent = DeepSearchAgent()
report = agent.research("区块链技术应用")

// 保存状态
agent.save_state("blockchain_research.json")

// 稍后恢复状态
new_agent = DeepSearchAgent()
new_agent.load_state("blockchain_research.json")

// 检查进度
progress = new_agent.get_progress_summary()
print(f"研究进度: {progress['progress_percentage']}%")

高级功能

多模型支持

// 使用DeepSeek
config = Config(default_llm_provider="deepseek")

// 使用OpenAI
config = Config(default_llm_provider="openai", openai_model="gpt-4o")

自定义输出

config = Config(
    output_dir="custom_reports",           // 自定义输出目录
    save_intermediate_states=True          // 保存中间状态
)

常见问题

Q: 支持哪些LLM？

A: 目前支持：

• DeepSeek: 推荐使用，性价比高
• OpenAI: GPT-4o、GPT-4o-mini等
• 可以通过继承BaseLLM类轻松添加其他模型

Q: 如何获取API密钥？

A:

• DeepSeek: 访问 DeepSeek平台 注册获取
• Tavily: 访问 Tavily 注册获取（每月1000次免费）
• OpenAI: 访问 OpenAI平台 获取

获取密钥后，直接编辑项目根目录的config.py文件填入即可。

Q: 研究报告质量如何提升？

A: 可以通过以下方式优化：

• 增加max_reflections参数（更多反思轮次）
• 增加max_search_results参数（更多搜索结果）
• 调整max_content_length参数（更长的搜索内容）
• 使用更强大的LLM模型

Q: 如何自定义提示词？

A: 修改src/prompts/prompts.py文件中的系统提示词，可以根据需要调整Agent的行为。

Q: 支持其他搜索引擎吗？

A: 当前主要支持Tavily，但可以通过修改src/tools/search.py添加其他搜索引擎支持。

贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启Pull Request

许可证

本项目采用MIT许可证 - 查看 LICENSE 文件了解详情。

致谢

• 感谢 DeepSeek 提供优秀的LLM服务
• 感谢 Tavily 提供高质量的搜索API

---

如果这个项目对您有帮助，请给个Star！

DeepSearchAgent-Demo 快速上手指南

Deep Search Agent 是一个无框架的深度搜索 AI 代理，能够通过多轮搜索和反思生成高质量的研究报告。本指南将帮助您快速在本地部署并运行该工具。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Windows, macOS 或 Linux
• Python 版本: 3.9 或更高版本
• API 密钥: 您需要准备以下服务的 API Key（可在代码配置或 Web 界面中填入）：
  • LLM: DeepSeek (推荐) 或 OpenAI
  • 搜索引擎: Tavily

检查 Python 版本：

python --version

2. 安装步骤

第一步：克隆项目

将项目代码下载到本地：

git clone <your-repo-url>
cd Demo\ DeepSearch\ Agent

第二步：创建并激活虚拟环境

推荐使用 conda 或 venv 隔离环境。

使用 Conda:

conda create -n deepsearch python=3.9
conda activate deepsearch

使用 venv:

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

第三步：安装依赖

安装项目所需的 Python 包。 (注：如遇下载缓慢，可添加国内镜像源参数，如 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple)

pip install -r requirements.txt

第四步：配置 API 密钥

项目根目录下已有 config.py 文件，请使用文本编辑器打开并填入您的密钥：

# config.py

# DeepSeek API Key (推荐)
DEEPSEEK_API_KEY = "your_deepseek_api_key_here"

# OpenAI API Key (可选)
OPENAI_API_KEY = "your_openai_api_key_here"

# Tavily 搜索 API Key
TAVILY_API_KEY = "your_tavily_api_key_here"

# 默认使用 DeepSeek 模型
DEFAULT_LLM_PROVIDER = "deepseek"

3. 基本使用

您可以通过以下三种方式快速启动工具：

方式一：运行示例脚本（最快体验）

直接运行预设的研究任务，查看控制台输出的研究报告：

python examples/basic_usage.py

方式二：启动 Web 界面（推荐）

启动基于 Streamlit 的图形化界面，无需修改配置文件，可直接在网页中输入 API Key 和研究主题：

streamlit run examples/streamlit_app.py

运行后，浏览器会自动打开本地服务地址，您可以在界面中输入查询（例如："2025 年人工智能发展趋势”），系统将自动执行多轮搜索与反思并生成报告。

方式三：编程调用

在您自己的 Python 脚本中集成该 Agent：

from src import DeepSearchAgent, load_config

# 加载配置
config = load_config()

# 创建 Agent 实例
agent = DeepSearchAgent(config)

# 执行研究任务
query = "量子计算的发展现状"
final_report = agent.research(query, save_report=True)

# 打印结果
print(final_report)

生成的 Markdown 格式报告默认保存在项目根目录的 reports/ 文件夹中。