Deerflow

DeerFlow — ByteDance Super Agent Harness

Source: bytedance/deer-flow (Apache-2.0)

Tier: TIER 2 — CORRECTNESS

Framework điều phối agent phức tạp, chạy nhiều giờ — sub-agents song song, sandbox Docker, memory dài hạn.

Do NOT use for: terminal--langgraph (raw LangGraph patterns, không phải DeerFlow framework), tencent--agent-memory (memory-only, không có orchestration).

Kiến trúc

User request
      ↓
Lead Agent (LangGraph state machine)
      ├─ spawn Sub-Agent A (research)     ← scoped context + tools + termination
      ├─ spawn Sub-Agent B (web search)   ← parallel execution
      └─ spawn Sub-Agent C (code exec)    ← Docker sandbox
             ↓
      Aggregate results
             ↓
      Persistent Memory (long-term user profile)
             ↓
      Output: report / slides / web page / code

Tech stack: Python 3.12+ · LangChain · LangGraph · TypeScript frontend · Docker · MCP servers

Cài đặt

# Yêu cầu: Python 3.12+, Node 22+, Docker (optional nhưng khuyến nghị)
git clone https://github.com/bytedance/deer-flow
cd deer-flow

# Backend
cp conf.yaml.example conf.yaml
# Chỉnh conf.yaml: LLM provider, API keys, tool configs

pip install -r requirements.txt

# Frontend
cd web
npm install
npm run build
cd ..

# Khởi động (local)
make dev
# → Backend: http://localhost:8000
# → Frontend: http://localhost:3000

# Docker (production)
docker compose up -d

Cấu hình LLM

# conf.yaml
llm:
  # Claude (Anthropic)
  provider: anthropic
  model: claude-sonnet-4-6
  api_key: ${ANTHROPIC_API_KEY}

  # Hoặc DeepSeek (chi phí thấp hơn)
  provider: deepseek
  model: deepseek-chat
  api_key: ${DEEPSEEK_API_KEY}

  # Local (Ollama / vLLM)
  provider: openai  # compatible API
  base_url: http://localhost:11434/v1
  model: llama3.2
  api_key: ollama

Sub-agent spawning

from deerflow import Agent, SubAgent

# Lead agent tự động spawn sub-agents theo task
lead = Agent(
    name="research-lead",
    max_subagents=5,       # tối đa 5 sub-agents song song
    sandbox=True,          # Docker sandbox cho code execution
    memory=True,           # persistent memory
)

# Sub-agent được spawn với scoped context
class WebResearchAgent(SubAgent):
    tools = ["web_search", "web_browse"]
    max_steps = 20
    termination = "found_sufficient_sources OR steps_exhausted"

# Run task — DeerFlow tự decompose + route
result = await lead.run(
    "Research the latest developments in LLM reasoning and write a 5000-word report"
)
# → Có thể chạy 30-60 phút
# → Output: structured report với citations

Sandbox execution

# Code được execute trong Docker container isolated
from deerflow.sandbox import DockerSandbox

sandbox = DockerSandbox(
    image="python:3.12-slim",
    volumes={
        "/uploads": "/workspace/uploads",   # read input files
        "/workspace": "/workspace/code",    # write area
        "/outputs": "/workspace/outputs",   # agent collects results
    },
    network=False,   # no outbound for sandboxed tasks
    memory_limit="512m",
    timeout=300,     # 5 phút per code execution
)

# Agent gọi sandbox khi cần execute code
result = await sandbox.run("python analysis.py --input data.csv")
# → stdout + stderr + output files

Persistent memory

from deerflow.memory import UserProfile

# Memory tự động update sau mỗi session
profile = UserProfile(user_id="tam")

# Agent đọc context từ memory
context = await profile.get_context()
# → {
#     "preferences": {"language": "vi", "report_style": "concise"},
#     "expertise": ["AI", "distributed systems", "Vietnam tech"],
#     "recent_topics": ["LLM reasoning", "agent frameworks"]
#   }

# Memory update sau session
await profile.update({
    "recent_session": "Deep research on DeerFlow architecture",
    "decisions": ["Chose DeerFlow over AutoGen for multi-hour tasks"]
})

Skills system

Built-in skills (modular, loadable):
  deep-research    — multi-source research với citations
  report-gen       — markdown/PDF report từ research results
  slide-creator    — PowerPoint/Keynote generation
  web-page-gen     — HTML page từ content
  code-analysis    — static analysis + refactoring suggestions

Custom skill template:
  deerflow/skills/my-skill/
    __init__.py
    skill.yaml     # name, description, tools required
    handler.py     # async def run(context, inputs) → outputs

IM channel integration

# conf.yaml — kết nối vào team chat
integrations:
  telegram:
    bot_token: ${TELEGRAM_BOT_TOKEN}
    allowed_users: ["tam_username"]

  slack:
    bot_token: ${SLACK_BOT_TOKEN}
    app_token: ${SLACK_APP_TOKEN}

  feishu:              # Lark — phổ biến ở ByteDance internals
    app_id: ${FEISHU_APP_ID}
    app_secret: ${FEISHU_APP_SECRET}

Observability

# LangSmith tracing (debug agent reasoning)
import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "ls__..."

# Langfuse (self-hosted alternative)
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."

Security — local deployment

⚠ ByteDance's own warning:
  "Deploy only in trusted networks by default"
  "For public deployment: add IP allowlist + authentication gateway"

Recommended setup:
  □ Behind VPN or internal network
  □ Nginx reverse proxy với basic auth
  □ Docker network isolation (no --network=host)
  □ Sandbox code execution (Docker-in-Docker cần cẩn thận)

So sánh với các framework khác

Anti-Fake-Pass Checks

❌ FAIL nếu dùng cho simple 1-turn tasks (overkill — dùng direct API call)
❌ FAIL nếu sandbox không isolate network khi execute untrusted code
❌ FAIL nếu persistent memory không update sau session (stale profile)
❌ FAIL nếu sub-agents vượt max_subagents limit (resource exhaustion)
✅ PASS khi: lead agent hoàn thành 10-step research task trong 1 run
✅ PASS khi: memory profile persist đúng sau restart (check DB file)

See also

• terminal--langgraph — raw LangGraph patterns (DeerFlow builds on top)
• tencent--agent-memory — memory hierarchy chi tiết (bổ sung cho DeerFlow memory)
• subagent-policy.md — Yana AI subagent spawn rules (khác DeerFlow model)
• 04-sandbox-isolation-law.md — sandbox isolation requirements