🦌 SmartDeerFlow

AI-Powered Deep Research Framework with Multi-Agent Collaboration

English | 简体中文

🚀 Overview

SmartDeerFlow is a community-driven AI research framework that combines Large Language Models, Multi-Agent Systems, and Advanced Tools for automated research, content generation, and data analysis.

Key Highlights:

• 🤖 Multi-Agent Collaboration - Intelligent task distribution with role-based specialization and cross-agent communication
• 🧠 GFLQ Reflection System - Self-improving research quality with knowledge gap detection and iterative enhancement
• 🔄 Adaptive Research Flow - Dynamic strategy adjustment and consensus building across multiple agents
• 🔍 Multi-Source Intelligence - Tavily, Brave, DuckDuckGo, ArXiv integration with smart content analysis
• 📊 Rich Output Formats - Reports, Podcasts, Presentations with AI-powered generation
• 🌐 Flexible Interfaces - Web & Console UI with human-in-the-loop collaboration
• 🔗 Extensible Architecture - MCP protocol integration and RAG knowledge base support

Forked from DeerFlow with enhanced features and community-driven improvements.

📑 Table of Contents

• 🚀 Quick Start
• 🌟 Features
• ⚡ Performance
• 🏗️ Architecture
• 🔄 GFLQ Reflection Integration
• 📚 Examples
• 🐳 Docker
• 🛠️ Development
• ❓ FAQ
• 📜 License

🚀 Quick Start

Prerequisites

• Python 3.12+ and Node.js 22+
• Recommended: uv for Python, pnpm for Node.js

Installation

# 1. Clone and setup
git clone https://github.com/hqzhon/smart-deer-flow.git
cd smart-deer-flow
uv sync

# 2. Configure API keys
cp .env.example .env          # Add your API keys (Tavily, Brave, etc.)
cp conf.yaml.example conf.yaml  # Configure LLM settings

# 3. Optional: Install additional tools
brew install marp-cli         # For PPT generation
cd web && pnpm install        # For Web UI

Usage

# Console Mode (Quick Start)
uv run main.py "What is quantum computing?"

# Interactive Mode
uv run main.py --interactive

# Web UI Mode
./bootstrap.sh -d  # macOS/Linux
# Visit http://localhost:3000

📖 Configuration: See Configuration Guide for detailed setup instructions.

Supported Search Engines

SmartDeerFlow supports multiple search engines that can be configured in your .env file using the SEARCH_API variable:

• Tavily (default): A specialized search API for AI applications

  • Requires TAVILY_API_KEY in your .env file
  • Sign up at: https://app.tavily.com/home

• DuckDuckGo: Privacy-focused search engine

  • No API key required

• Brave Search: Privacy-focused search engine with advanced features

  • Requires BRAVE_SEARCH_API_KEY in your .env file
  • Sign up at: https://brave.com/search/api/

• Arxiv: Scientific paper search for academic research

  • No API key required
  • Specialized for scientific and academic papers

To configure your preferred search engine, set the SEARCH_API variable in your .env file:

# Choose one: tavily, duckduckgo, brave_search, arxiv
SEARCH_API=tavily

🤖 Multi-Agent System

Agent Architecture

Agent	Role	Capabilities
Coordinator	Workflow Manager	Task orchestration, user interface
Planner	Strategic Planning	Research decomposition, execution planning
Researcher	Information Gathering	Multi-source search, content analysis
Coder	Technical Analysis	Code execution, data processing
Reporter	Content Generation	Report synthesis, output formatting

🌟 Features

🤖 AI & LLM Integration

• Multi-Model Support - OpenAI, Anthropic, Qwen, and more via LiteLLM
• Smart Agent Coordination - Dynamic task distribution and collaboration
• Context-Aware Processing - Intelligent content understanding and generation

🔍 Research & Data Collection

• Multi-Source Search - Tavily, Brave, DuckDuckGo, ArXiv integration
• Web Crawling - Advanced content extraction with Jina
• RAG Integration - Private knowledge base support via RAGFlow
• MCP Extensions - Expandable tool ecosystem

🤖 Multi-Agent Collaboration

• Intelligent Coordination - Dynamic task distribution and agent orchestration
• Reflection Mechanism - Self-evaluation and iterative improvement
• Knowledge Gap Detection - Automatic identification of missing information
• Adaptive Planning - Dynamic research strategy adjustment
• Cross-Agent Communication - Seamless information sharing between agents
• Role-Based Specialization - Each agent optimized for specific tasks
• Consensus Building - Multi-agent decision making and validation

📊 Content Generation

