This page provides a comprehensive introduction to DeerFlow, its architecture, core components, and how they work together.
DeerFlow (Deep Exploration and Efficient Research Flow) is an open-source super agent harness that orchestrates LLM-based agents with sandboxed execution, persistent memory, skill-based workflows, and subagent delegation README.md1-12 It provides a complete runtime environment for AI agents to perform complex, multi-step tasks that require file manipulation, code execution, web search, and parallel task decomposition backend/AGENTS.md5-7
Sources: README.md1-12 backend/AGENTS.md5-7
DeerFlow serves as an execution runtime for LLM-based agents that need to:
The system is not a single agent implementation but a harness — infrastructure that provides agents with everything they need: filesystem access, tool integration, memory management, and execution isolation README.md12-13
Sources: README.md12-13 README.md29-33 README.md35-37 backend/AGENTS.md5-50 config.example.yaml110-188
DeerFlow uses a multi-service architecture with clear separation of concerns, unified under a reverse proxy.
The following diagram bridges the high-level service components to their respective code entities and ports.
Title: "DeerFlow Service Topology and Code Mapping"
Service Responsibilities:
| Service | Port | Purpose | Main Entry Point / Code |
|---|---|---|---|
| Nginx | 2026 | Unified reverse proxy entry point | backend/AGENTS.md12 |
| Gateway API | 8001 | FastAPI REST API and embedded agent runtime | backend/AGENTS.md10 backend/Makefile5 |
| Frontend | 3000 | Next.js web interface | backend/AGENTS.md11 |
| Provisioner | 8002 | K8s sandbox lifecycle management (Optional) | backend/AGENTS.md13 .env.example63-66 |
Sources: backend/AGENTS.md9-13 backend/Makefile5-8 .env.example63-77
The agent execution is governed by a Lead Agent which serves as the runtime entry point. It is constructed using a factory pattern that assembles the LangGraph system prompt and tool definitions backend/AGENTS.md33-34 It processes requests through a chain of middlewares that handle cross-cutting concerns backend/AGENTS.md35
Middleware Components: DeerFlow utilizes a robust middleware system to manage the agent's lifecycle and capabilities. The pipeline includes:
Sources: backend/AGENTS.md33-42 config.example.yaml25-49
DeerFlow provides isolated execution environments with virtual path translation to protect the host system backend/AGENTS.md38-41
Title: "Path Virtualization and Sandbox Interaction"
Sandbox Backends:
Sources: backend/AGENTS.md38-42 backend/pyproject.toml24 .env.example27-29
The subagent system allows the lead agent to delegate complex tasks to specialized agents backend/AGENTS.md43
task_tool to spawn subagents backend/AGENTS.md47Sources: backend/AGENTS.md43-47
DeerFlow uses a hierarchical configuration system to manage its extensive feature set.
config.yaml: Primary configuration defining models, log_level, token_usage, and sandbox providers config.example.yaml1-18 config.example.yaml95-110extensions_config.json: Manages extended configurations like mcpServers and skills backend/AGENTS.md24.env: Stores sensitive API keys and environment-specific overrides README.md122 .env.example1-93Request Routing: The Nginx configuration handles path-based routing to unify the services:
/api/langgraph/* routes to the Gateway's LangGraph-compatible API backend/AGENTS.md16/api/* (other) routes to Gateway REST routers for models, skills, memory, and artifacts backend/AGENTS.md59/ routes to the Next.js frontend interface backend/AGENTS.md11Sources: config.example.yaml1-110 backend/AGENTS.md10-25 backend/AGENTS.md56-60 .env.example1-93