DeepseSearch

中文指南

项目简介

DeepseSearch 是一个面向深度调研（Deep Research）的多代理工作流，由字节开源项目 Deerflow（https://github.com/bytedance/deer-flow）演进而来。原始 Deerflow 基于 LangGraph 构建，在复杂工程中显得冗余、抽象层级偏高。本仓库针对这些痛点重写了核心编排，提供一个以 pydantic-ai 框架实现的 Deerflow 版本，用于快速搭建检索、爬取与报告生成一体化流程。

为什么选择 Pydantic-AI

• LangGraph 的不足：节点状态通过动态字典传递，缺少类型约束；调试需穿过多层回调与拦截器；依赖 LangChain 生态使得部署裁剪困难。
• Pydantic-AI 的优势：
  • 以 Pydantic 强类型模型描述代理状态，运行期自动校验并提供清晰错误信息；
  • 原生 asyncio 执行模型，依赖轻量，可直接嵌入现有 Python 服务；
  • 继承 FastAPI 的开发体验，测试友好，适合快速迭代生产级代理应用。

快速开始

1. 安装依赖：uv sync（或 uv pip install -e .[dev]）。
2. 初始化配置：
   • cp .env.example .env，填写 LLM、MCP 等密钥；
   • cp conf.yaml.example conf.yaml，设置默认模型与工具端点。
3. 运行示例流程：uv run python main.py（生成报告保存于 output/）。
4. 执行测试：uvx pytest。
5. 代码质量检查：uvx ruff check --fix . 与 uvx ruff format .。

目录速览

src/workflow.py      # 基于 pydantic-ai 的主工作流
src/graph/           # 图节点与依赖构建
src/models/          # Pydantic 状态定义
src/tools/           # MCP、搜索等工具封装
src/llms/            # LLM 适配与缓存
src/prompts/, config # 提示词与配置模板
tests/               # Pytest 用例

贡献建议

• 启用 git config core.hooksPath .git-hooks 配合 uvx prek，保证提交前通过 Ruff 与自定义钩子。
• 新增节点或工具时需同步补充 tests/ 覆盖。
• 提交信息保持简洁祈使句，PR 中注明调研流程与配置的影响，并附示例输出或日志。

---

English Guide

Project Overview

DeepseSearch is a deep-research workflow derived from ByteDance's Deerflow project (https://github.com/bytedance/deer-flow). Deerflow originally orchestrated multi-agent reasoning with LangGraph, but the abstraction proved heavy and redundant in production. This repository reimplements the orchestration with the pydantic-ai framework to deliver a lighter, strongly typed version tailored for rapid research, crawling, and reporting pipelines.

Why Pydantic-AI

• Limitations of LangGraph: Shared state travels through dictionaries without schema guarantees; debugging traverses nested callbacks; extensive LangChain dependencies complicate deployment and trimming.
• Advantages of Pydantic-AI:
  • Strongly typed Pydantic models validate every node input/output at runtime and surface precise error messages.
  • Native asyncio execution keeps dependencies minimal and integrates smoothly with existing Python services.
  • Captures the "FastAPI feeling"—confidence in iteration, easier automated testing, and a faster path to production-grade agents.

Getting Started

1. Install dependencies: uv sync (or uv pip install -e .[dev]).
2. Configure credentials:
   • cp .env.example .env and provide LLM/MCP keys.
   • cp conf.yaml.example conf.yaml to declare default models and tool endpoints.
3. Run the showcase workflow: uv run python main.py (reports land in output/).
4. Execute tests: uvx pytest.
5. Enforce quality: uvx ruff check --fix . and uvx ruff format ..

Repository Layout

src/workflow.py      # Main flow powered by pydantic-ai
src/graph/           # Graph construction and node wiring
src/models/          # Pydantic state definitions
src/tools/           # Tool adapters (MCP, search, etc.)
src/llms/            # LLM integration and caching
src/prompts/, config # Prompt templates and configuration assets
tests/               # Pytest suites

Contribution Notes

• Point Git hooks to .git-hooks and run uvx prek to keep linting/formatting checks automated.
• Add or update tests under tests/ whenever introducing new nodes or tools.
• Use concise imperative commit messages; describe workflow/configuration impact clearly in pull requests and attach sample outputs when behavior changes.