• Research Reports - Comprehensive analysis and documentation
• Podcast Scripts - AI-powered audio content generation with TTS
• Presentations - Automated PowerPoint creation via Marp
• Interactive Editing - Notion-style block editing with AI assistance
• Multi-Format Output - JSON, Markdown, HTML, PDF support
• Voice Synthesis - Volcengine TTS integration for audio reports
• Chart Generation - Automated data visualization via MCP Chart Server

🤝 Human Collaboration

• Human-in-the-Loop - Interactive plan review and modification
• Real-time Feedback - Natural language plan editing
• Consensus Systems - Multi-agent decision making
• Role-based Access - Dynamic permission management

🔗 MCP (Model Context Protocol) Integration

• Extensible Tool Ecosystem - Support for MCP servers and custom tools
• Chart Generation - Built-in MCP Chart Server for data visualization
• GitHub Integration - MCP GitHub Trending for repository analysis
• Search Extensions - Tavily MCP for enhanced search capabilities
• Custom MCP Servers - Easy integration of third-party MCP services
• Dynamic Tool Loading - Runtime tool discovery and configuration
• API-First Design - RESTful endpoints for MCP server management

🧠 Advanced AI Features

• GFLQ Reflection Mechanism - Self-improving research quality
• Knowledge Gap Detection - Automatic identification of missing information
• Iterative Research Enhancement - Continuous improvement of research strategies
• Context-Aware Processing - Intelligent understanding of research objectives
• Multi-Model Orchestration - Seamless integration across different LLM providers

🏗️ Architecture

DeerFlow implements a modular multi-agent system architecture designed for automated research and code analysis. The system is built on LangGraph, enabling a flexible state-based workflow where components communicate through a well-defined message passing system.

Multi-Agent Collaboration Flow

The system employs a streamlined workflow with the following components:

1. Coordinator: The entry point that manages the workflow lifecycle

   • Initiates the research process based on user input
   • Delegates tasks to the planner when appropriate
   • Acts as the primary interface between the user and the system

2. Planner: Strategic component for task decomposition and planning

   • Analyzes research objectives and creates structured execution plans
   • Determines if enough context is available or if more research is needed
   • Manages the research flow and decides when to generate the final report

3. Research Node: An intelligent research component with reflection capabilities:

   • Independent State Management: Maintains its own research context and progress
   • Reflection Analysis: Self-evaluates research quality and completeness
   • Knowledge Gap Detection: Identifies missing information automatically
   • Adaptive Research: Generates follow-up queries based on reflection results
   • Multi-Tool Integration: Uses web search, crawling, and MCP services

4. Specialized Agents: Supporting agents for specific tasks:

   • Coder: Handles code analysis, execution, and technical tasks using Python REPL tool
   • Each agent operates within the LangGraph framework with optimized tool access

5. Reporter: Final stage processor for research outputs

   • Aggregates findings from the research team
   • Processes and structures the collected information
   • Generates comprehensive research reports

🔄 GFLQ Reflection Integration

SmartDeerFlow is implementing an advanced reflection mechanism based on GFLQ (Goal-Focused Learning Query) to enhance research quality and system intelligence.

Overview

The GFLQ reflection integration introduces a self-improvement capability that allows the system to:

• Analyze research gaps and identify missing information
• Generate follow-up queries to fill knowledge gaps
• Evaluate research completeness and suggest improvements
• Learn from past research patterns to optimize future queries

Key Features

• 🎯 Goal-Focused Analysis - Evaluates research against specific objectives
• 🔍 Gap Detection - Identifies missing information and knowledge gaps
• 🔄 Iterative Improvement - Continuously refines research strategies
• 📊 Quality Assessment - Measures research completeness and relevance
• ⚡ Fast Integration - Experimental MVP approach for rapid deployment

Benefits

• Improved Research Quality - More comprehensive and complete research results
• Intelligent Adaptation - System learns and improves research strategies
• Reduced Manual Intervention - Automatic gap detection and follow-up
• Enhanced User Experience - More relevant and thorough research outputs

Details: GFLQ Reflection Integration

🛠️ Integrated Tools & Services

Text-to-Speech Integration

DeerFlow includes advanced TTS capabilities for converting research reports to high-quality audio:

# TTS API with customizable parameters
curl --location 'http://localhost:8000/api/tts' \
--header 'Content-Type: application/json' \
--data '{
    "text": "Research report content...",
    "speed_ratio": 1.0,
    "volume_ratio": 1.0,
    "pitch_ratio": 1.0
}' \
--output research_audio.mp3

Built-in Tool Suite

Tool	Purpose	Configuration
SmartSearchTool	Multi-source web search	Tavily, DuckDuckGo, Brave, ArXiv
WebCrawler	Content extraction	Jina API integration
PythonREPL	Code execution	Sandboxed Python environment
VolcengineTTS	Voice synthesis	Customizable voice parameters
RAGRetriever	Knowl