DeerFlow 2.0: The Framework-Shaped Agent

What makes DeerFlow different

While Claude Code reads like a bespoke product and Crush reads like a polished Go terminal app, DeerFlow reads like a framework for building agent systems. It was originally a deep research tool by ByteDance but was completely rewritten from scratch into v2.0 — a general-purpose orchestration runtime with FastAPI gateway, LangGraph server, and a Next.js frontend.

The 14-layer middleware stack

Every agent turn in DeerFlow passes through a fixed-order middleware chain. No other repo in this set has a composable middleware architecture this deep; most handle these concerns inline or not at all.

Loop detection with 200-line bucketing

DeerFlow's LoopDetectionMiddleware is the most sophisticated loop detector in this set after Crush's SHA-256 approach. It hashes tool name + input + output, but has a critical special case:

For write_file and str_replace, the full arguments are hashed to avoid false positives from legitimate repeated edits. This is far more nuanced than most agents' "stop after N identical calls" approach.

Sub-agent orchestration with parallel execution

The lead agent can spawn sub-agents via the task_tool. The SubagentLimitMiddleware enforces hard limits:

Sub-agents run in background with cooperative cancellation via threading.Event checked at astream() iteration boundaries. Deferred cleanup uses asyncio.create_task() to avoid race conditions. The parent sees only the delegation call and the child's summary result — never the intermediate tool calls.

Real-time streaming of sub-agent messages is supported via the StreamBridge abstraction, which decouples agent workers (producers) from SSE endpoints (consumers). Currently uses MemoryStreamBridge (in-memory queue); Redis is planned for Phase 2 for horizontal scaling.

Model support: 6 custom providers + LangChain compatibility

DeerFlow uses a config-driven model factory (models/factory.py) with a use field like langchain_openai:ChatOpenAI or custom provider classes:

Recommended models from the README: Doubao-Seed-2.0-Code, DeepSeek V3.2, and Kimi 2.5.

SSE streaming and stream bridge

DeerFlow's SSE streaming is decoupled from the agent runtime via an abstract StreamBridge protocol:

This decoupling is architecturally significant: the agent runtime doesn't know about HTTP. It can run embedded, in a CLI, or on a separate server. The stream bridge is the only coupling, and it's pluggable — Redis support is planned for Phase 2 horizontal scaling.

Smoke-Test Skill

New in this update: a comprehensive smoke-test skill for end-to-end testing in .agent/skills/smoke-test/:

• Local and Docker deployment modes
• Automatic mode switching based on network conditions
• Phase-based execution: Code Update → Environment Check → Configuration → Deployment → Health Check → Report
• Checks Node.js 22+, pnpm, uv, nginx, and required ports (2026, 3000, 8001, 2024)
• Comprehensive SOP documentation and troubleshooting guide (613 lines)

Skill system and self-evolution

DeerFlow has a structured skills system with SKILL.md files in skills/public/ (built-in) and skills/custom/ (user-created). Skills support progressive loading, validation, and atomic writes with JSONL history tracking.

The most unusual feature: skill self-evolution. When skill_evolution.enabled: true, the agent can create or improve skills during a session. Triggers defined in the system prompt include:

• "5+ tool calls used" in a pattern worth codifying
• "User corrected approach" — the user overrode the agent's method
• "Non-obvious errors encountered" — the agent discovered a gotcha worth documenting

Skills are cached at startup with a warm-up daemon thread: warm_enabled_skills_cache(timeout=5.0). The skills cache pre-loads in a daemon background thread at startup for fast access.

LLM-driven memory system

DeerFlow's memory is not a vector database — it's an LLM extraction pipeline. The MemoryMiddleware uses an LLM to extract facts, preferences, corrections, and reinforcement signals from conversations:

• Per-agent namespaces — memory is scoped to specific agent types
• Correction detection — when the user corrects the agent, that signal is extracted as a high-confidence fact
• Reinforcement detection — when the user praises an approach, that's stored as positive reinforcement
• Upload-event scrubbing — sensitive uploaded data is automatically scrubbed from memory
• Confidence thresholds — facts below a configurable confidence are not stored
• Debouncing — memory updates are debounced (configurable debounce_seconds) to avoid excessive LLM calls

Guardrail system

DeerFlow has a pluggable guardrail system for pre-execution tool call validation. The GuardrailMiddleware uses a GuardrailProvider interface with evaluate() and aevaluate() methods:

Sandbox architecture

DeerFlow supports two sandbox providers:

Messaging channel integration

DeerFlow includes built-in support for messaging platforms in backend/app/channels/:

New in this update: WeChat integration (52KB, 1371 lines) with support for TEXT, IMAGE, VOICE, FILE, VIDEO message types, AES encryption, and QR code login. Discord channel also added.

Deferred tool loading (tool_search)

When tool_search.enabled: true, MCP tools are not bound directly to the agent. Instead, they are registered in a DeferredToolRegistry and exposed via a tool_search tool that the agent can discover at runtime.

This is a smart design for environments with many MCP servers: rather than polluting the agent's context with hundreds of tool descriptions, the agent can search for tools on demand. Only tools it actually needs get loaded.

ACP integration

DeerFlow has an invoke_acp_agent tool that calls external ACP-compatible agents. It expects ACP adapters (e.g., @zed-industries/claude-agent-acp, @zed-industries/codex-acp), not raw CLI binaries. This means DeerFlow can delegate work to Claude Code or Codex through the ACP protocol as a first-class tool call.

Configuration system

DeerFlow uses a versioned YAML config (config_version: 5) with:

• Environment variable interpolation — $OPENAI_API_KEY in config values
• Dynamic class resolution — use: package.module:ClassName loads any LangChain-compatible class
• Config upgrade script — make config-upgrade migrates older configs
• Pydantic validation — all config is validated at load time
• Per-agent configs — custom config.yaml files under agents/ with custom model, soul (prompt), skills, and tool groups

LLM error handling middleware

The LLMErrorHandlingMiddleware classifies errors into:

• Retriable: busy, transient errors (408, 429, 500) — retried up to 3 times with exponential backoff and Retry-After header respect
• Non-retriable: quota exceeded, auth errors — returns user-friendly AIMessage instead of crashing

It emits llm_retry stream events so the frontend can show retry progress to the user.

Citation System Removed

In a significant simplification, DeerFlow removed its citation system entirely in this update:

• Deleted SafeCitationContent component
• Deleted inline-citation.tsx (289 lines)
• Removed citation core utilities
• Replaced with simple MarkdownContent renderer

This suggests the complexity of citation handling wasn't worth it for their use case — a notable example of an agent choosing simplicity over feature completeness.

Where DeerFlow is weaker

Bottom line

DeerFlow is the most framework-shaped agent in this set. If Claude Code is a product, DeerFlow is a platform. Its 14-layer middleware stack, sub-agent orchestration with parallel execution, LLM-driven memory, skill self-evolution, and SSE stream bridge make it the most extensible runtime here.

The tradeoff is that it's less immediately usable as a CLI tool — you need to configure models, skills, and sandboxes to get it working. But if you want to build an agent system rather than use one, DeerFlow is the most interesting starting point.