### Install Node.js 22+ Source: https://deepwiki.com/bytedance/deer-flow/6 Guides for installing Node.js version 22 or later using nvm (recommended) or downloading from the official Node.js website. ```shell # Using nvm (recommended) nvm install 22 nvm use 22 # Or download from nodejs.org ``` -------------------------------- ### Start LangGraph Development Server Source: https://deepwiki.com/bytedance/deer-flow/6-development-and-deployment Commands to start the LangGraph development server for debugging workflows. It includes a make command and manual installations for different operating systems, using uvx for package management and langgraph-cli for the dev server. ```bash # Start LangGraph development server make langgraph-dev # Or manually (Mac): uvx --refresh --from "langgraph-cli[inmem]" \ --with-editable . \ --python 3.12 \ langgraph dev --allow-blocking # Or manually (Windows/Linux): pip install -e . pip install -U "langgraph-cli[inmem]" langgraph dev ``` -------------------------------- ### Build and Start Frontend for Production Source: https://deepwiki.com/bytedance/deer-flow/6 Commands to build the frontend application for production and then start the production server. ```shell pnpm build pnpm start ``` -------------------------------- ### Install Dependencies with UV Source: https://deepwiki.com/bytedance/deer-flow/6 Commands to install project dependencies using uv, with options to include development, testing, or all extra dependencies. ```shell # Production dependencies only uv sync # With development tools uv sync --extra dev # With testing tools uv sync --extra test # All extras uv sync --all-extras ``` -------------------------------- ### Start Docker Compose Services Source: https://deepwiki.com/bytedance/deer-flow/6-development-and-deployment Starts the services defined in the docker-compose.yml file, bringing up both the backend and frontend containers. ```docker # Start services docker compose up # Start in detached mode docker compose up -d ``` -------------------------------- ### Start Frontend Development Server Source: https://deepwiki.com/bytedance/deer-flow/6 Instructions to start the frontend development server, which watches for changes and provides hot-reloading. It notes that the .env file is read from the project root. ```shell # Reads .env from project root pnpm dev # Open http://localhost:3000 ``` -------------------------------- ### Install UV Package Manager Source: https://deepwiki.com/bytedance/deer-flow/6 Instructions for installing the UV package manager on Unix/macOS and Windows systems using curl and PowerShell respectively. ```shell # Unix/macOS curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` -------------------------------- ### Install Frontend Dependencies with pnpm Source: https://deepwiki.com/bytedance/deer-flow/6 Command to install all necessary dependencies for the frontend project using the pnpm package manager. ```shell pnpm install ``` -------------------------------- ### Configure Environment Variables and Files Source: https://deepwiki.com/bytedance/deer-flow/6 Instructions for copying example environment configuration and creating the conf.yaml file, followed by editing the .env file with API keys. ```shell # Copy example configuration cp .env.example .env # Edit .env with your API keys nano .env # Create conf.yaml (see Configuration guide) nano conf.yaml ``` -------------------------------- ### Install or Enable pnpm Source: https://deepwiki.com/bytedance/deer-flow/6 Methods for installing or enabling the pnpm package manager. This includes global installation via npm or enabling it through Corepack, which is included with Node.js. ```bash # Install globally npm install -g pnpm # Or enable Corepack corepack enable ``` -------------------------------- ### Install Web UI Dependencies using pnpm Source: https://deepwiki.com/bytedance/deer-flow/index Installs frontend dependencies for the Web UI using the pnpm package manager. This command should be run from the 'web' directory. ```shell cd web pnpm install ``` -------------------------------- ### Integrated Development Setup Source: https://deepwiki.com/bytedance/deer-flow/6 Outlines two methods for setting up an integrated development environment, including using a bootstrap script or manually running backend and frontend in separate terminals. ```shell # Option 1: Use bootstrap script (if available) ./bootstrap.sh -d # Option 2: Manual setup in separate terminals # Terminal 1 - Backend cd deer-flow source .venv/bin/activate uv run uvicorn src.server.app:app --reload --port 8000 # Terminal 2 - Frontend cd deer-flow/web pnpm dev # Backend runs on: http://localhost:8000 # Frontend runs on: http://localhost:3000 ``` -------------------------------- ### Configure LLM and Tools for DeerFlow Source: https://deepwiki.com/bytedance/deer-flow/index Copies the example configuration file and prompts the user to edit it to specify LLM models, search engine choices, and RAG provider settings. ```shell cp conf.yaml.example conf.yaml # Edit conf.yaml to specify: # - LLM models for each agent type # - Search engine selection # - RAG provider settings ``` -------------------------------- ### Install pnpm Package Manager Source: https://deepwiki.com/bytedance/deer-flow/6 Instructions for installing the pnpm package manager globally using npm or Corepack, with specific version instructions. ```shell npm install -g pnpm@10.6.5 # Or using Corepack (Node.js 16+) corepack enable corepack prepare pnpm@10.6.5 --activate ``` -------------------------------- ### PostgreSQL Checkpointing Setup (Python) Source: https://deepwiki.com/bytedance/deer-flow/5-backend-services Configures PostgreSQL for LangGraph checkpointing when LANGGRAPH_CHECKPOINT_DB_URL starts with 'postgresql://'. It sets up an AsyncConnectionPool and AsyncPostgresSaver. ```python from langgraph.checkpoint.async_postgres import AsyncPostgresSaver from asyncpg import AsyncConnectionPool async def setup_postgres_checkpoint(db_url: str): pool = await AsyncConnectionPool(db_url, min_size=1, max_size=5, autocommit=True, record_class=dict) checkpointer = AsyncPostgresSaver(pool=pool) await checkpointer.setup() # Attach checkpointer and store to the graph return checkpointer ``` -------------------------------- ### Install PostgreSQL Dependencies for Checkpointing Source: https://deepwiki.com/bytedance/deer-flow/6-development-and-deployment Commands to install psycopg with binary support or system-level libpq-dev for PostgreSQL connectivity. This is a dependency for using PostgreSQL for LangGraph checkpointing. ```bash # Install binary package (if supported) pip install psycopg[binary] # Or install libpq system package # Ubuntu/Debian: apt-get install libpq-dev # macOS: brew install postgresql ``` -------------------------------- ### Manage Node.js Versions with nvm Source: https://deepwiki.com/bytedance/deer-flow/6 Instructions for managing Node.js versions using nvm. This includes checking the current Node.js version, installing a specific version, and switching to a desired version. NVM (Node Version Manager) allows for multiple Node.js installations. ```bash # Check Node version node --version # Use nvm nvm install 22 nvm use 22 ``` -------------------------------- ### MongoDB Checkpointing Setup (Python) Source: https://deepwiki.com/bytedance/deer-flow/5-backend-services Configures MongoDB for LangGraph checkpointing when the URL starts with 'mongodb://'. It initializes an AsyncMongoDBSaver and streams graph events for state persistence. ```python from langgraph.checkpoint.mongodb import AsyncMongoDBSaver async def setup_mongodb_checkpoint(db_url: str): checkpointer = AsyncMongoDBSaver.from_uri(db_url) # Attach checkpointer and store to the graph # Stream graph events with automatic state persistence return checkpointer ``` -------------------------------- ### Install Python 3.12+ Source: https://deepwiki.com/bytedance/deer-flow/6 Provides commands for installing Python version 3.12 or later on macOS and Ubuntu/Debian systems, with an option to download from python.org. ```shell # macOS (Homebrew) brew install python@3.12 # Ubuntu/Debian sudo apt install python3.12 # Or download from python.org ``` -------------------------------- ### Manage Frontend Dependencies with pnpm Source: https://deepwiki.com/bytedance/deer-flow/6 Commands for managing frontend dependencies using pnpm. This includes installing from a lock file for CI/production, updating the lock file, updating a specific package, or updating all packages to their latest versions. Ensure pnpm is installed. ```bash # Install from lock file (CI/production) pnpm install --frozen-lockfile # Update lock file pnpm install # Update specific package pnpm update next # Update all packages pnpm update --latest ``` -------------------------------- ### Configure Environment Variables for DeerFlow Source: https://deepwiki.com/bytedance/deer-flow/index Copies the example environment file and instructs the user to edit it with necessary API keys for various services like search engines, LLM providers, and optional configurations. ```shell cp .env.example .env # Edit .env with API keys: # - TAVILY_API_KEY (or other search engine keys) # - LLM provider API keys # - Optional: TTS, RAG, MCP configurations ``` -------------------------------- ### Lint Frontend with pnpm Source: https://deepwiki.com/bytedance/deer-flow/6-development-and-deployment Initiates a comprehensive frontend linting process using pnpm. This involves installing dependencies, running ESLint, TypeScript checks, Jest tests, and verifying the production build. ```makefile make lint-frontend ``` -------------------------------- ### Install Python Dependencies using uv Source: https://deepwiki.com/bytedance/deer-flow/index Installs Python dependencies from pyproject.toml using the uv package manager. This command automatically creates a virtual environment named .venv. ```shell uv sync ``` -------------------------------- ### Start DeerFlow Web UI in Development Mode Source: https://deepwiki.com/bytedance/deer-flow/index Launches both the backend (FastAPI) and frontend (Next.js) servers for local development. The backend runs on port 8000 and the frontend on port 3000. ```shell # Start both backend and frontend servers ./bootstrap.sh -d # macOS/Linux # or bootstrap.bat -d # Windows ``` -------------------------------- ### Run Development Server with LangGraph Studio (Shell) Source: https://deepwiki.com/bytedance/deer-flow/1-overview This command launches the LangGraph development server with a specific Python version and editable installation of the current project. It enables access to the LangGraph Studio UI for visual debugging, workflow visualization, and real-time execution tracing. The `--refresh` flag ensures changes are reloaded automatically. ```shell # Start LangGraph development server uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.12 langgraph dev --allow-blocking ``` -------------------------------- ### Verify Deer-Flow Installation Source: https://deepwiki.com/bytedance/deer-flow/6 Commands to run the Deer-Flow application, either through the console UI or as a FastAPI server. ```shell # Run console UI uv run main.py # Or run FastAPI server uv run uvicorn src.server.app:app --reload ``` -------------------------------- ### Build and Run DeerFlow Docker Full Stack Source: https://deepwiki.com/bytedance/deer-flow/index Builds Docker images for both the backend and frontend, and then starts them using Docker Compose. This command orchestrates both services within a shared network. ```shell # Full stack (backend + frontend) docker compose build docker compose up ``` -------------------------------- ### Example Output for Configured LLM Models (JSON) Source: https://deepwiki.com/bytedance/deer-flow/3 Illustrates the expected JSON output format for the `get_configured_llm_models()` function, showing LLM types mapped to lists of their respective model names. ```json { "basic": ["doubao-1.5-pro-32k-250115"], "reasoning": ["qwen3-235b-a22b-thinking-2507"], "code": ["qwen3-coder-480b-a35b-instruct"] } ``` -------------------------------- ### DeerFlow Agent Routing Logic Example Source: https://deepwiki.com/bytedance/deer-flow/1-overview Illustrates the logic for routing tasks to specialized agents based on the step type and requirements. This code snippet shows how the system selects the appropriate agent (researcher, coder, or analyst) and assigns them the necessary tools for execution. ```python # Simplified from actual implementation if step.step_type == "research" and step.need_search: agent = create_agent("researcher", [web_search, crawl, retriever, *mcp_tools]) elif step.step_type == "processing": agent = create_agent("coder", [python_repl_tool]) elif step.step_type == "analysis": agent = create_agent("analyst", []) # Pure reasoning, no tools ``` -------------------------------- ### Manage Backend Dependencies with UV Lock Source: https://deepwiki.com/bytedance/deer-flow/6 Commands for managing backend dependencies using the UV lock command. This includes updating the lock file, upgrading all dependencies, or upgrading a specific package. Ensure UV is installed and accessible in your PATH. ```bash # Update lock file with new dependencies uv lock # Update all dependencies uv lock --upgrade # Update specific package uv lock --upgrade-package langchain ``` -------------------------------- ### Dashscope (Qwen Models) Configuration (YAML) Source: https://deepwiki.com/bytedance/deer-flow/3 Example YAML configuration for Dashscope, which hosts Qwen models. The configuration includes a specific base URL for Dashscope's compatible mode, the model name, and the API key. For reasoning types, an 'enable_thinking: True' parameter is added. ```yaml REASONING_MODEL: base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" model: "qwen3-235b-a22b-thinking-2507" api_key: YOUR_API_KEY ``` -------------------------------- ### Google AI Studio Model Configuration (YAML) Source: https://deepwiki.com/bytedance/deer-flow/3 Example YAML configuration for Google AI Studio (Gemini models). It requires setting the platform to 'google_aistudio', specifying the model name, and providing the API key. The API key is automatically mapped to `google_api_key` by the system. ```yaml BASIC_MODEL: platform: "google_aistudio" model: "gemini-2.5-flash" api_key: your_gemini_api_key ``` -------------------------------- ### OpenAI-Compatible Model Configuration (YAML) Source: https://deepwiki.com/bytedance/deer-flow/3 Example YAML configuration for using OpenAI-compatible LLM providers like Ollama. It specifies the base URL for the API endpoint, the desired model name, and an API key (which can be a dummy value for local setups). This configuration is used when the default OpenAI provider is selected. ```yaml BASIC_MODEL: base_url: "http://localhost:11434/v1" # Ollama endpoint model: "qwen3:8b" api_key: "ollama" # Dummy key for local models ``` -------------------------------- ### Create and Activate Virtual Environment with UV Source: https://deepwiki.com/bytedance/deer-flow/6 Steps to create a Python virtual environment using uv and activate it on Unix/macOS and Windows. ```shell uv venv source .venv/bin/activate # Unix/macOS # or .venv\Scripts\activate # Windows ``` -------------------------------- ### Navigate to Frontend Directory Source: https://deepwiki.com/bytedance/deer-flow/6 Command to change the current directory to the 'web' folder, which contains the frontend code. ```shell cd web ``` -------------------------------- ### Running the Server Source: https://deepwiki.com/bytedance/deer-flow/2 Instructions for running the DeepWiki server in development mode, including command-line arguments and Windows-specific event loop configuration. ```APIDOC ## Running the Server ### Development Mode The `server.py` entry point provides a CLI for server configuration: ```bash python server.py --host localhost --port 8000 --log-level info ``` **Arguments:** - `--reload`: Enable auto-reload (default: False on Windows, can be enabled manually) - `--host`: Bind address (default: "localhost") - `--port`: Bind port (default: 8000) - `--log-level`: Logging verbosity (choices: debug, info, warning, error, critical) When `--log-level=debug`, the server enables DEBUG logging for `src`, `langchain`, and `langgraph` packages for detailed diagnostic information. ### Windows Event Loop Configuration On Windows, the server automatically configures `WindowsSelectorEventLoopPolicy` to ensure compatibility with psycopg (PostgreSQL driver) and other libraries: ```python if os.name == "nt": asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy()) ``` This workaround addresses issues with the default ProactorEventLoop on Windows, which lacks `add_reader`/`add_writer` support. ``` -------------------------------- ### Example Milvus RAG Provider Configuration Source: https://deepwiki.com/bytedance/deer-flow/3-configuration-and-settings An example .env file demonstrating the configuration variables required for the Milvus RAG provider. This includes the provider type, connection details, collection name, and embedding model settings. ```dotenv RAG_PROVIDER=milvus MILVUS_URI=./milvus_demo.db # Local Milvus Lite MILVUS_COLLECTION=documents MILVUS_EMBEDDING_PROVIDER=openai MILVUS_EMBEDDING_MODEL=text-embedding-ada-002 MILVUS_AUTO_LOAD_EXAMPLES=true # Load example markdown files ``` -------------------------------- ### GET /api/rag/resources Source: https://deepwiki.com/bytedance/deer-flow/5-backend-services Lists the available RAG resources or datasets that can be queried. ```APIDOC ## GET /api/rag/resources ### Description This endpoint lists the available RAG resources, such as document collections or datasets, that can be queried using the RAG system. ### Method GET ### Endpoint `/api/rag/resources` ### Parameters No parameters required. ### Request Example ``` GET /api/rag/resources ``` ### Response #### Success Response (200) - **resources** (array of objects) - A list of available RAG resources, each with 'id', 'name', and 'description'. #### Response Example ```json { "resources": [ {"id": "docs-v1", "name": "DeerFlow Documentation v1", "description": "Official documentation for DeerFlow."} ] } ``` ``` -------------------------------- ### GET /api/config Source: https://deepwiki.com/bytedance/deer-flow/5-backend-services Retrieves the configured LLM models and related settings. ```APIDOC ## GET /api/config ### Description This endpoint returns the current configuration for the Large Language Models (LLMs) used by the DeerFlow system, including available models and their associated settings. ### Method GET ### Endpoint `/api/config` ### Parameters No parameters required. ### Request Example ``` GET /api/config ``` ### Response #### Success Response (200) - **llm_models** (array of objects) - List of available LLM models, each with 'id' and 'name'. - **default_model** (string) - The ID of the default LLM model. - **settings** (object) - Various configuration settings related to LLM interactions. #### Response Example ```json { "llm_models": [ {"id": "gpt-3.5-turbo", "name": "GPT-3.5 Turbo"}, {"id": "claude-2", "name": "Claude 2"} ], "default_model": "gpt-3.5-turbo", "settings": { "temperature": 0.7, "max_tokens": 1024 } } ``` ``` -------------------------------- ### Run Frontend Tests with pnpm Source: https://deepwiki.com/bytedance/deer-flow/6 Provides commands for running frontend tests, including options for watch mode, single run, and coverage reports. ```shell # Watch mode pnpm test # Single run pnpm test:run # With coverage pnpm test:coverage ``` -------------------------------- ### GET /api/rag/config Source: https://deepwiki.com/bytedance/deer-flow/5-backend-services Retrieves the configuration details for the Retrieval-Augmented Generation (RAG) providers. ```APIDOC ## GET /api/rag/config ### Description This endpoint provides the configuration details for the various Retrieval-Augmented Generation (RAG) providers integrated with the DeerFlow system. ### Method GET ### Endpoint `/api/rag/config` ### Parameters No parameters required. ### Request Example ``` GET /api/rag/config ``` ### Response #### Success Response (200) - **providers** (array of objects) - A list of available RAG providers, each with 'id', 'name', and 'description'. #### Response Example ```json { "providers": [ {"id": "milvus", "name": "Milvus Vector Database", "description": "Connects to a Milvus instance for RAG."} ] } ``` ``` -------------------------------- ### Configuration Loading and Priority Source: https://deepwiki.com/bytedance/deer-flow/2-system-architecture Details the `Configuration` dataclass and how workflow parameters are loaded and prioritized, including default values and sources. ```APIDOC ## Configuration Parameters ### Description Defines all configurable workflow parameters within the `Configuration` dataclass. ### Sources - `src/config/configuration.py` - `src/config/loader.py` - `.env.example` - `conf.yaml.example` ### Parameters - **resources** (`List[Resource]`) - RAG retrieval targets. Default: `[]` - **max_plan_iterations** (`int`) - Maximum planning retries. Default: `1` - **max_step_num** (`int`) - Maximum steps per plan. Default: `3` - **max_search_results** (`int`) - Search result limit. Default: `3` - **report_style** (`str`) - Output format style. Default: `"academic"` - **enable_deep_thinking** (`bool`) - Use reasoning models. Default: `False` - **enforce_web_search** (`bool`) - Require search steps. Default: `False` - **interrupt_before_tools** (`List[str]`) - Tools requiring approval. Default: `[]` ``` -------------------------------- ### Rebuild Native Modules for Sharp Source: https://deepwiki.com/bytedance/deer-flow/6 Instructions for rebuilding native modules, specifically for the 'sharp' package, which is used for image processing. This step may be necessary if build errors occur. It's noted that 'sharp' might be ignored in the build process in `package.json`. ```bash # sharp is ignored in build (see package.json) # If issues persist, rebuild native modules pnpm rebuild sharp ``` -------------------------------- ### Build Configuration Source: https://deepwiki.com/bytedance/deer-flow/4-web-interface Notes on the build configuration, mentioning the use of different bundlers for development and production. ```APIDOC ## Build Configuration ### Description The frontend employs different bundlers for development and production environments to optimize for speed and stability. ### Sources - General project structure and build practices. ``` -------------------------------- ### Configure State Persistence Backends (Python) Source: https://deepwiki.com/bytedance/deer-flow/1-overview This snippet demonstrates how to configure state persistence backends for DeerFlow, supporting both PostgreSQL and MongoDB. It reads a checkpoint URL from environment variables and initializes the appropriate checkpointer and store. Dependencies include `AsyncConnectionPool` for PostgreSQL and `AsyncMongoDBSaver` for MongoDB. ```python # Simplified from src/server/app.py:603-652 checkpoint_url = get_str_env("LANGGRAPH_CHECKPOINT_DB_URL", "") if checkpoint_url.startswith("postgresql://"): async with AsyncConnectionPool(checkpoint_url, kwargs=connection_kwargs) as conn: checkpointer = AsyncPostgresSaver(conn) await checkpointer.setup() graph.checkpointer = checkpointer graph.store = in_memory_store elif checkpoint_url.startswith("mongodb://"): async with AsyncMongoDBSaver.from_conn_string(checkpoint_url) as checkpointer: graph.checkpointer = checkpointer graph.store = in_memory_store ``` -------------------------------- ### Get Configured LLM Models (Python) Source: https://deepwiki.com/bytedance/deer-flow/3 Retrieves a dictionary of all configured LLM models, grouped by their type. This function is useful for debugging and displaying available models to users. ```python def get_configured_llm_models() -> dict[str, list[str]]: """ Get all configured LLM models grouped by type. Returns: Dictionary mapping LLM type to list of configured model names. """ ``` -------------------------------- ### Select Web Search Tool based on Environment Variable (Python) Source: https://deepwiki.com/bytedance/deer-flow/2-system-architecture The `get_web_search_tool` function dynamically selects and instantiates a web search tool based on the `SELECTED_SEARCH_ENGINE` environment variable. It supports multiple search providers like Tavily, DuckDuckGo, and Brave, allowing flexible integration. ```python # From src/tools/__init__.py def get_web_search_tool(max_results: int = 3): if SELECTED_SEARCH_ENGINE == SearchEngine.TAVILY.value: return TavilySearch(max_results=max_results) elif SELECTED_SEARCH_ENGINE == SearchEngine.DUCKDUCKGO.value: return DuckDuckGoSearch(max_results=max_results) elif SELECTED_SEARCH_ENGINE == SearchEngine.BRAVE.value: return BraveSearch(max_results=max_results) # ... additional engines ``` -------------------------------- ### Ensure UV is in PATH Source: https://deepwiki.com/bytedance/deer-flow/6 Commands to ensure the UV package manager is accessible in your system's PATH. This involves exporting the directory containing UV's executable. It also includes a command to verify the UV installation. ```bash # Ensure UV is in PATH export PATH="$HOME/.cargo/bin:$PATH" # Verify installation uv --version ``` -------------------------------- ### Manage Python Versions with pyenv Source: https://deepwiki.com/bytedance/deer-flow/6 Instructions for managing Python versions using pyenv. This includes checking the current Python version and installing or setting a local Python version. Pyenv is a tool for managing multiple Python environments. ```bash # Check Python version python3 --version # Use pyenv to manage versions pyenv install 3.12.0 pyenv local 3.12.0 ``` -------------------------------- ### Lint and Format Frontend Code with pnpm Source: https://deepwiki.com/bytedance/deer-flow/6 Commands for linting and formatting the frontend codebase using pnpm, including options for auto-fixing and checking formatting. ```shell # Lint code pnpm lint # Auto-fix pnpm lint:fix # Format code pnpm format:write # Check formatting pnpm format:check ``` -------------------------------- ### Customizing Agent Models with conf.yaml and Python Source: https://deepwiki.com/bytedance/deer-flow/3 To assign a different LLM to an agent, modify both the `conf.yaml` file and the `AGENT_LLM_MAP` in Python. This example shows how to configure the `BASIC_MODEL` in `conf.yaml` to use 'deepseek-v3' for the 'researcher' agent. ```yaml BASIC_MODEL: base_url: https://api.deepseek.com model: "deepseek-v3" api_key: YOUR_API_KEY ``` ```python AGENT_LLM_MAP = { "researcher": "basic", # Will use deepseek-v3 ... } ```