deer-flow/backend

DeerFlow Backend

Language: English | 简体中文

DeerFlow is a LangGraph-based AI super agent with sandbox execution, persistent memory, and extensible tool integration. The backend enables AI agents to execute code, browse the web, manage files, delegate tasks to subagents, and retain context across conversations - all in isolated, per-thread environments.

---

Architecture

                        ┌──────────────────────────────────────┐
                        │          Nginx (Port 2026)           │
                        │      Unified reverse proxy           │
                        └───────┬──────────────────┬───────────┘
                                │
            /api/langgraph/*    │    /api/* (other)
            rewritten to /api/* │
                                ▼
               ┌────────────────────────────────────────┐
               │        Gateway API (8001)              │
               │        FastAPI REST + agent runtime    │
               │                                        │
               │ Models, MCP, Skills, Memory, Uploads,  │
               │ Artifacts, Threads, Runs, Streaming    │
               │                                        │
               │ ┌────────────────────────────────────┐ │
               │ │ Lead Agent                         │ │
               │ │ Middleware Chain, Tools, Subagents │ │
               │ └────────────────────────────────────┘ │
               └────────────────────────────────────────┘

Request Routing (via Nginx):

• /api/langgraph/* → Gateway LangGraph-compatible API - agent interactions, threads, streaming
• /api/* (other) → Gateway API - models, MCP, skills, memory, artifacts, uploads, thread-local cleanup
• / (non-API) → Frontend - Next.js web interface

---

Core Components

Lead Agent

The single LangGraph agent (lead_agent) is the runtime entry point, created via make_lead_agent(config). It combines:

• Dynamic model selection with thinking and vision support
• Middleware chain for cross-cutting concerns (9 middlewares)
• Tool system with sandbox, MCP, community, and built-in tools
• Subagent delegation for parallel task execution
• System prompt with skills injection, memory context, and working directory guidance

Middleware Chain

Middlewares execute in strict order, each handling a specific concern:

#	Middleware	Purpose
1	ThreadDataMiddleware	Creates per-thread isolated directories (workspace, uploads, outputs)
2	UploadsMiddleware	Injects newly uploaded files into conversation context
3	SandboxMiddleware	Acquires sandbox environment for code execution
4	SummarizationMiddleware	Reduces context when approaching token limits (optional)
5	TodoListMiddleware	Tracks multi-step tasks in plan mode (optional)
6	TitleMiddleware	Auto-generates conversation titles from the original user request after first exchange; attachment-only messages use a sanitized file name (or N files uploaded for multiple attachments)
7	MemoryMiddleware	Queues conversations for async memory extraction
8	ViewImageMiddleware	Injects image data for vision-capable models (conditional)
9	ClarificationMiddleware	Intercepts clarification requests and interrupts execution (must be last)

When loop_detection.enabled is set, loop detection checks both repeated tool-call sets and per-tool frequency. Warnings do not skip the rest of a tool-call batch: any hard limit reached takes precedence and stops the entire batch before tool execution. Warning-only batches remain fully counted and receive a transient hint on the next model request.

Sandbox System

Per-thread isolated execution with virtual path translation:

• Abstract interface: execute_command, read_file, write_file, list_dir
• Providers: LocalSandboxProvider (filesystem) and AioSandboxProvider (Docker, in community/). Async runtime paths use async sandbox lifecycle hooks so startup, readiness polling, and release do not block the event loop. AioSandboxProvider validates active-cache and warm-pool containers during acquire/reuse, dropping definitively dead entries so a thread can provision a fresh sandbox after an unexpected container exit while keeping get() as an in-memory lookup. Backend health-check failures are treated as unknown, not dead, and a container that cannot be verified during discovery is simply not adopted (acquire falls through to create instead of failing).
• Virtual paths: /mnt/user-data/{workspace,uploads,outputs} → thread-specific physical directories
• Skills path: /mnt/skills → deer-flow/skills/ directory
• Skills loading: Recursively discovers nested SKILL.md files under skills/{public,custom} and preserves nested container paths
• SkillScan: Native offline deterministic scanning runs before the LLM skill scanner on installs and agent-managed skill writes; CRITICAL findings block and warning findings become LLM context
• File-write safety: str_replace serializes read-modify-write per (sandbox.id, path) so isolated sandboxes keep concurrency even when virtual paths match
• Tools: bash, ls, read_file, write_file, str_replace (write_file overwrites by default and exposes append for end-of-file writes; bash is disabled by default when using LocalSandboxProvider; use AioSandboxProvider for isolated shell access)

Subagent System

Async task delegation with concurrent execution:

• Built-in agents: general-purpose (full toolset) and bash (command specialist, exposed only when shell access is available)
• Concurrency: Max 3 subagents per turn, 15-minute timeout
• Execution: Background thread pools with status tracking and SSE events
• Flow: Agent calls task() tool → executor runs subagent in background → polls for completion → returns result

Memory System

LLM-powered persistent context retention across conversations:

• Automatic extraction: Analyzes conversations for user context, facts, and preferences
• Scope-safe writes: Middleware extraction stores only durable, descriptive user-level facts; global summaries also require descriptive authority, while contradiction removals and consolidated facts fail closed when scope metadata is missing or task/project-local
• Atomic replacements: A contradiction removal linked to a replacement runs only after the replacement survives scope/confidence gates, deduplication, and fact-limit trimming
• Structured storage: User context (work, personal, top-of-mind), history, and confidence-scored facts
• Debounced updates: Batches updates to minimize LLM calls (configurable wait time)
• System prompt injection: Top facts + context injected into agent prompts
• Run-level memory identity: GET /api/threads/{thread_id}/runs/{run_id}/events?event_types=context:memory returns the SHA-256 identity of the effective hidden memory block without copying memory text into the event store
• Read failures: Strict backend policies (including legacy fail_closed) stop the turn, including at the 5-second async injection deadline. Fail-open reads continue without new context. Timeout handling does not wait for a free worker; a timed-out read may still occupy its worker until the backend returns.
• Storage: JSON file with mtime-based cache invalidation and canonical normalization for legacy sections/fact metadata

Tool Ecosystem

Category	Tools
Sandbox	bash, ls, read_file, write_file, str_replace
Built-in	present_files, ask_clarification, view_image, task (subagent)
Community	Tavily (web search), Jina AI (web fetch), Crawl4AI (web fetch), Firecrawl (scraping), fastCRW (scraping), DuckDuckGo (image search)
MCP	Any Model Context Protocol server (stdio, SSE, HTTP transports)
Skills	Domain-specific workflows injected via system prompt

Jina AI web fetch follows HTTP redirects from its API endpoint, including 307/308 redirects, which retain the POST method and body.

Run Event Storage

For direct RunEventStore.list_messages callers, after_seq and before_seq bound an exclusive message window. With both cursors, reads return the first limit messages inside that window in ascending sequence order across memory, JSONL, and database backends. Keep before_seq fixed and advance after_seq to the last returned sequence to page forward through a bounded history range.

Gateway API

FastAPI application providing REST endpoints for frontend integration:

Integer metadata filters match exact JSON integers, including signed-64-bit boundaries. Stored integers outside that range are ignored rather than rounded to a boundary (SQLite) or causing the search to fail (PostgreSQL).

Route	Purpose
GET /api/models	List available LLM models
GET/PUT /api/mcp/config	Manage MCP server configurations
POST /api/mcp/cache/reset	Reset cached MCP tools so they reload on next use
GET /api/skills	List skills visible to the caller
PUT /api/skills/{skill_name}	Enable or disable a skill (admin only)
POST /api/skills/install	Install skill from .skill archive
GET /api/memory	Retrieve memory data
POST /api/memory/reload	Force memory reload
GET /api/memory/config	Memory configuration
GET /api/memory/status	Combined config + data
GET /api/threads/{id}/runs/{run_id}/events	Debug/audit events for one run; filter event_types=context:memory for effective memory identity
POST /api/threads/{id}/uploads	Upload files (auto-converts PDF/PPT/Excel/Word to Markdown, rejects directory paths, auto-renames duplicate filenames in one request)
GET /api/threads/{id}/uploads/list	List uploaded files
DELETE /api/threads/{id}	Delete DeerFlow-managed local thread data after LangGraph thread deletion; unexpected failures are logged server-side and return a generic 500 detail
GET /api/threads/{id}/artifacts/{path}	Serve generated artifacts

Cancelling an upload waits for an already-running document conversion worker to finish before removing its temporary source. This prevents cleanup from deleting a file that the converter is still reading; cancellation can therefore take as long as that conversion.

Converted-upload ownership records live in each thread's upload-companions/ directory, outside the sandbox-mounted user-data/ tree. Older conversions without a record remain separate Markdown uploads and no longer provide an inferred outline for their source document; see file upload storage and upgrade behavior.

IM Channels

The IM bridge supports Feishu, Slack, and Telegram. Slack and Telegram still use the final runs.wait() response path, while Feishu now streams through runs.stream(["messages-tuple", "values"]), serializes rapid same-thread turns inside the channel manager, and updates a single in-thread card per source message in place.

Discord registers each typing-indicator loop before inbound message handling yields and refuses to start new typing work after the channel stops. Typing tasks are owned by the dedicated Discord event loop, so normal shutdown schedules bounded cancellation, awaiting, and map cleanup on that loop before closing the client. The Discord worker also drains the tasks in its finally block while its loop is still usable, covering disconnect and exception exits; if stop() encounters an already-stopped foreign loop, it never awaits those loop-bound tasks from the main loop. This serializes registration and cleanup across the main and Discord threads while preventing shutdown hangs and cross-loop RuntimeErrors.

For Feishu card updates, DeerFlow stores the running card's message_id per inbound message and patches that same card until the run finishes, preserving the existing OK / DONE reaction flow. When a follow-up arrives inside an existing Feishu topic while another turn is still running, the later message now waits on the mapped DeerFlow thread_id, receives a queued/running card on that exact source message, and keeps a compact source-message blockquote in subsequent patches so rapid consecutive questions remain distinguishable.

---

Quick Start

Prerequisites

• Python 3.12+
• uv package manager
• API keys for your chosen LLM provider

Installation

cd deer-flow

# Copy configuration files
cp config.example.yaml config.yaml

# Install backend dependencies
cd backend
make install

Configuration

Edit config.yaml in the project root:

models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    supports_thinking: false
    supports_vision: true

  - name: gpt-5-responses
    display_name: GPT-5 (Responses API)
    use: langchain_openai:ChatOpenAI
    model: gpt-5
    api_key: $OPENAI_API_KEY
    use_responses_api: true
    output_version: responses/v1
    supports_vision: true

Set your API keys:

export OPENAI_API_KEY="your-api-key-here"

Running

Full Application (from project root):

make dev  # Starts Gateway + Frontend + Nginx

Access at: http://localhost:2026

Backend Only (from backend directory):

# Gateway API + embedded agent runtime
make dev

Direct access: Gateway at http://localhost:8001

Terminal Workbench (TUI) — a terminal-native UI over the embedded harness, no services required:

uv pip install 'deerflow-harness[tui]'   # optional 'textual' dependency
deerflow                                 # launch the TUI
deerflow --print "summarize this repo"   # headless one-shot
deerflow --recursion-limit 250 --print "run a longer task"

Sessions opened in the TUI appear in the Web UI sidebar (it writes the shared threads_meta store under the local default user). See docs/TUI.md.

---

Project Structure

backend/
├── packages/harness/           # deerflow-harness package (import: deerflow.*)
│   └── deerflow/
│       ├── agents/             # Agent system
│       │   ├── lead_agent/     # Main agent (factory, prompts)
│       │   ├── middlewares/    # Middleware components
│       │   ├── memory/         # Memory extraction & storage
│       │   └── thread_state.py # ThreadState schema
│       ├── sandbox/            # Sandbox execution
│       │   ├── local/          # Local filesystem provider
│       │   ├── sandbox.py      # Abstract interface
│       │   ├── tools.py        # bash, ls, read/write/str_replace
│       │   └── middleware.py   # Sandbox lifecycle
│       ├── subagents/          # Subagent delegation
│       │   ├── builtins/       # general-purpose, bash agents
│       │   ├── executor.py     # Background execution engine
│       │   └── registry.py     # Agent registry
│       ├── tools/builtins/     # Built-in tools
│       ├── mcp/                # MCP protocol integration
│       ├── models/             # Model factory
│       ├── skills/             # Skill discovery & loading
│       ├── config/             # Configuration system
│       ├── runtime/            # Embedded run execution (RunManager, StreamBridge)
│       ├── persistence/        # Checkpointer/store engines & schema migrations
│       ├── guardrails/         # Pre-tool-call authorization providers
│       ├── tracing/            # Tracer factory & trace metadata
│       ├── uploads/            # Uploads manager
│       ├── tui/                # Terminal UI (`deerflow` console script)
│       ├── community/          # Community tools & providers
│       ├── reflection/         # Dynamic module loading
│       └── utils/              # Utilities
├── app/                        # FastAPI Gateway + IM channels (import: app.*)
│   ├── gateway/                # Gateway API
│   │   ├── app.py              # Application setup
│   │   └── routers/            # Route modules
│   └── channels/               # IM channel integrations
├── docs/                       # Documentation
├── tests/                      # Test suite
├── langgraph.json              # LangGraph graph registry for tooling/Studio compatibility
├── pyproject.toml              # Python dependencies
├── Makefile                    # Development commands
└── Dockerfile                  # Container build

langgraph.json is not the default service entrypoint. The scripts and Docker deployments run the Gateway embedded runtime; the file is kept for LangGraph tooling, Studio, or direct LangGraph Server compatibility.

To start the optional standalone development server and open its Studio URL:

cd backend
uv run langgraph dev --allow-blocking

Run it from backend/ so the CLI discovers langgraph.json. The in-memory server is intended for development and testing, not production deployment. The flag permits DeerFlow's synchronous configuration and graph-factory setup during local Studio requests; it is not a production-server setting. Its local Studio authentication and registered graph discovery are handled automatically; no custom connection headers are required. Assistant ownership/provenance is stamped by the server, and normal assistant-version selection remains available. Before the locked local runtime loads its persisted development store, DeerFlow repairs legacy assistant rows and version history so older metadata cannot reactivate server-only privileges or be discarded by runtime startup cleanup. Run uv sync after dependency changes; this compatibility path requires the declared LangGraph runtime versions and warns when the persisted-store contract does not match its expectations. The same file-based custom-app loading path used by this command is covered by the backend regression suite.

---

Configuration

Main Configuration (config.yaml)

Place in project root. Config values starting with $ resolve as environment variables.

Key sections:

• models - LLM configurations with class paths, API keys, thinking/vision flags
• tools - Tool definitions with module paths and groups
• tool_groups - Logical tool groupings
• sandbox - Execution environment provider
• skills - Skills directory paths
• title - Auto-title generation settings
• summarization - Context summarization settings
• subagents - Subagent system (enabled/disabled)
• memory - Memory system settings (enabled, storage, debounce, facts limits)

Provider note:

• models[*].use references provider classes by module path (for example langchain_openai:ChatOpenAI).
• If a provider module is missing, DeerFlow now returns an actionable error with install guidance (for example uv add langchain-google-genai).

Extensions Configuration (extensions_config.json)

MCP servers and skill states in a single file:

{
  "mcpServers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
    },
    "secure-http": {
      "enabled": true,
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "enabled": true,
        "token_url": "https://auth.example.com/oauth/token",
        "grant_type": "client_credentials",
        "client_id": "$MCP_OAUTH_CLIENT_ID",
        "client_secret": "$MCP_OAUTH_CLIENT_SECRET"
      }
    },
    "postgres": {
      "enabled": false,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
      "description": "PostgreSQL database access",
      "routing": {
        "mode": "prefer",
        "priority": 50,
        "keywords": ["orders", "users", "SQL", "database", "table"]
      },
      "tools": {
        "query": {
          "routing": {
            "priority": 100,
            "keywords": ["query database", "orders table", "metrics"]
          }
        }
      }
    }
  },
  "skills": {
    "pdf-processing": {"enabled": true}
  }
}

routing adds soft MCP preference hints to the agent prompt. It helps the model prefer a configured MCP tool for matching requests without forbidding other tools. When tool_search.enabled=true defers MCP schemas, matching routing metadata can auto-promote up to tool_search.auto_promote_top_k deferred schemas before the model call.

Environment Variables

• DEER_FLOW_CONFIG_PATH - Override config.yaml location
• DEER_FLOW_EXTENSIONS_CONFIG_PATH - Override extensions_config.json location
• Model API keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, etc.
• Tool API keys: TAVILY_API_KEY, GITHUB_TOKEN, etc.

LangSmith Tracing

DeerFlow has built-in LangSmith integration for observability. When enabled, all LLM calls, agent runs, tool executions, and middleware processing are traced and visible in the LangSmith dashboard.

Setup:

1. Sign up at smith.langchain.com and create a project.
2. Add the following to your .env file in the project root:

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
LANGSMITH_PROJECT=xxx

Legacy variables: The LANGCHAIN_TRACING_V2, LANGCHAIN_API_KEY, LANGCHAIN_PROJECT, and LANGCHAIN_ENDPOINT variables are also supported for backward compatibility. LANGSMITH_* variables take precedence when both are set.

Langfuse Tracing

DeerFlow also supports Langfuse observability for LangChain-compatible runs.

Add the following to your .env file:

LANGFUSE_TRACING=true
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_BASE_URL=https://cloud.langfuse.com

If you are using a self-hosted Langfuse deployment, set LANGFUSE_BASE_URL to your Langfuse host.

Dual Provider Behavior

If both LangSmith and Langfuse are enabled, DeerFlow initializes and attaches both callbacks so the same run data is reported to both systems.

If a provider is explicitly enabled but required credentials are missing, or the provider callback cannot be initialized, DeerFlow raises an error when tracing is initialized during model creation instead of silently disabling tracing.

Docker: In docker-compose.yaml, tracing is disabled by default (LANGSMITH_TRACING=false). Set LANGSMITH_TRACING=true and/or LANGFUSE_TRACING=true in your .env, together with the required credentials, to enable tracing in containerized deployments.

---

Development

Commands

make install    # Install dependencies
make dev        # Run Gateway API + embedded agent runtime with safe reload (port 8001)
make gateway    # Run Gateway API without reload (port 8001)
make lint       # Run linter (ruff)
make format     # Format code (ruff)
make detect-blocking-io  # Inventory blocking IO that may block the backend event loop
make migrate-rev MSG="..."  # Autogenerate a new alembic revision against the live ORM models

make dev pre-creates and excludes DEER_FLOW_HOME (by default backend/.deer-flow) and backend/sandbox from Uvicorn's reload watcher. Use this target instead of a bare uvicorn --reload: agent tasks write Python and other runtime files under DEER_FLOW_HOME, and watching that directory can restart the Gateway during an active run.

Schema Migrations

DeerFlow's application tables (runs, threads_meta, feedback, users, run_events, and the channel_* tables) are owned by alembic. The Gateway runs alembic upgrade head automatically on startup via bootstrap_schema(engine, backend=...), so operators do not run alembic manually in production. Bootstrap is concurrency-safe (Postgres advisory lock across processes; per-engine asyncio.Lock inside one SQLite process) and idempotent against pre-existing schemas (empty / legacy / versioned).

When you add or change an ORM model, ship the change as a new revision under packages/harness/deerflow/persistence/migrations/versions/:

make migrate-rev MSG="add foo column to runs"

The target invokes scripts/_autogen_revision.py, which builds a fresh temp SQLite at head and diffs the live models against it — so a clean checkout does not need a pre-existing ./data/deerflow.db. Review the generated file and switch raw op.add_column / op.drop_column calls to the idempotent helpers in migrations/_helpers.py before committing. There is no make migrate / make migrate-stamp target on purpose — Gateway startup is the only execution path, which keeps operational mistakes off the table. See backend/CLAUDE.md (Schema Migrations) for the full design.

Code Style

• Linter/Formatter: ruff
• Line length: 240 characters
• Python: 3.12+ with type hints
• Quotes: Double quotes
• Indentation: 4 spaces

Testing

# Default offline backend suite (four parallel shards; excludes live and blocking-I/O tests)
make test

# Run the same shards sequentially
make test TEST_JOBS=1

# Strict blocking-I/O suite
make test-blocking-io

# Explicit real-API DeerFlowClient integration suite
make test-live

The live suite requires a valid root config.yaml and API credentials. It may incur API costs or create local sandboxes, artifacts, and files, so it is not part of default test runs or CI. Direct pytest invocation of tests/test_client_live.py also requires DEER_FLOW_RUN_LIVE_TESTS=1.

make detect-blocking-io statically scans backend business code for blocking IO that may run on the backend event loop and is not test-coverage-bound. It prints a concise summary for human review and writes complete JSON findings to .deer-flow/blocking-io-findings.json at the repository root (regardless of whether the target is invoked from the repo root or from backend/). JSON findings include both broad IO category and review-oriented fields such as priority, location, blocking_call, event_loop_exposure, reason, and code. priority is a deterministic review ordering from the operation type, not proof of a bug. Bare-name same-file calls are resolved by function name, so duplicate helper names in one file can conservatively over-report async reachability.

---

Technology Stack

• LangGraph (1.0.6+) - Agent framework and multi-agent orchestration
• LangChain (1.2.3+) - LLM abstractions and tool system
• FastAPI (0.115.0+) - Gateway REST API
• langchain-mcp-adapters - Model Context Protocol support
• agent-sandbox - Sandboxed code execution
• markitdown - Multi-format document conversion
• tavily-python / firecrawl-py - Web search and scraping

---

Documentation

• Configuration Guide
• Architecture Details
• API Reference
• File Upload
• Path Examples
• Context Summarization
• Plan Mode
• Setup Guide

---

License

See the LICENSE file in the project root.

Contributing

See CONTRIBUTING.md for contribution guidelines.