DeerFlow

Overview

DeerFlow is an open-source long-horizon SuperAgent harness developed by ByteDance that researches, codes, and creates using sandboxes, memory, tools, skills, subagents, and a message gateway to handle tasks spanning minutes to hours. Unlike traditional agent frameworks focused on single-turn interactions, DeerFlow is designed for extended autonomous workflows where agents need to maintain context, decompose complex goals, and recover from failures over long execution periods.

The framework provides a complete infrastructure for building production-grade autonomous agents, including isolated sandbox environments for safe tool execution, persistent memory systems for long-term context retention, and a modular skills system that allows agents to load capabilities on-demand.

DeerFlow has gained significant traction in the AI agent community with over 74,000 GitHub stars, reflecting its appeal to developers building serious autonomous agent applications.

Features

• Long-Horizon Execution: Designed for tasks that span minutes to hours with automatic context management and recovery
• Sandbox Environments: Isolated execution environments for safe tool and code execution
• Skills System: Modular capabilities (research, report generation, code review) loaded on-demand
• Sub-Agent Orchestration: Parallel task decomposition with isolated contexts for each sub-agent
• Persistent Memory: Long-term memory system for user profiles, preferences, and conversation history
• Message Gateway: Unified communication layer supporting multiple channels (Telegram, Slack, web UI)
• Context Engineering: Automatic summarization and strict tool-call recovery for long-running tasks
• Observability: Integration with LangSmith and Langfuse for tracing and monitoring
• Multi-Modal Support: Handles text, images, code, and other content types
• Web UI: Built-in web interface at http://localhost:2026 for monitoring and interaction

Installation

Prerequisites

• Python 3.10+
• Docker and Docker Compose
• Make

Quick Install

# Clone the repository
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# Run setup
make setup

# Start with Docker
make docker-start

# Or for local development
make dev

Configuration

DeerFlow uses environment variables and configuration files for setup. Key configuration options include:

# Model provider configuration
export DEERFLOW_MODEL_PROVIDER=anthropic
export DEERFLOW_API_KEY=your-api-key

# Memory backend
export DEERFLOW_MEMORY_BACKEND=sqlite

# Sandbox configuration
export DEERFLOW_SANDBOX_TYPE=docker

See the Configuration Guide for all options.

Quick Start

Basic Agent Definition

from deerflow import Agent, Skill, Sandbox

# Create a research agent
research_agent = Agent(
    name="researcher",
    model="claude-sonnet-4-6",
    skills=["web_search", "document_analysis"],
    sandbox=Sandbox(type="docker"),
    instructions="""
    You are a research agent. Your job is to:
    1. Search for relevant information
    2. Analyze and synthesize findings
    3. Generate a comprehensive report
    """
)

# Run a research task
result = research_agent.run(
    task="Research the latest developments in AI agent frameworks",
    max_steps=50
)

print(result.summary)

Multi-Agent Workflow

from deerflow import AgentGroup, Task

# Define specialized agents
researcher = Agent(name="researcher", skills=["web_search"])
writer = Agent(name="writer", skills=["content_generation"])
reviewer = Agent(name="reviewer", skills=["quality_assurance"])

# Create agent group
team = AgentGroup(
    agents=[researcher, writer, reviewer],
    coordination_strategy="sequential"
)

# Define workflow
workflow = Task(
    name="research_report",
    description="Create a comprehensive research report",
    steps=[
        "Research: Gather information from multiple sources",
        "Write: Draft the report with citations",
        "Review: Check for accuracy and completeness"
    ]
)

# Execute
result = team.execute(workflow)

Core Concepts

Long-Horizon Tasks

DeerFlow excels at tasks that require extended execution time. The framework automatically manages context windows through summarization, allowing agents to work on problems that would exceed typical token limits.

Skills and Tools

Skills are reusable capabilities that can be loaded on-demand. Each skill defines a set of tools and behaviors that extend the agent's capabilities. Skills can be shared across agents and composed for complex workflows.

Sandboxes

