DeerFlow-Py

A pure-Python super-agent collaboration framework inspired by ByteDance's DeerFlow, rebuilt from first principles with zero hidden abstractions.

Overview

DeerFlow-Py is a from-scratch, pure-Python reimplementation of the ideas behind ByteDance's DeerFlow — a Deep Exploration & Efficient Research multi-agent framework — plus a companion Harness for running, evaluating and serving agent workflows.

The original DeerFlow is built on top of LangGraph, LangChain and the MCP SDK. While powerful, that stack hides the internals behind many abstraction layers. DeerFlow-Py rebuilds the same ideas from first principles so that every moving part — the state machine, the ReAct loop, tool calling, MCP-style tool servers, human-in-the-loop interrupts, the four-layer memory system, the skills/middleware/plugin extension mechanisms, and the evaluation harness — is readable, hackable and dependency-light.

~4,900 lines of Python · 40+ source files · 24 unit tests · 19 runnable examples · zero LangGraph dependency

What's New in v0.2.0

Highlights

Core Engine

• Custom StateGraph engine — a faithful reimplementation of the LangGraph programming model: typed state channels (last_value / add_messages / add_documents), conditional edges, parallel fan-out, checkpointing and human-in-the-loop interrupts. No LangGraph dependency.

• ReAct Agent runtime — a clean Reason → Act → Observe loop with native function-calling, streaming, retry and token accounting.

• Channel reducer system — declarative state merging; nodes return partial updates, channels decide merge semantics (last-write-wins, append-with-dedup, etc.)

LLM & Tools

• Pluggable LLM client — OpenAI-compatible async client with streaming, tool-calling, JSON mode and automatic retries via tenacity. Works with OpenAI, DeepSeek, Moonshot, Zhipu, vLLM, Ollama, ...

• MCP-style tool protocol — tools are described with JSON-Schema and can be served over stdio/WebSocket, exactly like the Model Context Protocol. Bidirectional MCPServer + MCPClient.

• Built-in tools — DuckDuckGoSearchTool (free), TavilySearchTool (production), WebCrawlerTool (readability-lxml), PythonSandboxTool (subprocess + RLIMIT + timeout)

Agents

• Six specialised agents — Coordinator (routing), Planner (JSON plans), Researcher (search+crawl), Coder (Python sandbox), Reporter (Markdown reports), Critic (review+revise loop)

• Research workflow — plan → parallel research → critic review → iterative refinement → cited Markdown report

• Orchestrator — simplified multi-agent routing with shared memory and LLM-driven handoff

Extension System (v0.2.0)

• Four-layer memory — MemorySystem facade with remember_fact / recall_similar / scratch / fetch

• Skills — higher-level than Tools; composable; auto-convertible to OpenAI tool descriptors

• Middleware — onion-model before_agent / after_agent / before_tool / after_tool hooks

• Plugins — Plugin base class + PluginContext + PluginManager with three discovery mechanisms

Harness

• FastAPI server — /run, /eval, /stream (WebSocket), /datasets, /health

• Dataset management — SimpleQADataset (10 cases), GAIA format, JSONL import/export

• Three evaluators — ExactMatchEvaluator, ContainsEvaluator, LLMJudgeEvaluator (LLM-as-judge with rubric)

• Concurrent runner — asyncio.Semaphore-controlled parallel execution with token/latency telemetry

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Client Layer                                 │
│   CLI (deerflow)  ·  REST API (FastAPI)  ·  WebSocket (/stream)  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                    Harness Layer                                 │
│   Runner (concurrent)  ·  Evaluator (3 types)  ·  Datasets       │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                   Core Engine Layer                              │
│  StateGraph  ·  Channel Reducers  ·  Checkpointer  ·  Middleware │
│  Orchestrator  ·  MemorySystem (4-layer)                        │
└──────────────────────────────┬──────────────────────────────────┘
                               │
        ┌──────────┬──────────┼──────────┬──────────┬──────────┐
        ▼          ▼          ▼          ▼          ▼          ▼
  Coordinator  Planner  Researcher   Coder    Reporter    Critic
        │          │          │          │          │          │
        └──────────┴──────────┴──────────┴──────────┴──────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                      Tool Layer                                   │
