DeerFlow: Deep Exploration and Efficient Research Flow

Overview

Key Architecture

System Architecture

Core Features

Agent System Architecture

Middleware Chain (Continued)

Middleware Chain (Final)

ThreadState Schema

class ThreadState(AgentState):\n    \"\"\"Extended state for DeerFlow threads\"\"\"\n    \n    # Sandbox and file system\n    sandbox: Optional[str] = None  # sandbox_id\n    thread_data: ThreadData = Field(default_factory=ThreadData)\n    \n    # Metadata and artifacts\n    title: Optional[str] = None\n    artifacts: List[Artifact] = Field(default_factory=list)\n    todos: List[Todo] = Field(default_factory=list)\n    \n    # User context\n    uploaded_files: List[str] = Field(default_factory=list)\n    viewed_images: List[str] = Field(default_factory=list)

Sandbox System

Virtual Path System

# Agent sees virtual paths:\n/mnt/user-data/{workspace,uploads,outputs}\n/mnt/skills\n\n# Physical mapping:\nbackend/.deer-flow/users/{user_id}/threads/{thread_id}/user-data/...\ndeer-flow/skills/\n\n# Translation happens in:\n# LocalSandboxProvider.build_path_mappings()\n# tools.replace_virtual_path()

Sandbox Tools

Subagent System

Subagent Task Flow

def task(subagent_type=\"general-purpose\", description, prompt):\n    \"\"\"Delegate task to subagent\"\"\"\n    # 1. Create task in registry\n    task_id = registry.create_task(\n        subagent_type=subagent_type,\n        description=description,\n        prompt=prompt\n    )\n    \n    # 2. Schedule background execution\n    executor.execute(task_id)\n    \n    # 3. Return polling interface\n    return task_id

Tool System Architecture

Tool Loading Flow

MCP Integration

MCP Configuration

extensions_config.json:\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"enabled\": true,\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"]\n    },\n    \"filesystem\": {\n      \"enabled\": true,\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\"]\n    }\n  }\n}

Skills System

Memory System

Memory Update Flow

class MemoryMiddleware:\n    def after_message(self, state: ThreadState, messages: List[Message]):\n        # Filter user inputs + final AI responses\n        filtered = [\n            msg for msg in messages\n            if msg.type == Message.USER or \n               (msg.type == Message.AI and msg.is_final)\n        ]\n        \n        # Queue for debounced background processing\n        memory_queue.enqueue(\n            user_id=get_effective_user_id(),\n            messages=filtered\n        )

Model Factory

Model Configuration Examples

# OpenAI with Responses API\n- name: gpt-5-responses\n  display_name: GPT-5 (Responses API)\n  use: langchain_openai:ChatOpenAI\n  model: gpt-5\n  use_responses_api: true\n  output_version: responses/v1\n\n# DeepSeek with thinking\n- name: deepseek-v3\n  display_name: DeepSeek V3 (Thinking)\n  use: deerflow.models.patched_deepseek:PatchedChatDeepSeek\n  model: deepseek-reasoner\n  supports_thinking: true\n  when_thinking_enabled:\n    extra_body:\n      thinking:\n        type: enabled

Configuration System

IM Channels Integration

Channel Configuration

# config.yaml channels section\nchannels:\n  langgraph_url: http://localhost:8001/api\n  gateway_url: http://localhost:8001\n  \n  telegram:\n    enabled: true\n    bot_token: $TELEGRAM_BOT_TOKEN\n    allowed_users: []  # allow all\n  \n  slack:\n    enabled: true\n    bot_token: $SLACK_BOT_TOKEN\n    app_token: $SLACK_APP_TOKEN

Embedded Client

Security Architecture

File Upload System

Upload Flow

async def upload_files(thread_id: str, files: List[UploadFile]):\n    \"\"\"Handle file upload with conversion\"\"\"\n    \n    # Thread isolation directory\n    thread_dir = get_thread_directory(thread_id)\n    \n    # Process each file\n    for file in files:\n        # Check for duplicates\n        filename = handle_duplicate_filenames(file.filename)\n        \n        # Convert documents\n        if should_convert(file.filename):\n            content = await convert_document(file.file)\n        else:\n            content = await file.read()\n        \n        # Store in thread directory\n        save_file(thread_dir, filename, content)\n    \n    return {\"success\": True, \"files\": processed_files}

Plan Mode

Context Summarization

Loop Detection

Development Workflow

Testing Architecture

Performance Optimization

Error Handling

Monitoring & Observability

Deployment Options

Docker Compose Setup

version: '3.8'\nservices:\n  gateway:\n    build: ./backend\n    ports:\n      - \"8001:8001\"\n    depends_on:\n      - provisioner\n    environment:\n      - DEER_FLOW_CONFIG_PATH=/config/config.yaml\n    volumes:\n      - ./config.yaml:/config/config.yaml\n      - ./skills:/skills\n      - ./.deer-flow:/app/.deer-flow\n  \n  provisioner:\n    build: ./backend/community/aio_sandbox\n    ports:\n      - \"8002:8002\"\n    volumes:\n      - ~/.kube:/root/.kube:ro

Comparison with Alternatives

Use Cases & Examples

Best Practices

Community & Ecosystem

Performance Benchmarks

Future Roadmap

Getting Started

Configuration Examples

Troubleshooting

Contributing Guidelines

Learning Resources

Advanced Features

Case Studies

Integration Examples

Security Deep Dive

Performance Tuning

Migration Guide

Summary

参考资料