Sandbox environments provide isolated execution contexts for agent tools. This ensures that agent actions don't affect the host system and allows for safe experimentation with code execution, file operations, and network access.

Memory System

The persistent memory system maintains context across sessions, allowing agents to remember user preferences, previous conversations, and learned patterns. This is crucial for building agents that provide consistent, personalized experiences over time.

Advanced Features

Context Engineering

DeerFlow implements sophisticated context management strategies:

• Automatic Summarization: Long conversation histories are summarized to fit within context windows
• Tool-Call Recovery: Failed tool calls are automatically retried with adjusted parameters
• Priority Context: Important information is preserved even during context compression

Sub-Agent Orchestration

Complex tasks are decomposed into sub-tasks handled by specialized sub-agents. Each sub-agent operates in an isolated context, preventing interference and allowing for parallel execution where possible.

Message Gateway

The message gateway provides a unified interface for agent communication across multiple channels:

• Web UI (http://localhost:2026)
• Telegram bot
• Slack integration
• REST API
• CLI interface

Observability

DeerFlow integrates with popular observability tools:

• LangSmith: Trace agent execution and debug workflows
• Langfuse: Monitor agent performance and costs
• Custom Metrics: Export metrics to your preferred monitoring system

Examples

Research and Report Generation

from deerflow import Agent, Skill

agent = Agent(
    name="research_reporter",
    skills=["web_search", "document_analysis", "report_generation"],
    instructions="""
    Research the given topic thoroughly and generate a detailed report.
    Include sources, analysis, and recommendations.
    """
)

result = agent.run(
    task="Research developments in multi-agent systems for 2026",
    output_format="markdown"
)

# Save report
with open("report.md", "w") as f:
    f.write(result.content)

Code Review Agent

from deerflow import Agent

code_reviewer = Agent(
    name="code_reviewer",
    skills=["git_operations", "code_analysis", "security_scan"],
    instructions="""
    Review code changes for:
    - Bugs and potential issues
    - Security vulnerabilities
    - Performance concerns
    - Code style and best practices
    """
)

result = code_reviewer.run(
    task="Review the latest changes in branch 'feature/new-agent'",
    repo_path="/path/to/repo"
)

Autonomous Coding Agent

from deerflow import Agent, Sandbox

coder = Agent(
    name="autonomous_coder",
    skills=["code_generation", "testing", "debugging"],
    sandbox=Sandbox(type="docker", resources={"cpu": 2, "memory": "4Gi"}),
    instructions="""
    Implement the requested feature with:
    1. Clear code structure
    2. Comprehensive tests
    3. Documentation
    4. Error handling
    """
)

result = coder.run(
    task="Implement a new MCP server for GitHub integration",
    max_steps=100
)

Pros

• ✅ Designed specifically for long-horizon autonomous tasks
• ✅ Robust sandbox system for safe execution
• ✅ Excellent context management for extended sessions
• ✅ Modular skills system for extensibility
• ✅ Strong observability and debugging support
• ✅ Active development with large community (74k+ stars)
• ✅ Multi-channel communication support
• ✅ Production-ready architecture

Cons

• ❌ Steeper learning curve than simpler frameworks
• ❌ Requires Docker for sandbox features
• ❌ Higher resource requirements due to sandbox overhead
• ❌ Documentation still evolving with rapid development
• ❌ Primarily Python-focused (limited TypeScript support)

When to Use

DeerFlow is ideal for:

• Long-running autonomous tasks that need to maintain context over hours
• Research and analysis workflows requiring extensive information gathering
• Code generation and review with safe sandboxed execution
• Multi-agent systems where agents need to collaborate on complex goals
• Production deployments requiring observability and reliability
• Applications needing persistent memory across sessions

Consider simpler frameworks like CrewAI or LangGraph for:

• Short, single-turn agent interactions
• Prototyping and experimentation
• Simple multi-agent conversations
• Projects with limited resources

Resources

• Official Website
• GitHub Repository
• Documentation
• Configuration Guide
• Architecture Overview
• Contributing Guide