│  web_search  ·  crawl_url  ·  python_run  ·  MCP Server/Client   │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                    Extension Layer (v0.2.0)                      │
│  Skills (Summarize/Translate/...)  ·  Middleware (5 built-in)     │
│  Plugins (entry_points/module/dir)                               │
└─────────────────────────────────────────────────────────────────┘

Project Structure

deerflow_py/
├── src/deerflow/
│   ├── core/                    # State machine engine (~1,300 lines)
│   │   ├── state.py             #   Channel reducers (last_value/add_messages/add_documents)
│   │   ├── graph.py             #   StateGraph + CompiledGraph (super-step execution)
│   │   ├── agent.py             #   ReAct Agent base class
│   │   ├── memory.py            #   Short-term memory + Checkpointer
│   │   ├── advanced_memory.py   #   ★ 4-layer memory system
│   │   └── orchestrator.py      #   Multi-agent routing
│   ├── llm/client.py           # OpenAI-compatible async client (~322 lines)
│   ├── tools/                   # Tool system (~900 lines)
│   │   ├── base.py              #   Tool/FunctionTool/ToolResult
│   │   ├── registry.py          #   ToolRegistry with concurrent dispatch
│   │   ├── search.py            #   DuckDuckGo + Tavily search
│   │   ├── crawler.py           #   Web page readability extraction
│   │   ├── python_sandbox.py    #   Subprocess-isolated code execution
│   │   └── mcp.py               #   MCP JSON-RPC 2.0 client/server
│   ├── agents/                   # 6 specialised agents (~440 lines)
│   │   ├── coordinator.py       #   Routes to the right specialist
│   │   ├── planner.py           #   Generates JSON research plans
│   │   ├── researcher.py        #   Web search + crawl (ReAct)
│   │   ├── coder.py             #   Python sandbox (write→run→fix)
│   │   ├── reporter.py          #   Markdown report synthesis
│   │   ├── critic.py            #   Review + pass/revise verdict
│   │   └── research_graph.py    #   Full workflow graph builder
│   ├── skills/                  # ★ Skills system (~300 lines)
│   ├── middleware/              # ★ Middleware system (~250 lines)
│   ├── plugins/                 # ★ Plugin system (~250 lines)
│   ├── prompts/                 # System prompts for each agent
│   ├── utils/                   # Logging, token estimation, helpers
│   └── cli.py                   # `deerflow` CLI entry point
├── harness/                     # Test & evaluation framework (~620 lines)
│   ├── datasets.py              #   TestCase, Dataset, SimpleQA, GAIA
│   ├── evaluator.py             #   ExactMatch, Contains, LLMJudge
│   ├── runner.py                #   Concurrent runner + RunReport
│   ├── server.py                #   FastAPI app (/run /eval /stream)
│   └── cli.py                   # `deerflow-harness` CLI
├── examples/                    # 19 runnable examples (all pass)
├── tests/                       # 24 unit tests (all pass)
├── docs/                        # Technical documentation
│   ├── DeerFlow_Py_Technical_Documentation.pdf  (40-page, 8 diagrams)
│   └── diagrams/                # Architecture/UML/sequence/flowchart PNGs
└── pyproject.toml

Quick Start

Installation

cd deerflow_py
pip install -e .

CLI Usage

# Set your LLM API key (or use MockLLM without one)
export OPENAI_API_KEY=sk-...
​
# Run a research workflow
deerflow "Summarise 2024 LLM agent trends"
​
# Start the Harness server
deerflow-harness serve --port 8000
​
# Run offline evaluation
deerflow-harness eval --dataset simple_qa --evaluator exact

Programmatic API

import asyncio
from deerflow import build_research_graph, LLMClient
​
async def main():
    llm = LLMClient.from_env()
    graph = build_research_graph(llm, max_revisions=2)
    result = await graph.ainvoke({
        "messages": [{"role": "user", "content": "Summarise 2024 LLM agent trends"}]
    })
    print(result.state["report"])
​
asyncio.run(main())

Without an API Key (MockLLM)

All examples work without an API key — they use a deterministic MockLLM that returns canned responses:

python3 examples/01_state_machine_basic.py
python3 examples/15_full_research_workflow.py
python3 examples/16_full_integration.py

