DeerFlow Source Code Location: Complete Repository Structure Guide

The DeerFlow source code is located in the bytedance/deer-flow GitHub repository, with the Python backend in backend/src/ and the TypeScript frontend in frontend/.

DeerFlow is ByteDance's open-source agentic AI framework designed for building complex research and task automation workflows. Understanding the DeerFlow source code location is essential for developers contributing to the project, debugging agent behavior, or extending its tool ecosystem. This guide provides a comprehensive map of the repository structure, from the FastAPI gateway implementation to the Next.js frontend components.

DeerFlow Repository Structure Overview

The DeerFlow repository follows a monorepo pattern containing two distinct runtime environments:

Component	Language	Description	Source Location
Backend	Python	Core agent engine, API gateway, tool implementations, sandbox execution, and memory system.	backend/src/
Frontend	TypeScript / React (Next.js)	Web UI for interacting with agents, visualizing artifacts, and managing configurations.	frontend/

All source files are hosted under the repository root at https://github.com/bytedance/deer-flow.

Backend Source Code Location (backend/src/)

The Python backend contains the core agentic logic and is organized into functional modules under backend/src/.

Core Gateway and API (backend/src/gateway/)

The FastAPI application factory resides in backend/src/gateway/app.py. This module creates the main application instance, registers routers for models, skills, uploads, artifacts, and channels, and starts optional IM channel services.

Key entry points:

• API Gateway: backend/src/gateway/app.py – create_app() function
• Routers: backend/src/gateway/routers/ – Individual API endpoint definitions

Embedded Python Client (backend/src/client.py)

For programmatic interaction without running the HTTP server, DeerFlow provides DeerFlowClient in backend/src/client.py. This class builds LangChain agents on-demand, streams events, and offers convenience methods for common operations.

from src.client import DeerFlowClient

# Initialise client (reads config.yaml automatically)

client = DeerFlowClient()

# One-shot chat

response = client.chat("Summarize the key points of the 2023 AI trends report.")
print(response)

# Stream conversation (captures tool calls, artifacts, etc.)

for event in client.stream("Generate a slide deck about quantum computing."):
    print(event.type, event.data)

# List available models

print(client.list_models())

# Upload a PDF and convert it to markdown (auto-conversion)

upload_info = client.upload_files(thread_id="demo", files=["./reports/qc_overview.pdf"])
print(upload_info)

Agent System (backend/src/agents/)

The agent orchestration logic is located in backend/src/agents/:

• Lead Agent: backend/src/agents/lead_agent/ – Constructs the primary agent with middleware stack (title generation, sub-agent limits, image viewing, upload handling)
• Memory: backend/src/agents/memory/ – Long-term memory implementation
• Sub-agents: backend/src/subagents/ – Management of delegated task agents

Tools and Sandbox (backend/src/tools/ and backend/src/sandbox/)

Tool implementations reside in backend/src/tools/, including web search, file viewing, and presentation generation.

Isolated execution environments are managed under backend/src/sandbox/:

• Providers: Docker and local sandbox implementations
• Middleware: Execution wrappers for safe code running

Configuration (backend/src/config/)

Configuration models using Pydantic are stored in backend/src/config/:

• backend/src/config/memory_config.py – Memory system settings
• backend/src/config/model_config.py – LLM model configurations
• backend/src/config/sandbox_config.py – Sandbox execution parameters

Frontend Source Code Location (frontend/)

The user interface is built with Next.js and TypeScript.

Next.js Application Structure

The frontend entry point is frontend/pages/index.tsx. The application communicates with the backend gateway through the auto-generated OpenAPI client.

Key directories:

• frontend/pages/ – Next.js page routes
• frontend/components/ – React UI components
• frontend/public/ – Static assets

To start the development server:

make dev          # starts backend

make frontend-dev # starts Next.js dev server on http://localhost:2026

Key Configuration Files

At the repository root, config.example.yaml provides the default configuration template. This file defines models, sandbox mode, memory settings, and extension loading. The backend reads this configuration at startup to initialize the gateway, client, and agent systems.

How to Navigate the DeerFlow Source Code

When exploring the repository:

1. Start with the gateway – backend/src/gateway/app.py shows how all components wire together
2. Check the client – backend/src/client.py demonstrates high-level usage patterns
3. Trace agent execution – Begin at backend/src/agents/lead_agent/ and follow through to backend/src/tools/
4. Review tests – backend/tests/ contains examples of expected behavior for uploads, title generation, and sub-agent execution

Summary

• The DeerFlow source code is hosted at https://github.com/bytedance/deer-flow as a monorepo
• Backend code resides in backend/src/, containing the FastAPI gateway (backend/src/gateway/app.py), embedded client (backend/src/client.py), agent system (backend/src/agents/), and tools (backend/src/tools/)
• Frontend code is located in frontend/, built with Next.js and TypeScript, with the entry point at frontend/pages/index.tsx
• Configuration is managed through config.example.yaml at the repository root and Pydantic models in backend/src/config/

Frequently Asked Questions

Where is the main entry point for the DeerFlow API?

The main entry point is backend/src/gateway/app.py, which contains the create_app() factory function. This module initializes the FastAPI application, registers routers for models, skills, uploads, and artifacts, and starts the HTTP server. You can start the gateway using make dev from the repository root.

How do I find the DeerFlow agent implementation in the source code?

The agent implementation is split across several directories under backend/src/. The lead agent construction resides in backend/src/agents/lead_agent/, which composes middleware for title generation, sub-agent limits, and image viewing. Tool definitions are in backend/src/tools/, while sub-agent management is handled by backend/src/subagents/. The memory system is located at backend/src/agents/memory/.

What is the difference between the backend and frontend source locations?

The backend (backend/src/) contains Python code for the core agent engine, API gateway, tool implementations, sandbox execution, and memory systems. The frontend (frontend/) contains TypeScript and React code built with Next.js, providing the web UI for interacting with agents. The backend exposes REST APIs that the frontend consumes, with the frontend entry point at frontend/pages/index.tsx.

Where are DeerFlow configuration files stored?

Configuration files are primarily stored in two locations. The root directory contains config.example.yaml, which serves as the default template for model settings, sandbox modes, memory configuration, and extensions. The backend/src/config/ directory contains Pydantic-based Python modules like memory_config.py, model_config.py, and sandbox_config.py that define the configuration schemas used by the application at runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}