Examples (19 total, all passing)

Key API Reference

State Machine

from deerflow import StateGraph, last_value, add_messages, add_documents
​
g = StateGraph()
g.add_node("planner", planner.run)
g.add_node("researcher", researcher.run)
g.add_conditional_edges("planner", lambda state: "researcher" if state["plan"] else "__end__")
g.add_edge("researcher", "__end__")
g.set_entry("planner")
compiled = g.compile(checkpointer=InMemoryCheckpointer())
​
result = await compiled.ainvoke({"messages": [...]}, thread_id="session-1")
# result.state, result.steps, result.trace, result.interrupted

Custom Agent

from deerflow import Agent, ToolRegistry, FunctionTool
​
class MyAgent(Agent):
    name = "my_agent"
    system_prompt = "You are a helpful assistant."
    max_iterations = 5
​
    def inject_context(self, ctx: dict) -> str:
        if ctx.get("current_step_desc"):
            return f"Current step: {ctx['current_step_desc']}"
        return ""
​
agent = MyAgent(llm, tools=ToolRegistry().register(my_tool))
response = await agent.arun([{"role": "user", "content": "Hello"}])

Memory System

from deerflow import MemorySystem, Episode

memory = MemorySystem.from_dir("./memory")
memory.remember_fact("user_name", "Alice")          # Long-term
memory.add_message({"role": "user", "content": "Hi"})  # Short-term
memory.store_episode(Episode(id="ep1", query="RAG", summary="...", outcome="..."))
similar = memory.recall_similar("RAG retrieval", limit=3)  # Episodic TF-IDF
memory.scratch("current_plan", {"steps": [1, 2, 3]})  # Working

Skills

from deerflow import SkillRegistry, SummarizeSkill, TranslateSkill

reg = SkillRegistry()
reg.register(SummarizeSkill(llm))
reg.register(TranslateSkill(llm))
result = await reg.execute("summarize", text="long text...", max_points=5)
# result.output, result.metadata, result.error

Middleware

from deerflow import MiddlewarePipeline, LoggingMiddleware, CacheMiddleware

pipe = MiddlewarePipeline()
pipe.add(LoggingMiddleware())
pipe.add(CacheMiddleware())
pipe.add(RateLimitMiddleware(rate=10, per=60))

# Hooks run in onion order: before A→B→C, after C→B→A
ctx = await pipe.run_before_agent(AgentContext(agent_name="x", messages=[]))
response = await pipe.run_after_agent(ctx, agent_response)

Plugins

from deerflow import Plugin, PluginContext, PluginManager

class MyPlugin(Plugin):
    name = "my-plugin"
    version = "1.0.0"

    def register(self, ctx: PluginContext) -> None:
        ctx.register_agent("my_agent", MyAgent)
        ctx.register_tool("my_tool", MyTool())
        ctx.register_skill("my_skill", MySkill(ctx.llm))
        ctx.register_middleware(LoggingMiddleware())

pm = PluginManager(llm=llm)
pm.register_plugin(MyPlugin())
pm.load_dir("./plugins")  # auto-discover deerflow_*.py

Comparison with Original DeerFlow

Testing

# Run all 24 unit tests
python -m pytest tests/ -v

# Run all 19 examples
for f in examples/0*.py examples/1*.py; do python3 "$f"; done

Technology Stack

Documentation

The docs/ directory contains:

• DeerFlow_Py_Technical_Documentation.pdf — 40-page comprehensive document with:

  • Part 1: Solution Document (problem, goals, approach, innovations)

  • Part 2: Architecture Design (system architecture, layered design, tech selection)

  • Part 3: Detailed Design (UML class diagram, sequence diagrams, flowcharts, memory/plugin architecture)

  • Part 4: Implementation Guide (state machine, agent runtime, tools, skills, middleware, plugins, harness)

  • Appendix: API reference, quick start, project structure

• diagrams/ — 8 high-resolution PNG diagrams:

  • System architecture, UML class diagram, research workflow sequence, ReAct flowchart, data flow, layered stack, plugin system, memory system

License

MIT
https://cdn.neusncp.com/public/file/20260729160307_rmKDWImu.pdf